Context Navigation

source: GTP/trunk/App/Demos/Geom/OgreStuff/include/CEGUI/elements/CEGUIMultiColumnList.h @ 1092

Revision 1092, 43.7 KB checked in by gumbau, 18 years ago (diff)
LodStrips? and LODTrees demos

Line
1	/************************************************************************
2	filename: CEGUIMultiColumnList.h
3	created: 13/4/2004
4	author: Paul D Turner
5
6	purpose: Interface to base class for MultiColumnList widget
7	*************************************************************************/
8	/*************************************************************************
9	Crazy Eddie's GUI System (http://www.cegui.org.uk)
10	Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
11
12	This library is free software; you can redistribute it and/or
13	modify it under the terms of the GNU Lesser General Public
14	License as published by the Free Software Foundation; either
15	version 2.1 of the License, or (at your option) any later version.
16
17	This library is distributed in the hope that it will be useful,
18	but WITHOUT ANY WARRANTY; without even the implied warranty of
19	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20	Lesser General Public License for more details.
21
22	You should have received a copy of the GNU Lesser General Public
23	License along with this library; if not, write to the Free Software
24	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25	*************************************************************************/
26	#ifndef _CEGUIMultiColumnList_h_
27	#define _CEGUIMultiColumnList_h_
28
29	#include "CEGUIBase.h"
30	#include "CEGUIWindow.h"
31	#include "CEGUIListHeader.h"
32	#include "elements/CEGUIMultiColumnListProperties.h"
33
34
35	#if defined(_MSC_VER)
36	# pragma warning(push)
37	# pragma warning(disable : 4251)
38	#endif
39
40
41	// Start of CEGUI namespace section
42	namespace CEGUI
43	{
44
45	/*!
46	\brief
47	Simple grid index structure.
48	*/
49	struct CEGUIEXPORT MCLGridRef
50	{
51	MCLGridRef(uint r, uint c) : row(r), column(c) {}
52
53	uint row; //!< Zero based row index.
54	uint column; //!< Zero based column index.
55
56	// operators
57	MCLGridRef& operator=(const MCLGridRef& rhs);
58	bool operator<(const MCLGridRef& rhs) const;
59	bool operator<=(const MCLGridRef& rhs) const;
60	bool operator>(const MCLGridRef& rhs) const;
61	bool operator>=(const MCLGridRef& rhs) const;
62	bool operator==(const MCLGridRef& rhs) const;
63	bool operator!=(const MCLGridRef& rhs) const;
64	};
65
66
67	/*!
68	\brief
69	Base class for the multi column list widget.
70	*/
71	class CEGUIEXPORT MultiColumnList : public Window
72	{
73	public:
74	static const String EventNamespace; //!< Namespace for global events
75
76
77	/*************************************************************************
78	Constants
79	*************************************************************************/
80	// Event names
81	static const String EventSelectionModeChanged; //!< Event fired when the selection mode for the list box changes.
82	static const String EventNominatedSelectColumnChanged;//!< Event fired when the nominated select column changes.
83	static const String EventNominatedSelectRowChanged; //!< Event fired when the nominated select row changes.
84	static const String EventVertScrollbarModeChanged; //!< Event fired when the vertical scroll bar 'force' setting changes.
85	static const String EventHorzScrollbarModeChanged; //!< Event fired when the horizontal scroll bar 'force' setting changes.
86	static const String EventSelectionChanged; //!< Event fired when the current selection(s) within the list box changes.
87	static const String EventListContentsChanged; //!< Event fired when the contents of the list box changes.
88	static const String EventSortColumnChanged; //!< Event fired when the sort column changes.
89	static const String EventSortDirectionChanged; //!< Event fired when the sort direction changes.
90	static const String EventListColumnSized; //!< Event fired when the width of a column in the list changes.
91	static const String EventListColumnMoved; //!< Event fired when the column order changes.
92
93
94	/*************************************************************************
95	Enumerations
96	*************************************************************************/
97	/*!
98	\brief
99	Enumerated values for the selection modes possible with a Multi-column list
100	*/
101	enum SelectionMode
102	{
103	RowSingle, // Any single row may be selected. All items in the row are selected.
104	RowMultiple, // Multiple rows may be selected. All items in the row are selected.
105	CellSingle, // Any single cell may be selected.
106	CellMultiple, // Multiple cells bay be selected.
107	NominatedColumnSingle, // Any single item in a nominated column may be selected.
108	NominatedColumnMultiple, // Multiple items in a nominated column may be selected.
109	ColumnSingle, // Any single column may be selected. All items in the column are selected.
110	ColumnMultiple, // Multiple columns may be selected. All items in the column are selected.
111	NominatedRowSingle, // Any single item in a nominated row may be selected.
112	NominatedRowMultiple // Multiple items in a nominated row may be selected.
113	};
114
115
116	/*************************************************************************
117	Accessor Methods
118	*************************************************************************/
119	/*!
120	\brief
121	Return whether user manipulation of the sort column and direction are enabled.
122
123	\return
124	true if the user may interactively modify the sort column and direction. false if the user may not
125	modify the sort column and direction (these can still be set programmatically).
126	*/
127	bool isUserSortControlEnabled(void) const;
128
129
130	/*!
131	\brief
132	Return whether the user may size column segments.
133
134	\return
135	true if the user may interactively modify the width of columns, false if they may not.
136	*/
137	bool isUserColumnSizingEnabled(void) const;
138
139
140	/*!
141	\brief
142	Return whether the user may modify the order of the columns.
143
144	\return
145	true if the user may interactively modify the order of the columns, false if they may not.
146	*/
147	bool isUserColumnDraggingEnabled(void) const;
148
149
150	/*!
151	\brief
152	Return the number of columns in the multi-column list
153
154	\return
155	uint value equal to the number of columns in the list.
156	*/
157	uint getColumnCount(void) const;
158
159
160	/*!
161	\brief
162	Return the number of rows in the multi-column list.
163
164	\return
165	uint value equal to the number of rows currently in the list.
166	*/
167	uint getRowCount(void) const;
168
169
170	/*!
171	\brief
172	Return the zero based index of the current sort column. There must be at least one column to successfully call this
173	method.
174
175	\return
176	Zero based column index that is the current sort column.
177
178	\exception InvalidRequestException thrown if there are no columns in this multi column list.
179	*/
180	uint getSortColumn(void) const;
181
182
183	/*!
184	\brief
185	Return the zero based column index of the column with the specified ID.
186
187	\param col_id
188	ID code of the column whos index is to be returned.
189
190	\return
191	Zero based column index of the first column whos ID matches \a col_id.
192
193	\exception InvalidRequestException thrown if no attached column has the requested ID.
194	*/
195	uint getColumnWithID(uint col_id) const;
196
197
198	/*!
199	\brief
200	Return the zero based index of the column whos header text matches the specified text.
201
202	\param text
203	String object containing the text to be searched for.
204
205	\return
206	Zero based column index of the column whos header has the specified text.
207
208	\exception InvalidRequestException thrown if no columns header has the requested text.
209	*/
210	uint getColumnWithHeaderText(const String& text) const;
211
212
213	/*!
214	\brief
215	Return the total width of all column headers.
216
217	\return
218	Sum total of all the column header widths in whichever metrics system is active.
219	*/
220	float getTotalColumnHeadersWidth(void) const;
221
222
223	/*!
224	\brief
225	Return the width of the specified column header (and therefore the column itself).
226
227	\param col_idx
228	Zero based column index of the column whos width is to be returned.
229
230	\return
231	Width of the column header at the zero based column index specified by \a col_idx, in whichever is the active metrics system.
232
233	\exception InvalidRequestException thrown if \a column is out of range.
234	*/
235	float getColumnHeaderWidth(uint col_idx) const;
236
237
238	/*!
239	\brief
240	Return the currently set sort direction.
241
242	\return
243	One of the ListHeaderSegment::SortDirection enumerated values specifying the current sort direction.
244	*/
245	ListHeaderSegment::SortDirection getSortDirection(void) const;
246
247
248	/*!
249	\brief
250	Return the ListHeaderSegment object for the specified column
251
252	\param col_idx
253	zero based index of the column whos ListHeaderSegment is to be returned.
254
255	\return
256	ListHeaderSegment object for the column at the requested index.
257
258	\exception InvalidRequestException thrown if \a col_idx is out of range.
259	*/
260	ListHeaderSegment& getHeaderSegmentForColumn(uint col_idx) const;
261
262
263	/*!
264	\brief
265	Return the zero based index of the Row that contains \a item.
266
267	\param item
268	Pointer to the ListboxItem that the row index is to returned for.
269
270	\return
271	Zero based index of the row that contains ListboxItem \a item.
272
273	\exception InvalidRequestException thrown if \a item is not attached to the list box.
274	*/
275	uint getItemRowIndex(const ListboxItem* item) const;
276
277
278	/*!
279	\brief
280	Return the current zero based index of the column that contains \a item.
281
282	\param item
283	Pointer to the ListboxItem that the column index is to returned for.
284
285	\return
286	Zero based index of the column that contains ListboxItem \a item.
287
288	\exception InvalidRequestException thrown if \a item is not attached to the list box.
289	*/
290	uint getItemColumnIndex(const ListboxItem* item) const;
291
292
293	/*!
294	\brief
295	Return the grid reference for \a item.
296
297	\param item
298	Pointer to the ListboxItem whos current grid reference is to be returned.
299
300	\return
301	MCLGridRef object describing the current grid reference of ListboxItem \a item.
302
303	\exception InvalidRequestException thrown if \a item is not attached to the list box.
304	*/
305	MCLGridRef getItemGridReference(const ListboxItem* item) const;
306
307
308	/*!
309	\brief
310	Return a pointer to the ListboxItem at the specified grid reference.
311
312	\param grid_ref
313	MCLGridRef object that describes the position of the ListboxItem to be returned.
314
315	\return
316	Pointer to the ListboxItem at grid reference \a grid_ref.
317
318	\exception InvalidRequestException thrown if \a grid_ref is invalid for this list box.
319	*/
320	ListboxItem* getItemAtGridReference(const MCLGridRef& grid_ref) const;
321
322
323	/*!
324	\brief
325	return whether ListboxItem \a item is attached to the column at index \a col_idx.
326
327	\param item
328	Pointer to the ListboxItem to look for.
329
330	\param col_idx
331	Zero based index of the column that is to be searched.
332
333	\return
334	- true if \a item is attached to list box column \a col_idx.
335	- false if \a item is not attached to list box column \a col_idx.
336
337	\exception InvalidRequestException thrown if \a col_idx is out of range.
338	*/
339	bool isListboxItemInColumn(const ListboxItem* item, uint col_idx) const;
340
341
342	/*!
343	\brief
344	return whether ListboxItem \a item is attached to the row at index \a row_idx.
345
346	\param item
347	Pointer to the ListboxItem to look for.
348
349	\param row_idx
350	Zero based index of the row that is to be searched.
351
352	\return
353	- true if \a item is attached to list box row \a row_idx.
354	- false if \a item is not attached to list box row \a row_idx.
355
356	\exception InvalidRequestException thrown if \a row_idx is out of range.
357	*/
358	bool isListboxItemInRow(const ListboxItem* item, uint row_idx) const;
359
360
361	/*!
362	\brief
363	return whether ListboxItem \a item is attached to the list box.
364
365	\param item
366	Pointer to the ListboxItem to look for.
367
368	\return
369	- true if \a item is attached to list box.
370	- false if \a item is not attached to list box.
371	*/
372	bool isListboxItemInList(const ListboxItem* item) const;
373
374
375	/*!
376	\brief
377	Return the ListboxItem in column \a col_idx that has the text string \a text.
378
379	\param text
380	String object containing the text to be searched for.
381
382	\param col_idx
383	Zero based index of the column to be searched.
384
385	\param start_item
386	Pointer to the ListboxItem where the exclusive search is to start, or NULL to search from the top of the column.
387
388	\return
389	Pointer to the first ListboxItem in column \a col_idx, after \a start_item, that has the string \a text.
390
391	\exception InvalidRequestException thrown if \a start_item is not attached to the list box, or if \a col_idx is out of range.
392	*/
393	ListboxItem* findColumnItemWithText(const String& text, uint col_idx, const ListboxItem* start_item) const;
394
395
396	/*!
397	\brief
398	Return the ListboxItem in row \a row_idx that has the text string \a text.
399
400	\param text
401	String object containing the text to be searched for.
402
403	\param row_idx
404	Zero based index of the row to be searched.
405
406	\param start_item
407	Pointer to the ListboxItem where the exclusive search is to start, or NULL to search from the start of the row.
408
409	\return
410	Pointer to the first ListboxItem in row \a row_idx, after \a start_item, that has the string \a text.
411
412	\exception InvalidRequestException thrown if \a start_item is not attached to the list box, or if \a row_idx is out of range.
413	*/
414	ListboxItem* findRowItemWithText(const String& text, uint row_idx, const ListboxItem* start_item) const;
415
416
417	/*!
418	\brief
419	Return the ListboxItem that has the text string \a text.
420
421	\note
422	List box searching progresses across the columns in each row.
423
424	\param text
425	String object containing the text to be searched for.
426
427	\param start_item
428	Pointer to the ListboxItem where the exclusive search is to start, or NULL to search the whole list box.
429
430	\return
431	Pointer to the first ListboxItem, after \a start_item, that has the string \a text.
432
433	\exception InvalidRequestException thrown if \a start_item is not attached to the list box.
434	*/
435	ListboxItem* findListItemWithText(const String& text, const ListboxItem* start_item) const;
436
437
438	/*!
439	\brief
440	Return a pointer to the first selected ListboxItem attached to this list box.
441
442	\note
443	List box searching progresses across the columns in each row.
444
445	\return
446	Pointer to the first ListboxItem attached to this list box that is selected, or NULL if no item is selected.
447	*/
448	ListboxItem* getFirstSelectedItem(void) const;
449
450
451	/*!
452	\brief
453	Return a pointer to the next selected ListboxItem after \a start_item.
454
455	\note
456	List box searching progresses across the columns in each row.
457
458	\param start_item
459	Pointer to the ListboxItem where the exclusive search is to start, or NULL to search the whole list box.
460
461	\return
462	Pointer to the first selected ListboxItem attached to this list box, after \a start_item, or NULL if no item is selected.
463
464	\exception InvalidRequestException thrown if \a start_item is not attached to the list box.
465	*/
466	ListboxItem* getNextSelected(const ListboxItem* start_item) const;
467
468
469	/*!
470	\brief
471	Return the number of selected ListboxItems attached to this list box.
472
473	return
474	uint value equal to the number of ListboxItems attached to this list box that are currently selected.
475	*/
476	uint getSelectedCount(void) const;
477
478
479	/*!
480	\brief
481	Return whether the ListboxItem at \a grid_ref is selected.
482
483	\param grid_ref
484	MCLGridRef object describing the grid reference that is to be examined.
485
486	\return
487	- true if there is a ListboxItem at \a grid_ref and it is selected.
488	- false if there is no ListboxItem at \a grid_ref, or if the item is not selected.
489
490	\exception InvalidRequestException thrown if \a grid_ref contains an invalid grid position.
491	*/
492	bool isItemSelected(const MCLGridRef& grid_ref) const;
493
494
495	/*!
496	\brief
497	Return the ID of the currently set nominated selection column to be used when in one of the NominatedColumn*
498	selection modes.
499
500	\note
501	You should only ever call this when getColumnCount() returns > 0.
502
503	\return
504	ID code of the nominated selection column.
505	*/
506	uint getNominatedSelectionColumnID(void) const;
507
508
509	/*!
510	\brief
511	Return the index of the currently set nominated selection column to be used when in one of the NominatedColumn*
512	selection modes.
513
514	\return
515	Zero based index of the nominated selection column.
516	*/
517	uint getNominatedSelectionColumn(void) const;
518
519
520	/*!
521	\brief
522	Return the index of the currently set nominated selection row to be used when in one of the NominatedRow*
523	selection modes.
524
525	\return
526	Zero based index of the nominated selection column.
527	*/
528	uint getNominatedSelectionRow(void) const;
529
530
531	/*!
532	\brief
533	Return the currently set selection mode.
534
535	\return
536	One of the MultiColumnList::SelectionMode enumerated values specifying the current selection mode.
537	*/
538	MultiColumnList::SelectionMode getSelectionMode(void) const;
539
540
541	/*!
542	\brief
543	Return whether the vertical scroll bar is always shown.
544
545	\return
546	- true if the scroll bar will always be shown even if it is not required.
547	- false if the scroll bar will only be shown when it is required.
548	*/
549	bool isVertScrollbarAlwaysShown(void) const;
550
551
552	/*!
553	\brief
554	Return whether the horizontal scroll bar is always shown.
555
556	\return
557	- true if the scroll bar will always be shown even if it is not required.
558	- false if the scroll bar will only be shown when it is required.
559	*/
560	bool isHorzScrollbarAlwaysShown(void) const;
561
562
563	/*!
564	\brief
565	Return the ID code assigned to the requested column.
566
567	\param col_idx
568	Zero based index of the column whos ID code is to be returned.
569
570	\return
571	Current ID code assigned to the column at the requested index.
572
573	\exception InvalidRequestException thrown if \a col_idx is out of range
574	*/
575	uint getColumnID(uint col_idx) const;
576
577
578	/*!
579	\brief
580	Return the ID code assigned to the requested row.
581
582	\param row_idx
583	Zero based index of the row who's ID code is to be returned.
584
585	\return
586	Current ID code assigned to the row at the requested index.
587
588	\exception InvalidRequestException thrown if \a row_idx is out of range
589	*/
590	uint getRowID(uint row_idx) const;
591
592
593	/*!
594	\brief
595	Return the zero based row index of the row with the specified ID.
596
597	\param row_id
598	ID code of the row who's index is to be returned.
599
600	\return
601	Zero based row index of the first row who's ID matches \a row_id.
602
603	\exception InvalidRequestException thrown if no row has the requested ID.
604	*/
605	uint getRowWithID(uint row_id) const;
606
607
608	/*************************************************************************
609	Manipulator Methods
610	*************************************************************************/
611	/*!
612	\brief
613	Initialise the Window based object ready for use.
614
615	\note
616	This must be called for every window created. Normally this is handled automatically by the WindowFactory for each Window type.
617
618	\return
619	Nothing
620	*/
621	virtual void initialise(void);
622
623
624	/*!
625	\brief
626	Remove all items from the list.
627
628	Note that this will cause 'AutoDelete' items to be deleted.
629	*/
630	void resetList(void);
631
632
633	/*!
634	\brief
635	Add a column to the list box.
636
637	\param text
638	String object containing the text label for the column header.
639
640	\param col_id
641	ID code to be assigned to the column header.
642
643	\param width
644	Initial width to be set for the column using the active metrics mode for this window.
645
646	\return
647	Nothing.
648	*/
649	void addColumn(const String& text, uint col_id, float width);
650
651
652	/*!
653	\brief
654	Insert a new column in the list.
655
656	\param text
657	String object containing the text label for the column header.
658
659	\param col_id
660	ID code to be assigned to the column header.
661
662	\param width
663	Initial width to be set for the column using the active metrics mode for this window.
664
665	\param position
666	Zero based index where the column is to be inserted. If this is greater than the current
667	number of columns, the new column is inserted at the end.
668
669	\return
670	Nothing.
671	*/
672	void insertColumn(const String& text, uint col_id, float width, uint position);
673
674
675	/*!
676	\brief
677	Removes a column from the list box. This will cause any ListboxItem using the autoDelete option in the column to be deleted.
678
679	\param col_idx
680	Zero based index of the column to be removed.
681
682	\return
683	Nothing.
684
685	\exception InvalidRequestException thrown if \a col_idx is invalid.
686	*/
687	void removeColumn(uint col_idx);
688
689
690	/*!
691	\brief
692	Removes a column from the list box. This will cause any ListboxItem using the autoDelete option in the column to be deleted.
693
694	\param col_id
695	ID code of the column to be deleted.
696
697	\return
698	Nothing.
699
700	\exception InvalidRequestException thrown if no column with \a col_id is available on this list box.
701	*/
702	void removeColumnWithID(uint col_id);
703
704
705	/*!
706	\brief
707	Move the column at index \a col_idx so it is at index \a position.
708
709	\param col_idx
710	Zero based index of the column to be moved.
711
712	\param position
713	Zero based index of the new position for the column.
714
715	\return
716	Nothing.
717
718	\exception InvalidRequestException thrown if \a col_idx is invalid.
719	*/
720	void moveColumn(uint col_idx, uint position);
721
722
723	/*!
724	\brief
725	Move the column with ID \a col_id so it is at index \a position.
726
727	\param col_id
728	ID code of the column to be moved.
729
730	\param position
731	Zero based index of the new position for the column.
732
733	\return
734	Nothing.
735
736	\exception InvalidRequestException thrown if no column with \a col_id is available on this list box.
737	*/
738	void moveColumnWithID(uint col_id, uint position);
739
740
741	/*!
742	\brief
743	Add an empty row to the list box.
744
745	\param row_id
746	ID code to be assigned to the new row.
747
748	\note
749	If the list is being sorted, the new row will appear at an appropriate position according to the sorting being
750	applied. If no sorting is being done, the new row will appear at the bottom of the list.
751
752	\return
753	Initial zero based index of the new row.
754	*/
755	uint addRow(uint row_id = 0);
756
757
758	/*!
759	\brief
760	Add a row to the list box, and set the item in the column with ID \a col_id to \a item.
761
762	\note
763	If the list is being sorted, the new row will appear at an appropriate position according to the sorting being
764	applied. If no sorting is being done, the new row will appear at the bottom of the list.
765
766	\param item
767	Pointer to a ListboxItem to be used as the initial contents for the column with ID \a col_id.
768
769	\param col_id
770	ID code of the column whos initial item is to be set to \a item.
771
772	\param row_id
773	ID code to be assigned to the new row.
774
775	\return
776	Initial zero based index of the new row.
777
778	\exception InvalidRequestException thrown if no column with the specified ID is attached to the list box.
779	*/
780	uint addRow(ListboxItem* item, uint col_id, uint row_id = 0);
781
782
783	/*!
784	\brief
785	Insert an empty row into the list box.
786
787	\note
788	If the list is being sorted, the new row will appear at an appropriate position according to the sorting being
789	applied. If no sorting is being done, the new row will appear at the specified index.
790
791	\param row_idx
792	Zero based index where the row should be inserted. If this is greater than the current number of rows, the row is
793	appended to the list.
794
795	\param row_id
796	ID code to be assigned to the new row.
797
798	\return
799	Zero based index where the row was actually inserted.
800	*/
801	uint insertRow(uint row_idx, uint row_id = 0);
802
803
804	/*!
805	\brief
806	Insert a row into the list box, and set the item in the column with ID \a col_id to \a item.
807
808	\note
809	If the list is being sorted, the new row will appear at an appropriate position according to the sorting being
810	applied. If no sorting is being done, the new row will appear at the specified index.
811
812	\param item
813	Pointer to a ListboxItem to be used as the initial contents for the column with ID \a col_id.
814
815	\param col_id
816	ID code of the column whos initial item is to be set to \a item.
817
818	\param row_idx
819	Zero based index where the row should be inserted. If this is greater than the current number of rows, the row is
820	appended to the list.
821
822	\param row_id
823	ID code to be assigned to the new row.
824
825	\return
826	Zero based index where the row was actually inserted.
827
828	\exception InvalidRequestException thrown if no column with the specified ID is attached to the list box.
829	*/
830	uint insertRow(ListboxItem* item, uint col_id, uint row_idx, uint row_id = 0);
831
832
833	/*!
834	\brief
835	Remove the list box row with index \a row_idx. Any ListboxItem in row \a row_idx using autoDelete mode will be deleted.
836
837	\param row_idx
838	Zero based index of the row to be removed.
839
840	\return
841	Nothing.
842
843	\exception InvalidRequestException thrown if \a row_idx is invalid.
844	*/
845	void removeRow(uint row_idx);
846
847
848	/*!
849	\brief
850	Set the ListboxItem for grid reference \a position.
851
852	\param item
853	Pointer to the ListboxItem to be set at \a position.
854
855	\param position
856	MCLGridRef describing the grid reference of the item to be set.
857
858	\return
859	Nothing.
860
861	\exception InvalidRequestException thrown if \a position contains an invalid grid reference.
862	*/
863	void setItem(ListboxItem* item, const MCLGridRef& position);
864
865
866	/*!
867	\brief
868	Set the ListboxItem for the column with ID \a col_id in row \a row_idx.
869
870	\param item
871	Pointer to the ListboxItem to be set into the list.
872
873	\param col_id
874	ID code of the column to receive \a item.
875
876	\param row_idx
877	Zero based index of the row to receive \a item.
878
879	\return
880	Nothing.
881
882	\exception InvalidRequestException thrown if no column with ID \a col_id exists, or of \a row_idx is out of range.
883	*/
884	void setItem(ListboxItem* item, uint col_id, uint row_idx);
885
886
887	/*!
888	\brief
889	Set the selection mode for the list box.
890
891	\param sel_mode
892	One of the MultiColumnList::SelectionMode enumerated values specifying the selection mode to be used.
893
894	\return
895	Nothing.
896
897	\exception InvalidRequestException thrown if the value specified for \a sel_mode is invalid.
898	*/
899	void setSelectionMode(MultiColumnList::SelectionMode sel_mode);
900
901
902	/*!
903	\brief
904	Set the column to be used for the NominatedColumn* selection modes.
905
906	\param col_id
907	ID code of the column to be used in NominatedColumn* selection modes.
908
909	\return
910	Nothing.
911
912	\exception InvalidRequestException thrown if no column has ID code \a col_id.
913	*/
914	void setNominatedSelectionColumnID(uint col_id);
915
916
917	/*!
918	\brief
919	Set the column to be used for the NominatedColumn* selection modes.
920
921	\param col_idx
922	zero based index of the column to be used in NominatedColumn* selection modes.
923
924	\return
925	Nothing.
926
927	\exception InvalidRequestException thrown if \a col_idx is out of range.
928	*/
929	void setNominatedSelectionColumn(uint col_idx);
930
931
932	/*!
933	\brief
934	Set the row to be used for the NominatedRow* selection modes.
935
936	\param row_idx
937	zero based index of the row to be used in NominatedRow* selection modes.
938
939	\return
940	Nothing.
941
942	\exception InvalidRequestException thrown if \a row_idx is out of range.
943	*/
944	void setNominatedSelectionRow(uint row_idx);
945
946
947	/*!
948	\brief
949	Set the sort direction to be used.
950
951	\param direction
952	One of the ListHeaderSegment::SortDirection enumerated values specifying the sort direction to be used.
953
954	\return
955	Nothing.
956	*/
957	void setSortDirection(ListHeaderSegment::SortDirection direction);
958
959
960	/*!
961	\brief
962	Set the column to be used as the sort key.
963
964	\param col_idx
965	Zero based index of the column to use as the key when sorting the list items.
966
967	\return
968	Nothing.
969
970	\exception InvalidRequestException thrown if col_idx is out of range.
971	*/
972	void setSortColumn(uint col_idx);
973
974
975	/*!
976	\brief
977	Set the column to be used as the sort key.
978
979	\param col_id
980	ID code of the column to use as the key when sorting the list items.
981
982	\return
983	Nothing.
984
985	\exception InvalidRequestException thrown if col_id is invalid for this list box.
986	*/
987	void setSortColumnByID(uint col_id);
988
989
990	/*!
991	\brief
992	Set whether the vertical scroll bar should always be shown, or just when needed.
993
994	\param setting
995	- true to have the vertical scroll bar shown at all times.
996	- false to have the vertical scroll bar appear only when needed.
997
998	\return
999	Nothing.
1000	*/
1001	void setShowVertScrollbar(bool setting);
1002
1003
1004	/*!
1005	\brief
1006	Set whether the horizontal scroll bar should always be shown, or just when needed.
1007
1008	\param setting
1009	- true to have the horizontal scroll bar shown at all times.
1010	- false to have the horizontal scroll bar appear only when needed.
1011
1012	\return
1013	Nothing.
1014	*/
1015	void setShowHorzScrollbar(bool setting);
1016
1017
1018	/*!
1019	\brief
1020	Removed the selected state from any currently selected ListboxItem attached to the list.
1021
1022	\return
1023	Nothing.
1024	*/
1025	void clearAllSelections(void);
1026
1027
1028	/*!
1029	\brief
1030	Sets or clears the selected state of the given ListboxItem which must be attached to the list.
1031
1032	\note
1033	Depending upon the current selection mode, this may cause other items to be selected, other
1034	items to be deselected, or for nothing to actually happen at all.
1035
1036	\param item
1037	Pointer to the attached ListboxItem to be affected.
1038
1039	\param state
1040	- true to put the ListboxItem into the selected state.
1041	- false to put the ListboxItem into the de-selected state.
1042
1043	\return
1044	Nothing.
1045
1046	\exception InvalidRequestException thrown if \a item is not attached to the list box.
1047	*/
1048	void setItemSelectState(ListboxItem* item, bool state);
1049
1050
1051	/*!
1052	\brief
1053	Sets or clears the selected state of the ListboxItem at the given grid reference.
1054
1055	\note
1056	Depending upon the current selection mode, this may cause other items to be selected, other
1057	items to be deselected, or for nothing to actually happen at all.
1058
1059	\param grid_ref
1060	MCLGridRef object describing the position of the item to be affected.
1061
1062	\param state
1063	- true to put the ListboxItem into the selected state.
1064	- false to put the ListboxItem into the de-selected state.
1065
1066	\return
1067	Nothing.
1068
1069	\exception InvalidRequestException thrown if \a grid_ref is invalid for this list box.
1070	*/
1071	void setItemSelectState(const MCLGridRef& grid_ref, bool state);
1072
1073
1074	/*!
1075	\brief
1076	Inform the list box that one or more attached ListboxItems have been externally modified, and
1077	the list should re-sync its internal state and refresh the display as needed.
1078
1079	\return
1080	Nothing.
1081	*/
1082	void handleUpdatedItemData(void);
1083
1084
1085	/*!
1086	\brief
1087	Set the width of the specified column header (and therefore the column itself).
1088
1089	\param col_idx
1090	Zero based column index of the column whos width is to be set.
1091
1092	\param width
1093	float value specifying the new width for the column using the active metrics system.
1094
1095	\return
1096	Nothing.
1097
1098	\exception InvalidRequestException thrown if \a column is out of range.
1099	*/
1100	void setColumnHeaderWidth(uint col_idx, float width);
1101
1102
1103	/*!
1104	\brief
1105	Set whether user manipulation of the sort column and direction are enabled.
1106
1107	\param setting
1108	- true if the user may interactively modify the sort column and direction.
1109	- false if the user may not modify the sort column and direction (these can still be set programmatically).
1110
1111	\return
1112	Nothing.
1113	*/
1114	void setUserSortControlEnabled(bool setting);
1115
1116
1117	/*!
1118	\brief
1119	Set whether the user may size column segments.
1120
1121	\param setting
1122	- true if the user may interactively modify the width of columns.
1123	- false if the user may not change the width of the columns.
1124
1125	\return
1126	Nothing.
1127	*/
1128	void setUserColumnSizingEnabled(bool setting);
1129
1130
1131	/*!
1132	\brief
1133	Set whether the user may modify the order of the columns.
1134
1135	\param setting
1136	- true if the user may interactively modify the order of the columns.
1137	- false if the user may not modify the order of the columns.
1138	*/
1139	void setUserColumnDraggingEnabled(bool setting);
1140
1141
1142	/*!
1143	\brief
1144	Automatically determines the "best fit" size for the specified column and sets
1145	the column width to the same.
1146
1147	\param col_idx
1148	Zero based index of the column to be sized.
1149
1150	\return
1151	Nothing.
1152
1153	\exception InvalidRequestException thrown if \a col_idx is out of range.
1154	*/
1155	void autoSizeColumnHeader(uint col_idx);
1156
1157
1158	/*!
1159	\brief
1160	Set the ID code assigned to a given row.
1161
1162	\param row_idx
1163	Zero based index of the row who's ID code is to be set.
1164
1165	\param row_id
1166	ID code to be assigned to the row at the requested index.
1167
1168	\return
1169	Nothing.
1170
1171	\exception InvalidRequestException thrown if \a row_idx is out of range
1172	*/
1173	void setRowID(uint row_idx, uint row_id);
1174
1175
1176	/*************************************************************************
1177	Construction and Destruction
1178	*************************************************************************/
1179	/*!
1180	\brief
1181	Constructor for the Multi-column list base class
1182	*/
1183	MultiColumnList(const String& type, const String& name);
1184
1185
1186	/*!
1187	\brief
1188	Destructor for the multi-column list base class.
1189	*/
1190	virtual ~MultiColumnList(void);
1191
1192
1193	protected:
1194	/*************************************************************************
1195	Implementation Functions (abstract interface)
1196	*************************************************************************/
1197	/*!
1198	\brief
1199	Return a Rect object describing, in un-clipped pixels, the window relative area
1200	that is to be used for rendering list items.
1201
1202	\return
1203	Rect object describing the area of the Window to be used for rendering
1204	list box items.
1205	*/
1206	virtual Rect getListRenderArea(void) const = 0;
1207
1208
1209	/*!
1210	\brief
1211	create and return a pointer to a ListHeaer widget for use as the column headers.
1212
1213	\return
1214	Pointer to a ListHeader based object.
1215	*/
1216	virtual ListHeader* createListHeader(void) const = 0;
1217
1218
1219	/*!
1220	\brief
1221	create and return a pointer to a Scrollbar widget for use as vertical scroll bar
1222
1223	\return
1224	Pointer to a Scrollbar to be used for scrolling the list vertically.
1225	*/
1226	virtual Scrollbar* createVertScrollbar(void) const = 0;
1227
1228
1229	/*!
1230	\brief
1231	create and return a pointer to a Scrollbar widget for use as horizontal scroll bar
1232
1233	\return
1234	Pointer to a Scrollbar to be used for scrolling the list horizontally.
1235	*/
1236	virtual Scrollbar* createHorzScrollbar(void) const = 0;
1237
1238
1239	/*!
1240	\brief
1241	Setup size and position for the component widgets attached to this Listbox
1242
1243	\return
1244	Nothing.
1245	*/
1246	virtual void layoutComponentWidgets() = 0;
1247
1248
1249	/*!
1250	\brief
1251	Perform rendering of the widget control frame and other 'static' areas. This
1252	method should not render the actual items. Note that the items are typically
1253	rendered to layer 3, other layers can be used for rendering imagery behind and
1254	infront of the items.
1255
1256	\param z
1257	Z co-ordinate for layer 0.
1258
1259	\return
1260	Nothing.
1261	*/
1262	virtual void renderListboxBaseImagery(float z) = 0;
1263
1264
1265	/*************************************************************************
1266	Implementation Functions
1267	*************************************************************************/
1268	/*!
1269	\brief
1270	Add multi column list box specific events
1271	*/
1272	void addMultiColumnListboxEvents(void);
1273
1274
1275	/*!
1276	\brief
1277	Perform the actual rendering for this Window.
1278
1279	\param z
1280	float value specifying the base Z co-ordinate that should be used when rendering
1281
1282	\return
1283	Nothing
1284	*/
1285	virtual void drawSelf(float z);
1286
1287
1288	/*!
1289	\brief
1290	display required integrated scroll bars according to current state of the list box and update their values.
1291	*/
1292	void configureScrollbars(void);
1293
1294
1295	/*!
1296	\brief
1297	select all strings between positions \a start and \a end. (inclusive). Returns true if something was modified.
1298	*/
1299	bool selectRange(const MCLGridRef& start, const MCLGridRef& end);
1300
1301
1302	/*!
1303	\brief
1304	Return the sum of all row heights
1305	*/
1306	float getTotalRowsHeight(void) const;
1307
1308
1309	/*!
1310	\brief
1311	Return the width of the widest item in the given column
1312	*/
1313	float getWidestColumnItemWidth(uint col_idx) const;
1314
1315
1316	/*!
1317	\brief
1318	Return the height of the highest item in the given row.
1319	*/
1320	float getHighestRowItemHeight(uint row_idx) const;
1321
1322
1323	/*!
1324	\brief
1325	Clear the selected state for all items (implementation)
1326
1327	\return
1328	true if some selections were cleared, false nothing was changed.
1329	*/
1330	bool clearAllSelections_impl(void);
1331
1332
1333	/*!
1334	\brief
1335	Return the ListboxItem under the given window local pixel co-ordinate.
1336
1337	\return
1338	ListboxItem that is under window pixel co-ordinate \a pt, or NULL if no
1339	item is under that position.
1340	*/
1341	ListboxItem* getItemAtPoint(const Point& pt) const;
1342
1343
1344	/*!
1345	\brief
1346	Set select state for the given item. This appropriately selects other
1347	items depending upon the select mode. Returns true if something is
1348	changed, else false.
1349	*/
1350	bool setItemSelectState_impl(const MCLGridRef grid_ref, bool state);
1351
1352
1353	/*!
1354	\brief
1355	Set select state for all items in the given row
1356	*/
1357	void setSelectForItemsInRow(uint row_idx, bool state);
1358
1359
1360	/*!
1361	\brief
1362	Set select state for all items in the given column
1363	*/
1364	void setSelectForItemsInColumn(uint col_idx, bool state);
1365
1366
1367	/*!
1368	\brief
1369	Move the column at index \a col_idx so it is at index \a position. Implementation version which does not move the
1370	header segment (since that may have already happened).
1371
1372	\exception InvalidRequestException thrown if \a col_idx is invalid.
1373	*/
1374	void moveColumn_impl(uint col_idx, uint position);
1375
1376
1377	/*!
1378	\brief
1379	Remove all items from the list.
1380
1381	\note
1382	Note that this will cause 'AutoDelete' items to be deleted.
1383
1384	\return
1385	- true if the list contents were changed.
1386	- false if the list contents were not changed (list already empty).
1387	*/
1388	bool resetList_impl(void);
1389
1390
1391	/*!
1392	\brief
1393	Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
1394
1395	\param class_name
1396	The class name that is to be checked.
1397
1398	\return
1399	true if this window was inherited from \a class_name. false if not.
1400	*/
1401	virtual bool testClassName_impl(const String& class_name) const
1402	{
1403	if (class_name==(const utf8*)"MultiColumnList") return true;
1404	return Window::testClassName_impl(class_name);
1405	}
1406
1407
1408	/*************************************************************************
1409	New event handlers for multi column list
1410	*************************************************************************/
1411	/*!
1412	\brief
1413	Handler called when the selection mode of the list box changes
1414	*/
1415	virtual void onSelectionModeChanged(WindowEventArgs& e);
1416
1417
1418	/*!
1419	\brief
1420	Handler called when the nominated selection column changes
1421	*/
1422	virtual void onNominatedSelectColumnChanged(WindowEventArgs& e);
1423
1424
1425	/*!
1426	\brief
1427	Handler called when the nominated selection row changes.
1428	*/
1429	virtual void onNominatedSelectRowChanged(WindowEventArgs& e);
1430
1431
1432	/*!
1433	\brief
1434	Handler called when the vertical scroll bar 'force' mode is changed.
1435	*/
1436	virtual void onVertScrollbarModeChanged(WindowEventArgs& e);
1437
1438
1439	/*!
1440	\brief
1441	Handler called when the horizontal scroll bar 'force' mode is changed.
1442	*/
1443	virtual void onHorzScrollbarModeChanged(WindowEventArgs& e);
1444
1445
1446	/*!
1447	\brief
1448	Handler called when the current selection changes.
1449	*/
1450	virtual void onSelectionChanged(WindowEventArgs& e);
1451
1452
1453	/*!
1454	\brief
1455	Handler called when the list contents is changed.
1456	*/
1457	virtual void onListContentsChanged(WindowEventArgs& e);
1458
1459
1460	/*!
1461	\brief
1462	Handler called when the sort column changes.
1463	*/
1464	virtual void onSortColumnChanged(WindowEventArgs& e);
1465
1466
1467	/*!
1468	\brief
1469	Handler called when the sort direction changes.
1470	*/
1471	virtual void onSortDirectionChanged(WindowEventArgs& e);
1472
1473
1474	/*!
1475	\brief
1476	Handler called when a column is sized.
1477	*/
1478	virtual void onListColumnSized(WindowEventArgs& e);
1479
1480
1481	/*!
1482	\brief
1483	Handler called when the column order is changed.
1484	*/
1485	virtual void onListColumnMoved(WindowEventArgs& e);
1486
1487
1488	/*************************************************************************
1489	Overridden Event handlers
1490	*************************************************************************/
1491	virtual void onSized(WindowEventArgs& e);
1492	virtual void onMouseButtonDown(MouseEventArgs& e);
1493	virtual void onMouseWheel(MouseEventArgs& e);
1494
1495
1496	/*************************************************************************
1497	Handlers for subscribed events
1498	*************************************************************************/
1499	bool handleHeaderScroll(const EventArgs& e);
1500	bool handleHeaderSegMove(const EventArgs& e);
1501	bool handleColumnSizeChange(const EventArgs& e);
1502	bool handleHorzScrollbar(const EventArgs& e);
1503	bool handleSortColumnChange(const EventArgs& e);
1504	bool handleSortDirectionChange(const EventArgs& e);
1505	bool handleHeaderSegDblClick(const EventArgs& e);
1506
1507
1508	/*************************************************************************
1509	Struct used to wrap a 'row' and ease sorting
1510	*************************************************************************/
1511	struct ListRow
1512	{
1513	typedef std::vector<ListboxItem*> RowItems;
1514	RowItems d_items;
1515	uint d_sortColumn;
1516	uint d_rowID;
1517
1518	// operators
1519	ListboxItem* const& operator[](uint idx) const {return d_items[idx];}
1520	ListboxItem*& operator[](uint idx) {return d_items[idx];}
1521	bool operator<(const ListRow& rhs) const;
1522	bool operator>(const ListRow& rhs) const;
1523	};
1524
1525
1526	/*!
1527	\brief
1528	std algorithm predicate used for sorting in descending order
1529	*/
1530	static bool pred_descend(const ListRow& a, const ListRow& b);
1531
1532
1533	/*************************************************************************
1534	Implementation Data
1535	*************************************************************************/
1536	// component widgets and settings.
1537	Scrollbar* d_vertScrollbar; //!< vertical scroll-bar widget
1538	Scrollbar* d_horzScrollbar; //!< horizontal scroll-bar widget
1539	ListHeader* d_header; //!< The ListHeader attached to this multi-column list.
1540	bool d_forceVertScroll; //!< true if vertical scrollbar should always be displayed
1541	bool d_forceHorzScroll; //!< true if horizontal scrollbar should always be displayed
1542
1543	// selection abilities.
1544	SelectionMode d_selectMode; //!< Holds selection mode (represented by settings below).
1545	uint d_nominatedSelectCol; //!< Nominated column for single column selection.
1546	uint d_nominatedSelectRow; //!< Nominated row for single row selection.
1547	bool d_multiSelect; //!< Allow multiple selections.
1548	bool d_fullRowSelect; //!< All items in a row are selected.
1549	bool d_fullColSelect; //!< All items in a column are selected.
1550	bool d_useNominatedRow; //!< true if we use a nominated row to select.
1551	bool d_useNominatedCol; //!< true if we use a nominated col to select.
1552	ListboxItem* d_lastSelected; //!< holds pointer to the last selected item (used in range selections)
1553
1554	// storage of items in the list box.
1555	typedef std::vector<ListRow> ListItemGrid;
1556	ListItemGrid d_grid; //!< Holds the list box data.
1557
1558
1559	private:
1560	/*************************************************************************
1561	Static Properties for this class
1562	*************************************************************************/
1563	static MultiColumnListProperties::ColumnsMovable d_columnsMovableProperty;
1564	static MultiColumnListProperties::ColumnsSizable d_columnsSizableProperty;
1565	static MultiColumnListProperties::ForceHorzScrollbar d_forceHorzScrollProperty;
1566	static MultiColumnListProperties::ForceVertScrollbar d_forceVertScrollProperty;
1567	static MultiColumnListProperties::NominatedSelectionColumnID d_nominatedSelectColProperty;
1568	static MultiColumnListProperties::NominatedSelectionRow d_nominatedSelectRowProperty;
1569	static MultiColumnListProperties::SelectionMode d_selectModeProperty;
1570	static MultiColumnListProperties::SortColumnID d_sortColumnIDProperty;
1571	static MultiColumnListProperties::SortDirection d_sortDirectionProperty;
1572	static MultiColumnListProperties::SortSettingEnabled d_sortSettingProperty;
1573	static MultiColumnListProperties::ColumnHeader d_columnHeaderProperty;
1574	static MultiColumnListProperties::RowCount d_rowCountProperty;
1575
1576
1577	/*************************************************************************
1578	Private methods
1579	*************************************************************************/
1580	void addMultiColumnListProperties(void);
1581	};
1582
1583	} // End of CEGUI namespace section
1584
1585	#if defined(_MSC_VER)
1586	# pragma warning(pop)
1587	#endif
1588
1589	#endif // end of guard _CEGUIMultiColumnList_h_

Note: See TracBrowser for help on using the repository browser.

Download in other formats: