Context Navigation

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

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

Line
1	/************************************************************************
2	filename: CEGUIListbox.h
3	created: 13/4/2004
4	author: Paul D Turner
5
6	purpose: Interface to base class for Listbox 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 _CEGUIListbox_h_
27	#define _CEGUIListbox_h_
28
29	#include "CEGUIBase.h"
30	#include "CEGUIWindow.h"
31	#include "elements/CEGUIListboxProperties.h"
32	#include <vector>
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	Base class for standard Listbox widget.
48	*/
49	class CEGUIEXPORT Listbox : public Window
50	{
51	public:
52	static const String EventNamespace; //!< Namespace for global events
53
54
55	/*************************************************************************
56	Constants
57	*************************************************************************/
58	// event names
59	static const String EventListContentsChanged; //!< Event triggered when the contents of the list is changed.
60	static const String EventSelectionChanged; //!< Event triggered when there is a change to the currently selected item(s).
61	static const String EventSortModeChanged; //!< Event triggered when the sort mode setting changes.
62	static const String EventMultiselectModeChanged; //!< Event triggered when the multi-select mode setting changes.
63	static const String EventVertScrollbarModeChanged; //!< Event triggered when the vertical scroll bar 'force' setting changes.
64	static const String EventHorzScrollbarModeChanged; //!< Event triggered when the horizontal scroll bar 'force' setting changes.
65
66
67	/*************************************************************************
68	Accessor Methods
69	*************************************************************************/
70	/*!
71	\brief
72	Return number of items attached to the list box
73
74	\return
75	the number of items currently attached to this list box.
76	*/
77	size_t getItemCount(void) const {return d_listItems.size();}
78
79
80	/*!
81	\brief
82	Return the number of selected items in the list box.
83
84	\return
85	Total number of attached items that are in the selected state.
86	*/
87	size_t getSelectedCount(void) const;
88
89
90	/*!
91	\brief
92	Return a pointer to the first selected item.
93
94	\return
95	Pointer to a ListboxItem based object that is the first selected item in the list. will return NULL if
96	no item is selected.
97	*/
98	ListboxItem* getFirstSelectedItem(void) const;
99
100
101	/*!
102	\brief
103	Return a pointer to the next selected item after item \a start_item
104
105	\param start_item
106	Pointer to the ListboxItem where the search for the next selected item is to begin. If this
107	parameter is NULL, the search will begin with the first item in the list box.
108
109	\return
110	Pointer to a ListboxItem based object that is the next selected item in the list after
111	the item specified by \a start_item. Will return NULL if no further items were selected.
112
113	\exception InvalidRequestException thrown if \a start_item is not attached to this list box.
114	*/
115	ListboxItem* getNextSelected(const ListboxItem* start_item) const;
116
117
118	/*!
119	\brief
120	Return the item at index position \a index.
121
122	\param index
123	Zero based index of the item to be returned.
124
125	\return
126	Pointer to the ListboxItem at index position \a index in the list box.
127
128	\exception InvalidRequestException thrown if \a index is out of range.
129	*/
130	ListboxItem* getListboxItemFromIndex(size_t index) const;
131
132
133	/*!
134	\brief
135	Return the index of ListboxItem \a item
136
137	\param item
138	Pointer to a ListboxItem whos zero based index is to be returned.
139
140	\return
141	Zero based index indicating the position of ListboxItem \a item in the list box.
142
143	\exception InvalidRequestException thrown if \a item is not attached to this list box.
144	*/
145	size_t getItemIndex(const ListboxItem* item) const;
146
147
148	/*!
149	\brief
150	return whether list sorting is enabled
151
152	\return
153	true if the list is sorted, false if the list is not sorted
154	*/
155	bool isSortEnabled(void) const {return d_sorted;}
156
157	/*!
158	\brief
159	return whether multi-select is enabled
160
161	\return
162	true if multi-select is enabled, false if multi-select is not enabled.
163	*/
164	bool isMultiselectEnabled(void) const {return d_multiselect;}
165
166
167	/*!
168	\brief
169	return whether the string at index position \a index is selected
170
171	\param index
172	Zero based index of the item to be examined.
173
174	\return
175	true if the item at \a index is selected, false if the item at \a index is not selected.
176
177	\exception InvalidRequestException thrown if \a index is out of range.
178	*/
179	bool isItemSelected(size_t index) const;
180
181
182	/*!
183	\brief
184	Search the list for an item with the specified text
185
186	\param text
187	String object containing the text to be searched for.
188
189	\param start_item
190	ListboxItem where the search is to begin, the search will not include \a item. If \a item is
191	NULL, the search will begin from the first item in the list.
192
193	\return
194	Pointer to the first ListboxItem in the list after \a item that has text matching \a text. If
195	no item matches the criteria NULL is returned.
196
197	\exception InvalidRequestException thrown if \a item is not attached to this list box.
198	*/
199	ListboxItem* findItemWithText(const String& text, const ListboxItem* start_item);
200
201
202	/*!
203	\brief
204	Return whether the specified ListboxItem is in the List
205
206	\return
207	true if ListboxItem \a item is in the list, false if ListboxItem \a item is not in the list.
208	*/
209	bool isListboxItemInList(const ListboxItem* item) const;
210
211
212	/*!
213	\brief
214	Return whether the vertical scroll bar is always shown.
215
216	\return
217	- true if the scroll bar will always be shown even if it is not required.
218	- false if the scroll bar will only be shown when it is required.
219	*/
220	bool isVertScrollbarAlwaysShown(void) const;
221
222
223	/*!
224	\brief
225	Return whether the horizontal scroll bar is always shown.
226
227	\return
228	- true if the scroll bar will always be shown even if it is not required.
229	- false if the scroll bar will only be shown when it is required.
230	*/
231	bool isHorzScrollbarAlwaysShown(void) const;
232
233
234	/*************************************************************************
235	Manipulator Methods
236	*************************************************************************/
237	/*!
238	\brief
239	Initialise the Window based object ready for use.
240
241	\note
242	This must be called for every window created. Normally this is handled automatically by the WindowFactory for each Window type.
243
244	\return
245	Nothing
246	*/
247	virtual void initialise(void);
248
249
250	/*!
251	\brief
252	Remove all items from the list.
253
254	Note that this will cause 'AutoDelete' items to be deleted.
255	*/
256	void resetList(void);
257
258
259	/*!
260	\brief
261	Add the given ListboxItem to the list.
262
263	\param item
264	Pointer to the ListboxItem to be added to the list. Note that it is the passed object that is added to the
265	list, a copy is not made. If this parameter is NULL, nothing happens.
266
267	\return
268	Nothing.
269	*/
270	void addItem(ListboxItem* item);
271
272
273	/*!
274	\brief
275	Insert an item into the list box after a specified item already in the list.
276
277	Note that if the list is sorted, the item may not end up in the requested position.
278
279	\param item
280	Pointer to the ListboxItem to be inserted. Note that it is the passed object that is added to the
281	list, a copy is not made. If this parameter is NULL, nothing happens.
282
283	\param position
284	Pointer to a ListboxItem that \a item is to be inserted after. If this parameter is NULL, the item is
285	inserted at the start of the list.
286
287	\return
288	Nothing.
289
290	\exception InvalidRequestException thrown if no ListboxItem \a position is attached to this list box.
291	*/
292	void insertItem(ListboxItem* item, const ListboxItem* position);
293
294
295	/*!
296	\brief
297	Removes the given item from the list box. If the item is has the auto delete state set, the item will be deleted.
298
299	\param item
300	Pointer to the ListboxItem that is to be removed. If \a item is not attached to this list box then nothing
301	will happen.
302
303	\return
304	Nothing.
305	*/
306	void removeItem(const ListboxItem* item);
307
308
309	/*!
310	\brief
311	Clear the selected state for all items.
312
313	\return
314	Nothing.
315	*/
316	void clearAllSelections(void);
317
318
319	/*!
320	\brief
321	Set whether the list should be sorted.
322
323	\param setting
324	true if the list should be sorted, false if the list should not be sorted.
325
326	\return
327	Nothing.
328	*/
329	void setSortingEnabled(bool setting);
330
331
332	/*!
333	\brief
334	Set whether the list should allow multiple selections or just a single selection
335
336	\param setting
337	true if the widget should allow multiple items to be selected, false if the widget should only allow
338	a single selection.
339
340	\return
341	Nothing.
342	*/
343	void setMultiselectEnabled(bool setting);
344
345
346	/*!
347	\brief
348	Set whether the vertical scroll bar should always be shown.
349
350	\param setting
351	true if the vertical scroll bar should be shown even when it is not required. false if the vertical
352	scroll bar should only be shown when it is required.
353
354	\return
355	Nothing.
356	*/
357	void setShowVertScrollbar(bool setting);
358
359
360	/*!
361	\brief
362	Set whether the horizontal scroll bar should always be shown.
363
364	\param setting
365	true if the horizontal scroll bar should be shown even when it is not required. false if the horizontal
366	scroll bar should only be shown when it is required.
367
368	\return
369	Nothing.
370	*/
371	void setShowHorzScrollbar(bool setting);
372
373
374	/*!
375	\brief
376	Set the select state of an attached ListboxItem.
377
378	This is the recommended way of selecting and deselecting items attached to a list box as it respects the
379	multi-select mode setting. It is possible to modify the setting on ListboxItems directly, but that approach
380	does not respect the settings of the list box.
381
382	\param item
383	The ListboxItem to be affected. This item must be attached to the list box.
384
385	\param state
386	true to select the item, false to de-select the item.
387
388	\return
389	Nothing.
390
391	\exception InvalidRequestException thrown if \a item is not attached to this list box.
392	*/
393	void setItemSelectState(ListboxItem* item, bool state);
394
395
396	/*!
397	\brief
398	Set the select state of an attached ListboxItem.
399
400	This is the recommended way of selecting and deselecting items attached to a list box as it respects the
401	multi-select mode setting. It is possible to modify the setting on ListboxItems directly, but that approach
402	does not respect the settings of the list box.
403
404	\param item_index
405	The zero based index of the ListboxItem to be affected. This must be a valid index (0 <= index < getItemCount())
406
407	\param state
408	true to select the item, false to de-select the item.
409
410	\return
411	Nothing.
412
413	\exception InvalidRequestException thrown if \a item_index is out of range for the list box
414	*/
415	void setItemSelectState(size_t item_index, bool state);
416
417
418	/*!
419	\brief
420	Causes the list box to update it's internal state after changes have been made to one or more
421	attached ListboxItem objects.
422
423	Client code must call this whenever it has made any changes to ListboxItem objects already attached to the
424	list box. If you are just adding items, or removed items to update them prior to re-adding them, there is
425	no need to call this method.
426
427	\return
428	Nothing.
429	*/
430	void handleUpdatedItemData(void);
431
432
433	/*!
434	\brief
435	Ensure the item at the specified index is visible within the list box.
436
437	\param item_index
438	Zero based index of the item to be made visible in the list box. If this value is out of range, the
439	list is always scrolled to the bottom.
440
441	\return
442	Nothing.
443	*/
444	void ensureItemIsVisible(size_t item_index);
445
446
447	/*!
448	\brief
449	Ensure the item at the specified index is visible within the list box.
450
451	\param item
452	Pointer to the ListboxItem to be made visible in the list box.
453
454	\return
455	Nothing.
456
457	\exception InvalidRequestException thrown if \a item is not attached to this list box.
458	*/
459	void ensureItemIsVisible(const ListboxItem* item);
460
461
462	/*************************************************************************
463	Construction and Destruction
464	*************************************************************************/
465	/*!
466	\brief
467	Constructor for Listbox base class.
468	*/
469	Listbox(const String& type, const String& name);
470
471
472	/*!
473	\brief
474	Destructor for Listbox base class.
475	*/
476	virtual ~Listbox(void);
477
478
479	protected:
480	/*************************************************************************
481	Abstract Implementation Functions (must be provided by derived class)
482	*************************************************************************/
483	/*!
484	\brief
485	Return a Rect object describing, in un-clipped pixels, the window relative area
486	that is to be used for rendering list items.
487
488	\return
489	Rect object describing the area of the Window to be used for rendering
490	list box items.
491	*/
492	virtual Rect getListRenderArea(void) const = 0;
493
494
495	/*!
496	\brief
497	create and return a pointer to a Scrollbar widget for use as vertical scroll bar
498
499	\return
500	Pointer to a Scrollbar to be used for scrolling the list vertically.
501	*/
502	virtual Scrollbar* createVertScrollbar(void) const = 0;
503
504
505	/*!
506	\brief
507	create and return a pointer to a Scrollbar widget for use as horizontal scroll bar
508
509	\return
510	Pointer to a Scrollbar to be used for scrolling the list horizontally.
511	*/
512	virtual Scrollbar* createHorzScrollbar(void) const = 0;
513
514
515	/*!
516	\brief
517	Setup size and position for the component widgets attached to this Listbox
518
519	\return
520	Nothing.
521	*/
522	virtual void layoutComponentWidgets() = 0;
523
524
525	/*!
526	\brief
527	Perform rendering of the widget control frame and other 'static' areas. This
528	method should not render the actual items. Note that the items are typically
529	rendered to layer 3, other layers can be used for rendering imagery behind and
530	infront of the items.
531
532	\param z
533	Z co-ordinate for layer 0.
534
535	\return
536	Nothing.
537	*/
538	virtual void renderListboxBaseImagery(float z) = 0;
539
540
541	/*************************************************************************
542	Implementation Functions
543	*************************************************************************/
544	/*!
545	\brief
546	Add list box specific events
547	*/
548	void addListboxEvents(void);
549
550
551	/*!
552	\brief
553	Perform the actual rendering for this Window.
554
555	\param z
556	float value specifying the base Z co-ordinate that should be used when rendering
557
558	\return
559	Nothing
560	*/
561	virtual void drawSelf(float z);
562
563
564	/*!
565	\brief
566	display required integrated scroll bars according to current state of the list box and update their values.
567	*/
568	void configureScrollbars(void);
569
570	/*!
571	\brief
572	select all strings between positions \a start and \a end. (inclusive)
573	including \a end.
574	*/
575	void selectRange(size_t start, size_t end);
576
577
578	/*!
579	\brief
580	Return the sum of all item heights
581	*/
582	float getTotalItemsHeight(void) const;
583
584
585	/*!
586	\brief
587	Return the width of the widest item
588	*/
589	float getWidestItemWidth(void) const;
590
591
592	/*!
593	\brief
594	Clear the selected state for all items (implementation)
595
596	\return
597	true if some selections were cleared, false nothing was changed.
598	*/
599	bool clearAllSelections_impl(void);
600
601
602	/*!
603	\brief
604	Return the ListboxItem under the given window local pixel co-ordinate.
605
606	\return
607	ListboxItem that is under window pixel co-ordinate \a pt, or NULL if no
608	item is under that position.
609	*/
610	ListboxItem* getItemAtPoint(const Point& pt) const;
611
612
613	/*!
614	\brief
615	Remove all items from the list.
616
617	\note
618	Note that this will cause 'AutoDelete' items to be deleted.
619
620	\return
621	- true if the list contents were changed.
622	- false if the list contents were not changed (list already empty).
623	*/
624	bool resetList_impl(void);
625
626
627	/*!
628	\brief
629	Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
630
631	\param class_name
632	The class name that is to be checked.
633
634	\return
635	true if this window was inherited from \a class_name. false if not.
636	*/
637	virtual bool testClassName_impl(const String& class_name) const
638	{
639	if (class_name==(const utf8*)"Listbox") return true;
640	return Window::testClassName_impl(class_name);
641	}
642
643
644	/*************************************************************************
645	New event handlers
646	*************************************************************************/
647	/*!
648	\brief
649	Handler called internally when the list contents are changed
650	*/
651	virtual void onListContentsChanged(WindowEventArgs& e);
652
653
654	/*!
655	\brief
656	Handler called internally when the currently selected item or items changes.
657	*/
658	virtual void onSelectionChanged(WindowEventArgs& e);
659
660
661	/*!
662	\brief
663	Handler called internally when the sort mode setting changes.
664	*/
665	virtual void onSortModeChanged(WindowEventArgs& e);
666
667
668	/*!
669	\brief
670	Handler called internally when the multi-select mode setting changes.
671	*/
672	virtual void onMultiselectModeChanged(WindowEventArgs& e);
673
674
675	/*!
676	\brief
677	Handler called internally when the forced display of the vertical scroll bar setting changes.
678	*/
679	virtual void onVertScrollbarModeChanged(WindowEventArgs& e);
680
681
682	/*!
683	\brief
684	Handler called internally when the forced display of the horizontal scroll bar setting changes.
685	*/
686	virtual void onHorzScrollbarModeChanged(WindowEventArgs& e);
687
688
689	/*************************************************************************
690	Overridden Event handlers
691	*************************************************************************/
692	virtual void onSized(WindowEventArgs& e);
693	virtual void onMouseButtonDown(MouseEventArgs& e);
694	virtual void onMouseWheel(MouseEventArgs& e);
695
696
697	/*************************************************************************
698	Implementation Data
699	*************************************************************************/
700	typedef std::vector<ListboxItem*> LBItemList;
701	bool d_sorted; //!< true if list is sorted
702	bool d_multiselect; //!< true if multi-select is enabled
703	bool d_forceVertScroll; //!< true if vertical scrollbar should always be displayed
704	bool d_forceHorzScroll; //!< true if horizontal scrollbar should always be displayed
705	Scrollbar* d_vertScrollbar; //!< vertical scroll-bar widget
706	Scrollbar* d_horzScrollbar; //!< horizontal scroll-bar widget
707	LBItemList d_listItems; //!< list of items in the list box.
708	ListboxItem* d_lastSelected; //!< holds pointer to the last selected item (used in range selections)
709
710
711	private:
712	/*************************************************************************
713	Static Properties for this class
714	*************************************************************************/
715	static ListboxProperties::Sort d_sortProperty;
716	static ListboxProperties::MultiSelect d_multiSelectProperty;
717	static ListboxProperties::ForceVertScrollbar d_forceVertProperty;
718	static ListboxProperties::ForceHorzScrollbar d_forceHorzProperty;
719
720	/*************************************************************************
721	Private methods
722	*************************************************************************/
723	void addListboxProperties(void);
724	};
725
726
727	/*!
728	\brief
729	Helper function used in sorting to compare two list box item text strings
730	via the ListboxItem pointers and return if \a a is less than \a b.
731	*/
732	bool lbi_less(const ListboxItem* a, const ListboxItem* b);
733
734
735	/*!
736	\brief
737	Helper function used in sorting to compare two list box item text strings
738	via the ListboxItem pointers and return if \a a is greater than \a b.
739	*/
740	bool lbi_greater(const ListboxItem* a, const ListboxItem* b);
741
742	} // End of CEGUI namespace section
743
744
745	#if defined(_MSC_VER)
746	# pragma warning(pop)
747	#endif
748
749	#endif // end of guard _CEGUIListbox_h_

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

Download in other formats: