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