interface/listbox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        listbox.h
   3 // Purpose:     interface of wxListBox
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxListBox
  11     @wxheader{listbox.h}
  12
  13     A listbox is used to select one or more of a list of strings. The
  14     strings are displayed in a scrolling box, with the selected string(s)
  15     marked in reverse video. A listbox can be single selection (if an item
  16     is selected, the previous selection is removed) or multiple selection
  17     (clicking an item toggles the item on or off independently of other
  18     selections).
  19
  20     List box elements are numbered from zero. Their number may be limited
  21     under some platforms.
  22
  23     A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for
  24     single clicks, and wxEVT_COMMAND_LISTBOX_DOUBLECLICKED for double clicks.
  25
  26     @beginStyleTable
  27     @style{wxLB_SINGLE}
  28            Single-selection list.
  29     @style{wxLB_MULTIPLE}
  30            Multiple-selection list: the user can toggle multiple items on and
  31            off. This is the same as wxLB_EXTENDED in wxGTK2 port.
  32     @style{wxLB_EXTENDED}
  33            Extended-selection list: the user can extend the selection by using
  34            @c SHIFT or @c CTRL keys together with the cursor movement keys or
  35            the mouse.
  36     @style{wxLB_HSCROLL}
  37            Create horizontal scrollbar if contents are too wide (Windows only).
  38     @style{wxLB_ALWAYS_SB}
  39            Always show a vertical scrollbar.
  40     @style{wxLB_NEEDED_SB}
  41            Only create a vertical scrollbar if needed.
  42     @style{wxLB_SORT}
  43            The listbox contents are sorted in alphabetical order.
  44     @endStyleTable
  45
  46     @beginEventTable{wxCommandEvent}
  47     @event{EVT_LISTBOX(id, func)}
  48            Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the
  49            list is selected or the selection changes.
  50     @event{EVT_LISTBOX_DCLICK(id, func)}
  51            Process a wxEVT_COMMAND_LISTBOXDOUBLECLICKED event, when the
  52            listbox is double-clicked.
  53     @endEventTable
  54
  55     @library{wxcore}
  56     @category{ctrl}
  57     <!-- @appearance{listbox.png} -->
  58
  59     @see wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
  60 */
  61 class wxListBox : public wxControlWithItems
  62 {
  63 public:
  64     /**
  65         Default constructor.
  66     */
  67     wxListBox();
  68
  69     /**
  70         Constructor
  71
  72         @param n
  73             Number of strings with which to initialise the control.
  74         @param style
  75             Window style. See wxListBox.
  76     */
  77
  78     wxListBox(wxWindow* parent, wxWindowID id,
  79               const wxPoint& pos = wxDefaultPosition,
  80               const wxSize& size = wxDefaultSize,
  81               int n = 0,
  82               const wxString choices[] = NULL,
  83               long style = 0,
  84               const wxValidator& validator = wxDefaultValidator,
  85               const wxString& name = "listBox");
  86
  87     /**
  88         Constructor
  89
  90         @param choices
  91             An array of strings with which to initialise the control.
  92         @param style
  93             Window style. See wxListBox.
  94     */
  95
  96     wxListBox(wxWindow* parent, wxWindowID id,
  97               const wxPoint& pos,
  98               const wxSize& size,
  99               const wxArrayString& choices,
 100               long style = 0,
 101               const wxValidator& validator = wxDefaultValidator,
 102               const wxString& name = "listBox");
 103
 104     /**
 105         Destructor, destroying the list box.
 106     */
 107     ~wxListBox();
 108
 109     //@{
 110     /**
 111         Creates the listbox for two-step construction. See wxListBox()
 112         for further details.
 113     */
 114     bool Create(wxWindow* parent, wxWindowID id,
 115                 const wxPoint& pos = wxDefaultPosition,
 116                 const wxSize& size = wxDefaultSize,
 117                 int n,
 118                 const wxString choices[] = NULL,
 119                 long style = 0,
 120                 const wxValidator& validator = wxDefaultValidator,
 121                 const wxString& name = "listBox");
 122     bool Create(wxWindow* parent, wxWindowID id,
 123                 const wxPoint& pos,
 124                 const wxSize& size,
 125                 const wxArrayString& choices,
 126                 long style = 0,
 127                 const wxValidator& validator = wxDefaultValidator,
 128                 const wxString& name = "listBox");
 129     //@}
 130
 131     /**
 132         Deselects an item in the list box.
 133
 134         @param n
 135             The zero-based item to deselect.
 136
 137         @remarks This applies to multiple selection listboxes only.
 138     */
 139     void Deselect(int n);
 140
 141     /**
 142         Fill an array of ints with the positions of the currently selected items.
 143
 144         @param selections
 145             A reference to an wxArrayInt instance that is used to store the result of
 146         the query.
 147
 148         @return The number of selections.
 149
 150         @remarks Use this with a multiple selection listbox.
 151
 152         @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
 153              wxControlWithItems::SetSelection
 154     */
 155     int GetSelections(wxArrayInt& selections) const;
 156
 157     /**
 158         Returns the item located at @e point, or @c wxNOT_FOUND if there
 159         is no item located at @e point.
 160
 161         It is currently implemented for wxMSW, wxMac and wxGTK2 ports.
 162
 163         @param point
 164             Point of item (in client coordinates) to obtain
 165
 166         @return Item located at point, or wxNOT_FOUND if unimplemented or the
 167                  item does not exist.
 168
 169         @since 2.7.0
 170     */
 171     int HitTest(const wxPoint point) const;
 172
 173     /**
 174         Insert the given number of strings before the specified position.
 175
 176         @param nItems
 177             Number of items in the array items
 178         @param items
 179             Labels of items to be inserted
 180         @param pos
 181             Position before which to insert the items: if pos is 0 the
 182             items will be inserted in the beginning of the listbox
 183     */
 184     void InsertItems(int nItems, const wxString *items,
 185                      unsigned int pos);
 186
 187     /**
 188         Insert the given number of strings before the specified position.
 189
 190         @param items
 191             Labels of items to be inserted
 192         @param pos
 193             Position before which to insert the items: if pos is 0 the
 194             items will be inserted in the beginning of the listbox
 195     */
 196     void InsertItems(const wxArrayString& items,
 197                      unsigned int pos);
 198
 199     /**
 200         Determines whether an item is selected.
 201
 202         @param n
 203             The zero-based item index.
 204
 205         @return @true if the given item is selected, @false otherwise.
 206     */
 207     bool IsSelected(int n) const;
 208
 209     /**
 210         Clears the list box and adds the given strings to it.
 211
 212         @param n
 213             The number of strings to set.
 214         @param choices
 215             An array of strings to set.
 216         @param clientData
 217             Options array of client data pointers
 218     */
 219     void Set(int n, const wxString* choices, void **clientData = NULL);
 220
 221     /**
 222         Clears the list box and adds the given strings to it. You may
 223         free the array from the calling program after this method
 224         has been called.
 225
 226         @param choices
 227             An array of strings to set.
 228         @param clientData
 229             Options array of client data pointers
 230     */
 231     void Set(const wxArrayString& choices,
 232              void **clientData = NULL);
 233
 234     /**
 235         Set the specified item to be the first visible item.
 236
 237         @param n
 238             The zero-based item index that should be visible.
 239     */
 240     void SetFirstItem(int n);
 241
 242     /**
 243         Set the specified item to be the first visible item.
 244
 245         @param string
 246             The string that should be visible.
 247     */
 248     void SetFirstItem(const wxString& string);
 249 };
 250