Context Navigation

← Previous Revision
Latest Revision
Next Revision →
Blame
Revision Log

CEGUIListbox.h @ 1809

Revision 1809, 20.9 KB checked in by gumbau, 18 years ago (diff)

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

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

Context Navigation

source: GTP/trunk/Lib/Geom/OgreStuff/include/CEGUI/elements/CEGUIListbox.h @ 1809

Download in other formats: