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