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