interface/wx/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
  12     A listbox is used to select one or more of a list of strings.
  13
  14     The 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 is
  16     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.
  21     Their number may be limited under some platforms.
  22
  23     A listbox callback gets an event @c wxEVT_COMMAND_LISTBOX_SELECTED for
  24     single clicks, and @c 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 off.
  31         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_NO_SB}
  43         Don't create vertical scrollbar (wxMSW only).
  44     @style{wxLB_SORT}
  45         The listbox contents are sorted in alphabetical order.
  46     @endStyleTable
  47
  48     Note that @c wxLB_SINGLE, @c wxLB_MULTIPLE and @c wxLB_EXTENDED styles are
  49     mutually exclusive and you can specify at most one of them (single selection
  50     is the default). See also @ref overview_windowstyles.
  51
  52     @beginEventEmissionTable{wxCommandEvent}
  53     @event{EVT_LISTBOX(id, func)}
  54         Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the
  55         list is selected or the selection changes.
  56     @event{EVT_LISTBOX_DCLICK(id, func)}
  57         Process a wxEVT_COMMAND_LISTBOXDOUBLECLICKED event, when the listbox
  58         is double-clicked.
  59     @endEventTable
  60
  61     @library{wxcore}
  62     @category{ctrl}
  63     @appearance{listbox.png}
  64
  65     @see wxEditableListBox, wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
  66 */
  67 class wxListBox : public wxControlWithItems
  68 {
  69 public:
  70     /**
  71         Default constructor.
  72     */
  73     wxListBox();
  74
  75     /**
  76         Constructor, creating and showing a list box.
  77
  78         @param parent
  79             The parent window.
  80         @param id
  81             The ID of this control. A value of @c wxID_ANY indicates a default value.
  82         @param pos
  83             The initial position.
  84             If ::wxDefaultPosition is specified then a default position is chosen.
  85         @param size
  86             The initial size.
  87             If ::wxDefaultSize is specified then the window is sized appropriately.
  88         @param n
  89             Number of strings with which to initialise the control.
  90         @param choices
  91             The strings to use to initialize the control.
  92         @param style
  93             Window style. See wxListBox.
  94         @param validator
  95             The validator for this control.
  96         @param name
  97             The name of this class.
  98     */
  99
 100     wxListBox(wxWindow* parent, wxWindowID id,
 101               const wxPoint& pos = wxDefaultPosition,
 102               const wxSize& size = wxDefaultSize,
 103               int n = 0,
 104               const wxString choices[] = NULL,
 105               long style = 0,
 106               const wxValidator& validator = wxDefaultValidator,
 107               const wxString& name = wxListBoxNameStr);
 108
 109     /**
 110         Constructor, creating and showing a list box.
 111
 112         See the other wxListBox() constructor; the only difference is that
 113         this overload takes a wxArrayString instead of a pointer to an array
 114         of wxString.
 115     */
 116
 117     wxListBox(wxWindow* parent, wxWindowID id,
 118               const wxPoint& pos,
 119               const wxSize& size,
 120               const wxArrayString& choices,
 121               long style = 0,
 122               const wxValidator& validator = wxDefaultValidator,
 123               const wxString& name = wxListBoxNameStr);
 124
 125     /**
 126         Destructor, destroying the list box.
 127     */
 128     virtual ~wxListBox();
 129
 130     //@{
 131     /**
 132         Creates the listbox for two-step construction.
 133         See wxListBox() for further details.
 134     */
 135     bool Create(wxWindow *parent, wxWindowID id,
 136                 const wxPoint& pos = wxDefaultPosition,
 137                 const wxSize& size = wxDefaultSize,
 138                 int n = 0, const wxString choices[] = NULL,
 139                 long style = 0,
 140                 const wxValidator& validator = wxDefaultValidator,
 141                 const wxString& name = wxListBoxNameStr);
 142     bool Create(wxWindow *parent, wxWindowID id,
 143                 const wxPoint& pos,
 144                 const wxSize& size,
 145                 const wxArrayString& choices,
 146                 long style = 0,
 147                 const wxValidator& validator = wxDefaultValidator,
 148                 const wxString& name = wxListBoxNameStr);
 149     //@}
 150
 151     /**
 152         Deselects an item in the list box.
 153
 154         @param n
 155             The zero-based item to deselect.
 156
 157         @remarks This applies to multiple selection listboxes only.
 158     */
 159     void Deselect(int n);
 160
 161     /**
 162         Fill an array of ints with the positions of the currently selected items.
 163
 164         @param selections
 165             A reference to an wxArrayInt instance that is used to store the result of
 166             the query.
 167
 168         @return The number of selections.
 169
 170         @remarks Use this with a multiple selection listbox.
 171
 172         @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
 173              wxControlWithItems::SetSelection
 174     */
 175     virtual int GetSelections(wxArrayInt& selections) const;
 176
 177     /**
 178         Returns the item located at @a point, or @c wxNOT_FOUND if there
 179         is no item located at @a point.
 180
 181         It is currently implemented for wxMSW, wxMac and wxGTK2 ports.
 182
 183         @param point
 184             Point of item (in client coordinates) to obtain
 185
 186         @return Item located at point, or wxNOT_FOUND if unimplemented or the
 187                 item does not exist.
 188
 189         @since 2.7.0
 190     */
 191     int HitTest(const wxPoint& point) const;
 192
 193     /**
 194         @overload
 195     */
 196     int HitTest(int x, int y) const;
 197
 198     /**
 199         Insert the given number of strings before the specified position.
 200
 201         @param nItems
 202             Number of items in the array items
 203         @param items
 204             Labels of items to be inserted
 205         @param pos
 206             Position before which to insert the items: if pos is 0 the
 207             items will be inserted in the beginning of the listbox
 208     */
 209     void InsertItems(unsigned int nItems, const wxString *items,
 210                      unsigned int pos);
 211
 212     /**
 213         Insert the given number of strings before the specified position.
 214
 215         @param items
 216             Labels of items to be inserted
 217         @param pos
 218             Position before which to insert the items: if pos is @c 0 the
 219             items will be inserted in the beginning of the listbox
 220     */
 221     void InsertItems(const wxArrayString& items,
 222                      unsigned int pos);
 223
 224     /**
 225         Determines whether an item is selected.
 226
 227         @param n
 228             The zero-based item index.
 229
 230         @return @true if the given item is selected, @false otherwise.
 231     */
 232     virtual bool IsSelected(int n) const;
 233
 234     /**
 235         Clears the list box and adds the given strings to it.
 236
 237         @param n
 238             The number of strings to set.
 239         @param choices
 240             An array of strings to set.
 241         @param clientData
 242             Options array of client data pointers
 243     */
 244     void Set(unsigned int n, const wxString* choices, void *clientData);
 245
 246     /**
 247         Clears the list box and adds the given strings to it.
 248         You may free the array from the calling program after this method
 249         has been called.
 250
 251         @param choices
 252             An array of strings to set.
 253         @param clientData
 254             Options array of client data pointers
 255     */
 256     void Set(const wxArrayString& choices, void *clientData);
 257
 258     /**
 259         Set the specified item to be the first visible item.
 260
 261         @param n
 262             The zero-based item index that should be visible.
 263     */
 264     void SetFirstItem(int n);
 265
 266     /**
 267         Set the specified item to be the first visible item.
 268
 269         @param string
 270             The string that should be visible.
 271     */
 272     void SetFirstItem(const wxString& string);
 273 };
 274