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 licence
   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 and while the maximal number of
  21     elements is unlimited, it is usually better to use a virtual control, not
  22     requiring to add all the items to it at once, such as wxDataViewCtrl or
  23     wxListCtrl with @c wxLC_VIRTUAL style, once more than a few hundreds items
  24     need to be displayed because this control is not optimized, neither from
  25     performance nor from user interface point of view, for large number of
  26     items.
  27
  28
  29     A listbox callback gets an event @c wxEVT_COMMAND_LISTBOX_SELECTED for
  30     single clicks, and @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED for double clicks.
  31
  32     @beginStyleTable
  33     @style{wxLB_SINGLE}
  34         Single-selection list.
  35     @style{wxLB_MULTIPLE}
  36         Multiple-selection list: the user can toggle multiple items on and off.
  37         This is the same as wxLB_EXTENDED in wxGTK2 port.
  38     @style{wxLB_EXTENDED}
  39         Extended-selection list: the user can extend the selection by using
  40         @c SHIFT or @c CTRL keys together with the cursor movement keys or
  41         the mouse.
  42     @style{wxLB_HSCROLL}
  43         Create horizontal scrollbar if contents are too wide (Windows only).
  44     @style{wxLB_ALWAYS_SB}
  45         Always show a vertical scrollbar.
  46     @style{wxLB_NEEDED_SB}
  47         Only create a vertical scrollbar if needed.
  48     @style{wxLB_NO_SB}
  49         Don't create vertical scrollbar (wxMSW only).
  50     @style{wxLB_SORT}
  51         The listbox contents are sorted in alphabetical order.
  52     @endStyleTable
  53
  54     Note that @c wxLB_SINGLE, @c wxLB_MULTIPLE and @c wxLB_EXTENDED styles are
  55     mutually exclusive and you can specify at most one of them (single selection
  56     is the default). See also @ref overview_windowstyles.
  57
  58     @beginEventEmissionTable{wxCommandEvent}
  59     @event{EVT_LISTBOX(id, func)}
  60         Process a @c wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the
  61         list is selected or the selection changes.
  62     @event{EVT_LISTBOX_DCLICK(id, func)}
  63         Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the listbox
  64         is double-clicked.
  65     @endEventTable
  66
  67     @library{wxcore}
  68     @category{ctrl}
  69     @appearance{listbox.png}
  70
  71     @see wxEditableListBox, wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
  72 */
  73 class wxListBox : public wxControlWithItems
  74 {
  75 public:
  76     /**
  77         Default constructor.
  78     */
  79     wxListBox();
  80
  81     /**
  82         Constructor, creating and showing a list box.
  83
  84         @param parent
  85             The parent window.
  86         @param id
  87             The ID of this control. A value of @c wxID_ANY indicates a default value.
  88         @param pos
  89             The initial position.
  90             If ::wxDefaultPosition is specified then a default position is chosen.
  91         @param size
  92             The initial size.
  93             If ::wxDefaultSize is specified then the window is sized appropriately.
  94         @param n
  95             Number of strings with which to initialise the control.
  96         @param choices
  97             The strings to use to initialize the control.
  98         @param style
  99             Window style. See wxListBox.
 100         @param validator
 101             The validator for this control.
 102         @param name
 103             The name of this class.
 104
 105         @beginWxPerlOnly
 106         Not supported by wxPerl.
 107         @endWxPerlOnly
 108     */
 109
 110     wxListBox(wxWindow* parent, wxWindowID id,
 111               const wxPoint& pos = wxDefaultPosition,
 112               const wxSize& size = wxDefaultSize,
 113               int n = 0,
 114               const wxString choices[] = NULL,
 115               long style = 0,
 116               const wxValidator& validator = wxDefaultValidator,
 117               const wxString& name = wxListBoxNameStr);
 118
 119     /**
 120         Constructor, creating and showing a list box.
 121
 122         See the other wxListBox() constructor; the only difference is that
 123         this overload takes a wxArrayString instead of a pointer to an array
 124         of wxString.
 125
 126         @beginWxPerlOnly
 127         Use an array reference for the @a choices parameter.
 128         @endWxPerlOnly
 129     */
 130
 131     wxListBox(wxWindow* parent, wxWindowID id,
 132               const wxPoint& pos,
 133               const wxSize& size,
 134               const wxArrayString& choices,
 135               long style = 0,
 136               const wxValidator& validator = wxDefaultValidator,
 137               const wxString& name = wxListBoxNameStr);
 138
 139     /**
 140         Destructor, destroying the list box.
 141     */
 142     virtual ~wxListBox();
 143
 144     //@{
 145     /**
 146         Creates the listbox for two-step construction.
 147         See wxListBox() for further details.
 148     */
 149     bool Create(wxWindow *parent, wxWindowID id,
 150                 const wxPoint& pos = wxDefaultPosition,
 151                 const wxSize& size = wxDefaultSize,
 152                 int n = 0, const wxString choices[] = NULL,
 153                 long style = 0,
 154                 const wxValidator& validator = wxDefaultValidator,
 155                 const wxString& name = wxListBoxNameStr);
 156     bool Create(wxWindow *parent, wxWindowID id,
 157                 const wxPoint& pos,
 158                 const wxSize& size,
 159                 const wxArrayString& choices,
 160                 long style = 0,
 161                 const wxValidator& validator = wxDefaultValidator,
 162                 const wxString& name = wxListBoxNameStr);
 163     //@}
 164
 165     /**
 166         Deselects an item in the list box.
 167
 168         @param n
 169             The zero-based item to deselect.
 170
 171         @remarks This applies to multiple selection listboxes only.
 172     */
 173     void Deselect(int n);
 174
 175     virtual void SetSelection(int n);
 176
 177     virtual int GetSelection() const;
 178
 179     virtual bool SetStringSelection(const wxString& s, bool select);
 180     virtual bool SetStringSelection(const wxString& s);
 181
 182     /**
 183         Fill an array of ints with the positions of the currently selected items.
 184
 185         @param selections
 186             A reference to an wxArrayInt instance that is used to store the result of
 187             the query.
 188
 189         @return The number of selections.
 190
 191         @remarks Use this with a multiple selection listbox.
 192
 193         @beginWxPerlOnly
 194         In wxPerl this method takes no parameters and return the
 195         selected items as a list.
 196         @endWxPerlOnly
 197
 198         @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
 199              wxControlWithItems::SetSelection
 200     */
 201     virtual int GetSelections(wxArrayInt& selections) const;
 202
 203     /**
 204         Returns the item located at @a point, or @c wxNOT_FOUND if there
 205         is no item located at @a point.
 206
 207         It is currently implemented for wxMSW, wxMac and wxGTK2 ports.
 208
 209         @param point
 210             Point of item (in client coordinates) to obtain
 211
 212         @return Item located at point, or wxNOT_FOUND if unimplemented or the
 213                 item does not exist.
 214
 215         @since 2.7.0
 216     */
 217     int HitTest(const wxPoint& point) const;
 218
 219     /**
 220         @overload
 221     */
 222     int HitTest(int x, int y) const;
 223
 224     /**
 225         Insert the given number of strings before the specified position.
 226
 227         @param nItems
 228             Number of items in the array items
 229         @param items
 230             Labels of items to be inserted
 231         @param pos
 232             Position before which to insert the items: if pos is 0 the
 233             items will be inserted in the beginning of the listbox
 234
 235         @beginWxPerlOnly
 236         Not supported by wxPerl.
 237         @endWxPerlOnly
 238     */
 239     void InsertItems(unsigned int nItems, const wxString *items,
 240                      unsigned int pos);
 241
 242     /**
 243         Insert the given number of strings before the specified position.
 244
 245         @param items
 246             Labels of items to be inserted
 247         @param pos
 248             Position before which to insert the items: if pos is @c 0 the
 249             items will be inserted in the beginning of the listbox
 250
 251         @beginWxPerlOnly
 252         Use an array reference for the @a items parameter.
 253         @endWxPerlOnly
 254     */
 255     void InsertItems(const wxArrayString& items,
 256                      unsigned int pos);
 257
 258     /**
 259         Determines whether an item is selected.
 260
 261         @param n
 262             The zero-based item index.
 263
 264         @return @true if the given item is selected, @false otherwise.
 265     */
 266     virtual bool IsSelected(int n) const;
 267
 268     /**
 269         Set the specified item to be the first visible item.
 270
 271         @param n
 272             The zero-based item index that should be visible.
 273     */
 274     void SetFirstItem(int n);
 275
 276     /**
 277         Set the specified item to be the first visible item.
 278
 279         @param string
 280             The string that should be visible.
 281     */
 282     void SetFirstItem(const wxString& string);
 283
 284     /**
 285         Ensure that the item with the given index is currently shown.
 286
 287         Scroll the listbox if necessary.
 288
 289         This method is currently only implemented in wxGTK and wxOSX and does
 290         nothing in other ports.
 291
 292         @see SetFirstItem()
 293      */
 294     virtual void EnsureVisible(int n);
 295
 296     /**
 297         Return true if the listbox has ::wxLB_SORT style.
 298
 299         This method is mostly meant for internal use only.
 300      */
 301     virtual bool IsSorted() const;
 302
 303
 304     // NOTE: Phoenix needs to see the implementation of pure virtuals so it
 305     // knows that this class is not abstract.
 306     virtual unsigned int GetCount() const;
 307     virtual wxString GetString(unsigned int n) const;
 308     virtual void SetString(unsigned int n, const wxString& s);
 309     virtual int FindString(const wxString& s, bool bCase = false) const;
 310 };
 311