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