Context Navigation

source: GTP/trunk/App/Demos/Geom/include/CEGUI/elements/CEGUIListHeader.h @ 1030

Revision 1030, 24.6 KB checked in by gumbau, 18 years ago (diff)
Ogre Stuff initial import

Line
1	/************************************************************************
2	filename: CEGUIListHeader.h
3	created: 13/4/2004
4	author: Paul D Turner
5
6	purpose: Interface to base class for ListHeader 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 _CEGUIListHeader_h_
27	#define _CEGUIListHeader_h_
28
29	#include "CEGUIBase.h"
30	#include "CEGUIWindow.h"
31	#include "elements/CEGUIListHeaderSegment.h"
32	#include "elements/CEGUIListHeaderProperties.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	\brief
46	EventArgs class used for segment move (sequence changed) events.
47	*/
48	class CEGUIEXPORT HeaderSequenceEventArgs : public WindowEventArgs
49	{
50	public:
51	HeaderSequenceEventArgs(Window* wnd, uint old_idx, uint new_idx) : WindowEventArgs(wnd), d_oldIdx(old_idx), d_newIdx(new_idx) {};
52
53	uint d_oldIdx; //!< The original column index of the segment that has moved.
54	uint d_newIdx; //!< The new column index of the segment that has moved.
55	};
56
57
58	/*!
59	\brief
60	Base class for the multi column list header widget.
61	*/
62	class CEGUIEXPORT ListHeader : public Window
63	{
64	public:
65	static const String EventNamespace; //!< Namespace for global events
66
67
68	/*************************************************************************
69	Constants
70	*************************************************************************/
71	// Event names
72	static const String EventSortColumnChanged; //!< Event fired when the current sort column changes.
73	static const String EventSortDirectionChanged; //!< Event fired when the sort direction changes.
74	static const String EventSegmentSized; //!< Event fired when a segment has been sized by the user (e.window is the segment).
75	static const String EventSegmentClicked; //!< Event fired when a segment has been clicked by the user (e.window is the segment).
76	static const String EventSplitterDoubleClicked; //!< Event fired when a segment splitter has been double-clicked. (e.window is the segment).
77	static const String EventSegmentSequenceChanged; //!< Event fired when the order of the segments has changed. ('e' is a HeaderSequenceEventArgs&)
78	static const String EventSegmentAdded; //!< Event fired when a segment is added to the header.
79	static const String EventSegmentRemoved; //!< Event fired when a segment is removed from the header.
80	static const String EventSortSettingChanged; //!< Event fired when setting that controls user modification to sort configuration changes.
81	static const String EventDragMoveSettingChanged; //!< Event fired when setting that controls user drag & drop of segments changes.
82	static const String EventDragSizeSettingChanged; //!< Event fired when setting that controls user sizing of segments changes.
83	static const String EventSegmentRenderOffsetChanged; //!< Event fired when the rendering offset for the segments changes.
84
85	// values
86	static const float ScrollSpeed; //!< Speed to scroll at when dragging outside header.
87	static const float MinimumSegmentPixelWidth; //!< Miniumum width of a segment in pixels.
88
89
90	/*************************************************************************
91	Accessor Methods
92	*************************************************************************/
93	/*!
94	\brief
95	Return the number of columns or segments attached to the header.
96
97	\return
98	uint value equal to the number of columns / segments currently in the header.
99	*/
100	uint getColumnCount(void) const;
101
102
103	/*!
104	\brief
105	Return the ListHeaderSegment object for the specified column
106
107	\param column
108	zero based column index of the ListHeaderSegment to be returned.
109
110	\return
111	ListHeaderSegment object at the requested index.
112
113	\exception InvalidRequestException thrown if column is out of range.
114	*/
115	ListHeaderSegment& getSegmentFromColumn(uint column) const;
116
117
118	/*!
119	\brief
120	Return the ListHeaderSegment object with the specified ID.
121
122	\param id
123	id code of the ListHeaderSegment to be returned.
124
125	\return
126	ListHeaderSegment object with the ID \a id. If more than one segment has the same ID, only the first one will
127	ever be returned.
128
129	\exception InvalidRequestException thrown if no segment with the requested ID is attached.
130	*/
131	ListHeaderSegment& getSegmentFromID(uint id) const;
132
133
134	/*!
135	\brief
136	Return the ListHeaderSegment that is marked as being the 'sort key' segment. There must be at least one segment
137	to successfully call this method.
138
139	\return
140	ListHeaderSegment object which is the sort-key segment.
141
142	\exception InvalidRequestException thrown if no segments are attached to the ListHeader.
143	*/
144	ListHeaderSegment& getSortSegment(void) const;
145
146
147	/*!
148	\brief
149	Return the zero based column index of the specified segment.
150
151	\param segment
152	ListHeaderSegment whos zero based index is to be returned.
153
154	\return
155	Zero based column index of the ListHeaderSegment \a segment.
156
157	\exception InvalidRequestException thrown if \a segment is not attached to this ListHeader.
158	*/
159	uint getColumnFromSegment(const ListHeaderSegment& segment) const;
160
161
162	/*!
163	\brief
164	Return the zero based column index of the segment with the specified ID.
165
166	\param id
167	ID code of the segment whos column index is to be returned.
168
169	\return
170	Zero based column index of the first ListHeaderSegment whos ID matches \a id.
171
172	\exception InvalidRequestException thrown if no attached segment has the requested ID.
173	*/
174	uint getColumnFromID(uint id) const;
175
176
177	/*!
178	\brief
179	Return the zero based index of the current sort column. There must be at least one segment/column to successfully call this
180	method.
181
182	\return
183	Zero based column index that is the current sort column.
184
185	\exception InvalidRequestException thrown if there are no segments / columns in this ListHeader.
186	*/
187	uint getSortColumn(void) const;
188
189
190	/*!
191	\brief
192	Return the zero based column index of the segment with the specified text.
193
194	\param text
195	String object containing the text to be searched for.
196
197	\return
198	Zero based column index of the segment with the specified text.
199
200	\exception InvalidRequestException thrown if no attached segments have the requested text.
201	*/
202	uint getColumnWithText(const String& text) const;
203
204
205	/*!
206	\brief
207	Return the pixel offset to the given ListHeaderSegment.
208
209	\param segment
210	ListHeaderSegment object that the offset to is to be returned.
211
212	\return
213	The number of pixels up-to the begining of the ListHeaderSegment described by \a segment.
214
215	\exception InvalidRequestException thrown if \a segment is not attached to the ListHeader.
216	*/
217	float getPixelOffsetToSegment(const ListHeaderSegment& segment) const;
218
219
220	/*!
221	\brief
222	Return the pixel offset to the ListHeaderSegment at the given zero based column index.
223
224	\param column
225	Zero based column index of the ListHeaderSegment whos pixel offset it to be returned.
226
227	\return
228	The number of pixels up-to the begining of the ListHeaderSegment located at zero based column
229	index \a column.
230
231	\exception InvalidRequestException thrown if \a column is out of range.
232	*/
233	float getPixelOffsetToColumn(uint column) const;
234
235
236	/*!
237	\brief
238	Return the total pixel width of all attached segments.
239
240	\return
241	Sum of the pixel widths of all attached ListHeaderSegment objects.
242	*/
243	float getTotalSegmentsPixelExtent(void) const;
244
245
246	/*!
247	\brief
248	Return the pixel width of the specified column.
249
250	\param column
251	Zero based column index of the segment whos pixel width is to be returned.
252
253	\return
254	Pixel width of the ListHeaderSegment at the zero based column index specified by \a column.
255
256	\exception InvalidRequestException thrown if \a column is out of range.
257	*/
258	float getColumnPixelWidth(uint column) const;
259
260
261	/*!
262	\brief
263	Return the currently set sort direction.
264
265	\return
266	One of the ListHeaderSegment::SortDirection enumerated values specifying the current sort direction.
267	*/
268	ListHeaderSegment::SortDirection getSortDirection(void) const;
269
270
271	/*!
272	\brief
273	Return whether user manipulation of the sort column & direction are enabled.
274
275	\return
276	true if the user may interactively modify the sort column and direction. false if the user may not
277	modify the sort column and direction (these can still be set programmatically).
278	*/
279	bool isSortingEnabled(void) const;
280
281
282	/*!
283	\brief
284	Return whether the user may size column segments.
285
286	\return
287	true if the user may interactively modify the width of column segments, false if they may not.
288	*/
289	bool isColumnSizingEnabled(void) const;
290
291
292	/*!
293	\brief
294	Return whether the user may modify the order of the segments.
295
296	\return
297	true if the user may interactively modify the order of the column segments, false if they may not.
298	*/
299	bool isColumnDraggingEnabled(void) const;
300
301
302	/*!
303	\brief
304	Return the current segment offset value. This value is used to implement scrolling of the header segments within
305	the ListHeader area.
306
307	\return
308	float value specifying the current segment offset value in whatever metrics system is active for the ListHeader.
309	*/
310	float getSegmentOffset(void) const {return d_segmentOffset;}
311
312
313	/*************************************************************************
314	Manipulator Methods
315	*************************************************************************/
316	/*!
317	\brief
318	Set whether user manipulation of the sort column and direction is enabled.
319
320	\param setting
321	- true to allow interactive user manipulation of the sort column and direction.
322	- false to disallow interactive user manipulation of the sort column and direction.
323
324	\return
325	Nothing.
326	*/
327	void setSortingEnabled(bool setting);
328
329
330	/*!
331	\brief
332	Set the current sort direction.
333
334	\param direction
335	One of the ListHeaderSegment::SortDirection enumerated values indicating the sort direction to be used.
336
337	\return
338	Nothing.
339	*/
340	void setSortDirection(ListHeaderSegment::SortDirection direction);
341
342
343	/*!
344	\brief
345	Set the column segment to be used as the sort column.
346
347	\param segment
348	ListHeaderSegment object indicating the column to be sorted.
349
350	\return
351	Nothing.
352
353	\exception InvalidRequestException thrown if \a segment is not attached to this ListHeader.
354	*/
355	void setSortSegment(const ListHeaderSegment& segment);
356
357
358	/*!
359	\brief
360	Set the column to be used as the sort column.
361
362	\param column
363	Zero based column index indicating the column to be sorted.
364
365	\return
366	Nothing.
367
368	\exception InvalidRequestException thrown if \a column is out of range for this ListHeader.
369	*/
370	void setSortColumn(uint column);
371
372
373	/*!
374	\brief
375	Set the column to to be used for sorting via its ID code.
376
377	\param id
378	ID code of the column segment that is to be used as the sort column.
379
380	\return
381	Nothing.
382
383	\exception InvalidRequestException thrown if no segment with ID \a id is attached to the ListHeader.
384	*/
385	void setSortColumnFromID(uint id);
386
387
388	/*!
389	\brief
390	Set whether columns may be sized by the user.
391
392	\param setting
393	- true to indicate that the user may interactively size segments.
394	- false to indicate that the user may not interactively size segments.
395
396	\return
397	Nothing.
398	*/
399	void setColumnSizingEnabled(bool setting);
400
401
402	/*!
403	\brief
404	Set whether columns may be reordered by the user via drag and drop.
405
406	\param setting
407	- true to indicate the user may change the order of the column segments via drag and drop.
408	- false to indicate the user may not change the column segment order.
409
410	\return
411	Nothing.
412	*/
413	void setColumnDraggingEnabled(bool setting);
414
415
416	/*!
417	\brief
418	Add a new column segment to the end of the header.
419
420	\param text
421	String object holding the initial text for the new segment
422
423	\param id
424	Client specified ID code to be assigned to the new segment.
425
426	\param width
427	Initial width of the new segment using the relative metrics system
428
429	\return
430	Nothing.
431	*/
432	void addColumn(const String& text, uint id, float width);
433
434
435	/*!
436	\brief
437	Insert a new column segment at the specified position.
438
439	\param text
440	String object holding the initial text for the new segment
441
442	\param id
443	Client specified ID code to be assigned to the new segment.
444
445	\param width
446	Initial width of the new segment using the relative metrics system
447
448	\param position
449	Zero based column index indicating the desired position for the new column. If this is greater than
450	the current number of columns, the new segment is added to the end if the header.
451
452	\return
453	Nothing.
454	*/
455	void insertColumn(const String& text, uint id, float width, uint position);
456
457
458	/*!
459	\brief
460	Insert a new column segment at the specified position.
461
462	\param text
463	String object holding the initial text for the new segment
464
465	\param id
466	Client specified ID code to be assigned to the new segment.
467
468	\param width
469	Initial width of the new segment using the relative metrics system
470
471	\param position
472	ListHeaderSegment object indicating the insert position for the new segment. The new segment will be
473	inserted before the segment indicated by \a position.
474
475	\return
476	Nothing.
477
478	\exception InvalidRequestException thrown if ListHeaderSegment \a position is not attached to the ListHeader.
479	*/
480	void insertColumn(const String& text, uint id, float width, const ListHeaderSegment& position);
481
482
483	/*!
484	\brief
485	Removes a column segment from the ListHeader.
486
487	\param column
488	Zero based column index indicating the segment to be removed.
489
490	\return
491	Nothing.
492
493	\exception InvalidRequestException thrown if \a column is out of range.
494	*/
495	void removeColumn(uint column);
496
497
498	/*!
499	\brief
500	Remove the specified segment from the ListHeader.
501
502	\param segment
503	ListHeaderSegment object that is to be removed from the ListHeader.
504
505	\return
506	Nothing.
507
508	\exception InvalidRequestException thrown if \a segment is not attached to this ListHeader.
509	*/
510	void removeSegment(const ListHeaderSegment& segment);
511
512
513	/*!
514	\brief
515	Moves a column segment into a new position.
516
517	\param column
518	Zero based column index indicating the column segment to be moved.
519
520	\param position
521	Zero based column index indicating the new position for the segment. If this is greater than the current number of segments,
522	the segment is moved to the end of the header.
523
524	\return
525	Nothing.
526
527	\exception InvalidRequestException thrown if \a column is out of range for this ListHeader.
528	*/
529	void moveColumn(uint column, uint position);
530
531
532	/*!
533	\brief
534	Move a column segment to a new position.
535
536	\param column
537	Zero based column index indicating the column segment to be moved.
538
539	\param position
540	ListHeaderSegment object indicating the new position for the segment. The segment at \a column
541	will be moved behind segment \a position (that is, segment \a column will appear to the right of
542	segment \a position).
543
544	\return
545	Nothing.
546
547	\exception InvalidRequestException thrown if \a column is out of range for this ListHeader, or if \a position
548	is not attached to this ListHeader.
549	*/
550	void moveColumn(uint column, const ListHeaderSegment& position);
551
552
553	/*!
554	\brief
555	Moves a segment into a new position.
556
557	\param segment
558	ListHeaderSegment object that is to be moved.
559
560	\param position
561	Zero based column index indicating the new position for the segment. If this is greater than the current number of segments,
562	the segment is moved to the end of the header.
563
564	\return
565	Nothing.
566
567	\exception InvalidRequestException thrown if \a segment is not attached to this ListHeader.
568	*/
569	void moveSegment(const ListHeaderSegment& segment, uint position);
570
571
572	/*!
573	\brief
574	Move a segment to a new position.
575
576	\param segment
577	ListHeaderSegment object that is to be moved.
578
579	\param position
580	ListHeaderSegment object indicating the new position for the segment. The segment \a segment
581	will be moved behind segment \a position (that is, segment \a segment will appear to the right of
582	segment \a position).
583
584	\return
585	Nothing.
586
587	\exception InvalidRequestException thrown if either \a segment or \a position are not attached to this ListHeader.
588	*/
589	void moveSegment(const ListHeaderSegment& segment, const ListHeaderSegment& position);
590
591
592	/*!
593	\brief
594	Set the current base segment offset. (This implements scrolling of the header segments within
595	the header area).
596
597	\param offset
598	New base offset for the first segment. The segments will of offset to the left by the amount specified.
599	\a offset should be specified using the active metrics system for the ListHeader.
600
601	\return
602	Nothing.
603	*/
604	void setSegmentOffset(float offset);
605
606
607	/*!
608	\brief
609	Set the pixel width of the specified column.
610
611	\param column
612	Zero based column index of the segment whos pixel width is to be set.
613
614	\param width
615	float value specifying the new pixel width to set for the ListHeaderSegment at the zero based column
616	index specified by \a column.
617
618	\return
619	Nothing
620
621	\exception InvalidRequestException thrown if \a column is out of range.
622	*/
623	void setColumnPixelWidth(uint column, float width);
624
625
626	/*************************************************************************
627	Construction and Destruction
628	*************************************************************************/
629	/*!
630	\brief
631	Constructor for the list header base class.
632	*/
633	ListHeader(const String& type, const String& name);
634
635
636	/*!
637	\brief
638	Destructor for the list header base class.
639	*/
640	virtual ~ListHeader(void);
641
642
643	protected:
644	/*************************************************************************
645	Abstract Implementation Methods
646	*************************************************************************/
647	/*!
648	\brief
649	Create and return a pointer to a new ListHeaderSegment based object.
650
651	\param name
652	String object holding the name that should be given to the new Window.
653
654	\return
655	Pointer to an ListHeaderSegment based object of whatever type is appropriate for
656	this ListHeader.
657	*/
658	virtual ListHeaderSegment* createNewSegment(const String& name) const = 0;
659
660
661	/*!
662	\brief
663	Cleanup and destroy the given ListHeaderSegment that was created via the
664	createNewSegment method.
665
666	\param segment
667	Pointer to a ListHeaderSegment based object to be destroyed.
668
669	\return
670	Nothing.
671	*/
672	virtual void destroyListSegment(ListHeaderSegment* segment) const = 0;
673
674
675	/*************************************************************************
676	Implementation Methods
677	*************************************************************************/
678	/*!
679	\brief
680	Create initialise and return a ListHeaderSegment object, with all events subscribed and ready to use.
681	*/
682	ListHeaderSegment* createInitialisedSegment(const String& text, uint id, float width);
683
684
685	/*!
686	\brief
687	Layout the attached segments
688	*/
689	void layoutSegments(void);
690
691
692	/*!
693	\brief
694	Add ListHeader specific events
695	*/
696	void addListHeaderEvents(void);
697
698
699	/*!
700	\brief
701	Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
702
703	\param class_name
704	The class name that is to be checked.
705
706	\return
707	true if this window was inherited from \a class_name. false if not.
708	*/
709	virtual bool testClassName_impl(const String& class_name) const
710	{
711	if (class_name==(const utf8*)"ListHeader") return true;
712	return Window::testClassName_impl(class_name);
713	}
714
715
716	/*************************************************************************
717	New List header event handlers
718	*************************************************************************/
719	/*!
720	\brief
721	Handler called when the sort column is changed.
722	*/
723	virtual void onSortColumnChanged(WindowEventArgs& e);
724
725
726	/*!
727	\brief
728	Handler called when the sort direction is changed.
729	*/
730	virtual void onSortDirectionChanged(WindowEventArgs& e);
731
732
733	/*!
734	\brief
735	Handler called when a segment is sized by the user. e.window points to the segment.
736	*/
737	virtual void onSegmentSized(WindowEventArgs& e);
738
739
740	/*!
741	\brief
742	Handler called when a segment is clicked by the user. e.window points to the segment.
743	*/
744	virtual void onSegmentClicked(WindowEventArgs& e);
745
746
747	/*!
748	\brief
749	Handler called when a segment splitter / sizer is double-clicked. e.window points to the segment.
750	*/
751	virtual void onSplitterDoubleClicked(WindowEventArgs& e);
752
753
754	/*!
755	\brief
756	Handler called when the segment / column order changes.
757	*/
758	virtual void onSegmentSequenceChanged(WindowEventArgs& e);
759
760
761	/*!
762	\brief
763	Handler called when a new segment is added to the header.
764	*/
765	virtual void onSegmentAdded(WindowEventArgs& e);
766
767
768	/*!
769	\brief
770	Handler called when a segment is removed from the header.
771	*/
772	virtual void onSegmentRemoved(WindowEventArgs& e);
773
774
775	/*!
776	\brief
777	Handler called then setting that controls the users ability to modify the search column & direction changes.
778	*/
779	virtual void onSortSettingChanged(WindowEventArgs& e);
780
781
782	/*!
783	\brief
784	Handler called when the setting that controls the users ability to drag and drop segments changes.
785	*/
786	virtual void onDragMoveSettingChanged(WindowEventArgs& e);
787
788
789	/*!
790	\brief
791	Handler called when the setting that controls the users ability to size segments changes.
792	*/
793	virtual void onDragSizeSettingChanged(WindowEventArgs& e);
794
795
796	/*!
797	\brief
798	Handler called when the base rendering offset for the segments (scroll position) changes.
799	*/
800	virtual void onSegmentOffsetChanged(WindowEventArgs& e);
801
802
803	/*************************************************************************
804	handlers for events we subscribe to from segments
805	*************************************************************************/
806	bool segmentSizedHandler(const EventArgs& e);
807	bool segmentMovedHandler(const EventArgs& e);
808	bool segmentClickedHandler(const EventArgs& e);
809	bool segmentDoubleClickHandler(const EventArgs& e);
810	bool segmentDragHandler(const EventArgs& e);
811
812
813	/*************************************************************************
814	Implementation Data
815	*************************************************************************/
816	typedef std::vector<ListHeaderSegment*> SegmentList;
817	SegmentList d_segments; //!< Attached segment windows in header order.
818	ListHeaderSegment* d_sortSegment; //!< Pointer to the segment that is currently set as the sork-key,
819	bool d_sizingEnabled; //!< true if segments can be sized by the user.
820	bool d_sortingEnabled; //!< true if the sort criteria modifications by user are enabled (no sorting is actuall done)
821	bool d_movingEnabled; //!< true if drag & drop moving of columns / segments is enabled.
822	uint d_uniqueIDNumber; //!< field used to create unique names.
823	float d_segmentOffset; //!< Base offset used to layout the segments (allows scrolling within the window area)
824	ListHeaderSegment::SortDirection d_sortDir; //!< Brief copy of the current sort direction.
825
826
827	private:
828	/*************************************************************************
829	Static Properties for this class
830	*************************************************************************/
831	static ListHeaderProperties::SortSettingEnabled d_sortSettingProperty;
832	static ListHeaderProperties::ColumnsSizable d_sizableProperty;
833	static ListHeaderProperties::ColumnsMovable d_movableProperty;
834	static ListHeaderProperties::SortColumnID d_sortColumnIDProperty;
835	static ListHeaderProperties::SortDirection d_sortDirectionProperty;
836
837
838	/*************************************************************************
839	Private methods
840	*************************************************************************/
841	void addHeaderProperties(void);
842	};
843
844	} // End of CEGUI namespace section
845
846
847	#if defined(_MSC_VER)
848	# pragma warning(pop)
849	#endif
850
851	#endif // end of guard _CEGUIListHeader_h_

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

Download in other formats: