Crazy Eddie's GUI System  0.8.7
widgets/Listbox.h
1 /***********************************************************************
2  created: 13/4/2004
3  author: Paul D Turner
4 
5  purpose: Interface to base class for Listbox widget
6 *************************************************************************/
7 /***************************************************************************
8  * Copyright (C) 2004 - 2006 Paul D Turner & The CEGUI Development Team
9  *
10  * Permission is hereby granted, free of charge, to any person obtaining
11  * a copy of this software and associated documentation files (the
12  * "Software"), to deal in the Software without restriction, including
13  * without limitation the rights to use, copy, modify, merge, publish,
14  * distribute, sublicense, and/or sell copies of the Software, and to
15  * permit persons to whom the Software is furnished to do so, subject to
16  * the following conditions:
17  *
18  * The above copyright notice and this permission notice shall be
19  * included in all copies or substantial portions of the Software.
20  *
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
24  * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
25  * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
26  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
27  * OTHER DEALINGS IN THE SOFTWARE.
28  ***************************************************************************/
29 #ifndef _CEGUIListbox_h_
30 #define _CEGUIListbox_h_
31 
32 #include "../Base.h"
33 #include "../Window.h"
34 #include <vector>
35 
36 
37 #if defined(_MSC_VER)
38 # pragma warning(push)
39 # pragma warning(disable : 4251)
40 #endif
41 
42 
43 // Start of CEGUI namespace section
44 namespace CEGUI
45 {
46 
51 class CEGUIEXPORT ListboxWindowRenderer : public WindowRenderer
52 {
53 public:
59 
65  virtual Rectf getListRenderArea(void) const = 0;
66 
73  virtual void resizeListToContent(bool fit_width,
74  bool fit_height) const = 0;
75 };
76 
81 class CEGUIEXPORT Listbox : public Window
82 {
83 public:
84  static const String EventNamespace;
85  static const String WidgetTypeName;
86 
87  /*************************************************************************
88  Constants
89  *************************************************************************/
90  // event names
129 
130  /*************************************************************************
131  Child Widget name constants
132  *************************************************************************/
133  static const String VertScrollbarName;
134  static const String HorzScrollbarName;
135 
136  /*************************************************************************
137  Accessor Methods
138  *************************************************************************/
146  size_t getItemCount(void) const {return d_listItems.size();}
147 
148 
156  size_t getSelectedCount(void) const;
157 
158 
168 
169 
184  ListboxItem* getNextSelected(const ListboxItem* start_item) const;
185 
186 
199  ListboxItem* getListboxItemFromIndex(size_t index) const;
200 
201 
214  size_t getItemIndex(const ListboxItem* item) const;
215 
216 
224  bool isSortEnabled(void) const {return d_sorted;}
225 
233  bool isMultiselectEnabled(void) const {return d_multiselect;}
234 
235  bool isItemTooltipsEnabled(void) const {return d_itemTooltips;}
236 
249  bool isItemSelected(size_t index) const;
250 
251 
269  ListboxItem* findItemWithText(const String& text, const ListboxItem* start_item);
270 
271 
279  bool isListboxItemInList(const ListboxItem* item) const;
280 
281 
290  bool isVertScrollbarAlwaysShown(void) const;
291 
292 
301  bool isHorzScrollbarAlwaysShown(void) const;
302 
303 
304  /*************************************************************************
305  Manipulator Methods
306  *************************************************************************/
317  virtual void initialiseComponents(void);
318 
319 
326  void resetList(void);
327 
328 
340  void addItem(ListboxItem* item);
341 
342 
366  void insertItem(ListboxItem* item, const ListboxItem* position);
367 
368 
380  void removeItem(const ListboxItem* item);
381 
382 
390  void clearAllSelections(void);
391 
392 
403  void setSortingEnabled(bool setting);
404 
405 
417  void setMultiselectEnabled(bool setting);
418 
419 
431  void setShowVertScrollbar(bool setting);
432 
433 
445  void setShowHorzScrollbar(bool setting);
446 
447  void setItemTooltipsEnabled(bool setting);
467  void setItemSelectState(ListboxItem* item, bool state);
468 
469 
489  void setItemSelectState(size_t item_index, bool state);
490 
491 
505 
506 
518  void ensureItemIsVisible(size_t item_index);
519 
520 
533  void ensureItemIsVisible(const ListboxItem* item);
534 
535 
545  virtual Rectf getListRenderArea(void) const;
546 
547 
560 
573 
574 
579  float getTotalItemsHeight(void) const;
580 
581 
586  float getWidestItemWidth(void) const;
587 
588 
600 
601 
602  /*************************************************************************
603  Construction and Destruction
604  *************************************************************************/
609  Listbox(const String& type, const String& name);
610 
611 
616  virtual ~Listbox(void);
617 
618 
619 protected:
620  /*************************************************************************
621  Abstract Implementation Functions (must be provided by derived class)
622  *************************************************************************/
632  //virtual Rect getListRenderArea_impl(void) const = 0;
633 
634 
635  /*************************************************************************
636  Implementation Functions
637  *************************************************************************/
643 
649  void selectRange(size_t start, size_t end);
650 
651 
660 
661 
673  bool resetList_impl(void);
674 
679  bool handle_scrollChange(const EventArgs& args);
680 
681 
682  // validate window renderer
683  virtual bool validateWindowRenderer(const WindowRenderer* renderer) const;
684 
689  void resortList();
690 
691  /*************************************************************************
692  New event handlers
693  *************************************************************************/
699 
700 
706 
707 
713 
714 
720 
721 
727 
728 
734 
735 
736  /*************************************************************************
737  Overridden Event handlers
738  *************************************************************************/
739  virtual void onSized(ElementEventArgs& e);
741  virtual void onMouseWheel(MouseEventArgs& e);
742  virtual void onMouseMove(MouseEventArgs& e);
743 
744 
745  /*************************************************************************
746  Implementation Data
747  *************************************************************************/
748  typedef std::vector<ListboxItem*
749  CEGUI_VECTOR_ALLOC(ListboxItem*)> LBItemList;
750  bool d_sorted;
755  LBItemList d_listItems;
757 
758  friend class ListboxWindowRenderer;
759 
760 private:
761 
762  /*************************************************************************
763  Private methods
764  *************************************************************************/
765  void addListboxProperties(void);
766 };
767 
768 
774 bool lbi_less(const ListboxItem* a, const ListboxItem* b);
775 
776 
782 bool lbi_greater(const ListboxItem* a, const ListboxItem* b);
783 
784 } // End of CEGUI namespace section
785 
786 
787 #if defined(_MSC_VER)
788 # pragma warning(pop)
789 #endif
790 
791 #endif // end of guard _CEGUIListbox_h_
EventArgs based class that is used for objects passed to handlers triggered for events concerning som...
Definition: Element.h:211
Base class used as the argument to all subscribers Event object.
Definition: EventArgs.h:51
Base class for list box items.
Definition: ListboxItem.h:53
Base class for Listbox window renderer.
Definition: widgets/Listbox.h:52
virtual void resizeListToContent(bool fit_width, bool fit_height) const =0
virtual Rectf getListRenderArea(void) const =0
Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used fo...
ListboxWindowRenderer(const String &name)
Constructor.
Base class for standard Listbox widget.
Definition: widgets/Listbox.h:82
virtual bool validateWindowRenderer(const WindowRenderer *renderer) const
Function used in checking if a WindowRenderer is valid for this window.
virtual void onMultiselectModeChanged(WindowEventArgs &e)
Handler called internally when the multi-select mode setting changes.
ListboxItem * getItemAtPoint(const Vector2f &pt) const
Return a pointer to the ListboxItem attached to this Listbox at the given screen pixel co-ordinate.
void ensureItemIsVisible(size_t item_index)
Ensure the item at the specified index is visible within the list box.
Scrollbar * getVertScrollbar() const
Return a pointer to the vertical scrollbar component widget for this Listbox.
void setShowHorzScrollbar(bool setting)
Set whether the horizontal scroll bar should always be shown.
void insertItem(ListboxItem *item, const ListboxItem *position)
Insert an item into the list box before a specified item already in the list.
void setItemSelectState(ListboxItem *item, bool state)
Set the select state of an attached ListboxItem.
virtual ~Listbox(void)
Destructor for Listbox base class.
virtual void onMouseButtonDown(MouseEventArgs &e)
Handler called when a mouse button has been depressed within this window's area.
virtual void onSized(ElementEventArgs &e)
Handler called when the window's size changes.
bool isHorzScrollbarAlwaysShown(void) const
Return whether the horizontal scroll bar is always shown.
virtual void initialiseComponents(void)
Initialise the Window based object ready for use.
bool isListboxItemInList(const ListboxItem *item) const
Return whether the specified ListboxItem is in the List.
LBItemList d_listItems
list of items in the list box.
Definition: widgets/Listbox.h:755
void resetList(void)
Remove all items from the list.
void removeItem(const ListboxItem *item)
Removes the given item from the list box. If the item is has the auto delete state set,...
static const String VertScrollbarName
Widget name for the vertical scrollbar component.
Definition: widgets/Listbox.h:133
static const String EventListContentsChanged
Definition: widgets/Listbox.h:95
bool d_itemTooltips
true if each item should have an individual tooltip
Definition: widgets/Listbox.h:754
void ensureItemIsVisible(const ListboxItem *item)
Ensure the item at the specified index is visible within the list box.
size_t getSelectedCount(void) const
Return the number of selected items in the list box.
float getTotalItemsHeight(void) const
Return the sum of all item heights.
virtual void onListContentsChanged(WindowEventArgs &e)
Handler called internally when the list contents are changed.
bool isVertScrollbarAlwaysShown(void) const
Return whether the vertical scroll bar is always shown.
bool handle_scrollChange(const EventArgs &args)
Internal handler that is triggered when the user interacts with the scrollbars.
float getWidestItemWidth(void) const
Return the width of the widest item.
void configureScrollbars(void)
Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used fo...
static const String WidgetTypeName
Window factory name.
Definition: widgets/Listbox.h:85
virtual void onVertScrollbarModeChanged(WindowEventArgs &e)
Handler called internally when the forced display of the vertical scroll bar setting changes.
static const String HorzScrollbarName
Widget name for the horizontal scrollbar component.
Definition: widgets/Listbox.h:134
void setSortingEnabled(bool setting)
Set whether the list should be sorted.
void clearAllSelections(void)
Clear the selected state for all items.
void addItem(ListboxItem *item)
Add the given ListboxItem to the list.
void handleUpdatedItemData(void)
Causes the list box to update it's internal state after changes have been made to one or more attache...
void setItemSelectState(size_t item_index, bool state)
Set the select state of an attached ListboxItem.
ListboxItem * findItemWithText(const String &text, const ListboxItem *start_item)
Search the list for an item with the specified text.
bool isSortEnabled(void) const
return whether list sorting is enabled
Definition: widgets/Listbox.h:224
size_t getItemIndex(const ListboxItem *item) const
Return the index of ListboxItem item.
void setShowVertScrollbar(bool setting)
Set whether the vertical scroll bar should always be shown.
ListboxItem * getListboxItemFromIndex(size_t index) const
Return the item at index position index.
virtual void onHorzScrollbarModeChanged(WindowEventArgs &e)
Handler called internally when the forced display of the horizontal scroll bar setting changes.
static const String EventMultiselectModeChanged
Definition: widgets/Listbox.h:114
void resortList()
Causes the internal list to be (re)sorted.
bool d_forceHorzScroll
true if horizontal scrollbar should always be displayed
Definition: widgets/Listbox.h:753
bool d_sorted
true if list is sorted
Definition: widgets/Listbox.h:750
bool d_multiselect
true if multi-select is enabled
Definition: widgets/Listbox.h:751
static const String EventVertScrollbarModeChanged
Definition: widgets/Listbox.h:121
Scrollbar * getHorzScrollbar() const
Return a pointer to the horizontal scrollbar component widget for this Listbox.
bool resetList_impl(void)
Remove all items from the list.
virtual Rectf getListRenderArea(void) const
Return a Rect object describing, in un-clipped pixels, the window relative area that is to be used fo...
ListboxItem * d_lastSelected
holds pointer to the last selected item (used in range selections)
Definition: widgets/Listbox.h:756
static const String EventHorzScrollbarModeChanged
Definition: widgets/Listbox.h:128
Listbox(const String &type, const String &name)
Constructor for Listbox base class.
bool clearAllSelections_impl(void)
Clear the selected state for all items (implementation)
virtual void onSortModeChanged(WindowEventArgs &e)
Handler called internally when the sort mode setting changes.
static const String EventNamespace
Namespace for global events.
Definition: widgets/Listbox.h:84
virtual void onMouseWheel(MouseEventArgs &e)
Handler called when the mouse wheel (z-axis) position changes within this window's area.
bool isMultiselectEnabled(void) const
return whether multi-select is enabled
Definition: widgets/Listbox.h:233
bool isItemSelected(size_t index) const
return whether the string at index position index is selected
ListboxItem * getFirstSelectedItem(void) const
Return a pointer to the first selected item.
void selectRange(size_t start, size_t end)
select all strings between positions start and end. (inclusive) including end.
virtual void onMouseMove(MouseEventArgs &e)
Handler called when the mouse cursor has been moved within this window's area.
bool d_forceVertScroll
true if vertical scrollbar should always be displayed
Definition: widgets/Listbox.h:752
static const String EventSortModeChanged
Definition: widgets/Listbox.h:108
size_t getItemCount(void) const
Return number of items attached to the list box.
Definition: widgets/Listbox.h:146
static const String EventSelectionChanged
Definition: widgets/Listbox.h:102
ListboxItem * getNextSelected(const ListboxItem *start_item) const
Return a pointer to the next selected item after item start_item.
virtual void onSelectionChanged(WindowEventArgs &e)
Handler called internally when the currently selected item or items changes.
void setMultiselectEnabled(bool setting)
Set whether the list should allow multiple selections or just a single selection.
EventArgs based class that is used for objects passed to input event handlers concerning mouse input.
Definition: InputEvent.h:281
Base scroll bar class.
Definition: widgets/Scrollbar.h:90
String class used within the GUI system.
Definition: String.h:64
EventArgs based class that is used for objects passed to handlers triggered for events concerning som...
Definition: InputEvent.h:252
Base-class for the assignable WindowRenderer object.
Definition: WindowRenderer.h:52
An abstract base class providing common functionality and specifying the required interface for deriv...
Definition: Window.h:151
Main namespace for Crazy Eddie's GUI Library.
Definition: arch_overview.dox:1
bool lbi_less(const ListboxItem *a, const ListboxItem *b)
Helper function used in sorting to compare two list box item text strings via the ListboxItem pointer...
bool lbi_greater(const ListboxItem *a, const ListboxItem *b)
Helper function used in sorting to compare two list box item text strings via the ListboxItem pointer...