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 wxControl,
  75                   public wxItemContainer
  76 {
  77 public:
  78     /**
  79         Default constructor.
  80     */
  81     wxListBox();
  82
  83     /**
  84         Constructor, creating and showing a list box.
  85
  86         @param parent
  87             The parent window.
  88         @param id
  89             The ID of this control. A value of @c wxID_ANY indicates a default value.
  90         @param pos
  91             The initial position.
  92             If ::wxDefaultPosition is specified then a default position is chosen.
  93         @param size
  94             The initial size.
  95             If ::wxDefaultSize is specified then the window is sized appropriately.
  96         @param n
  97             Number of strings with which to initialise the control.
  98         @param choices
  99             The strings to use to initialize the control.
 100         @param style
 101             Window style. See wxListBox.
 102         @param validator
 103             The validator for this control.
 104         @param name
 105             The name of this class.
 106
 107         @beginWxPerlOnly
 108         Not supported by wxPerl.
 109         @endWxPerlOnly
 110     */
 111
 112     wxListBox(wxWindow* parent, wxWindowID id,
 113               const wxPoint& pos = wxDefaultPosition,
 114               const wxSize& size = wxDefaultSize,
 115               int n = 0,
 116               const wxString choices[] = NULL,
 117               long style = 0,
 118               const wxValidator& validator = wxDefaultValidator,
 119               const wxString& name = wxListBoxNameStr);
 120
 121     /**
 122         Constructor, creating and showing a list box.
 123
 124         See the other wxListBox() constructor; the only difference is that
 125         this overload takes a wxArrayString instead of a pointer to an array
 126         of wxString.
 127
 128         @beginWxPerlOnly
 129         Use an array reference for the @a choices parameter.
 130         @endWxPerlOnly
 131     */
 132
 133     wxListBox(wxWindow* parent, wxWindowID id,
 134               const wxPoint& pos,
 135               const wxSize& size,
 136               const wxArrayString& choices,
 137               long style = 0,
 138               const wxValidator& validator = wxDefaultValidator,
 139               const wxString& name = wxListBoxNameStr);
 140
 141     /**
 142         Destructor, destroying the list box.
 143     */
 144     virtual ~wxListBox();
 145
 146     //@{
 147     /**
 148         Creates the listbox for two-step construction.
 149         See wxListBox() for further details.
 150     */
 151     bool Create(wxWindow *parent, wxWindowID id,
 152                 const wxPoint& pos = wxDefaultPosition,
 153                 const wxSize& size = wxDefaultSize,
 154                 int n = 0, const wxString choices[] = NULL,
 155                 long style = 0,
 156                 const wxValidator& validator = wxDefaultValidator,
 157                 const wxString& name = wxListBoxNameStr);
 158     bool Create(wxWindow *parent, wxWindowID id,
 159                 const wxPoint& pos,
 160                 const wxSize& size,
 161                 const wxArrayString& choices,
 162                 long style = 0,
 163                 const wxValidator& validator = wxDefaultValidator,
 164                 const wxString& name = wxListBoxNameStr);
 165     //@}
 166
 167     /**
 168         Deselects an item in the list box.
 169
 170         @param n
 171             The zero-based item to deselect.
 172
 173         @remarks This applies to multiple selection listboxes only.
 174     */
 175     void Deselect(int n);
 176
 177     virtual void SetSelection(int n);
 178
 179     virtual int GetSelection() const;
 180
 181     virtual bool SetStringSelection(const wxString& s, bool select);
 182     virtual bool SetStringSelection(const wxString& s);
 183
 184     /**
 185         Fill an array of ints with the positions of the currently selected items.
 186
 187         @param selections
 188             A reference to an wxArrayInt instance that is used to store the result of
 189             the query.
 190
 191         @return The number of selections.
 192
 193         @remarks Use this with a multiple selection listbox.
 194
 195         @beginWxPerlOnly
 196         In wxPerl this method takes no parameters and return the
 197         selected items as a list.
 198         @endWxPerlOnly
 199
 200         @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
 201              wxControlWithItems::SetSelection
 202     */
 203     virtual int GetSelections(wxArrayInt& selections) const;
 204
 205     /**
 206         Returns the item located at @a point, or @c wxNOT_FOUND if there
 207         is no item located at @a point.
 208
 209         It is currently implemented for wxMSW, wxMac and wxGTK2 ports.
 210
 211         @param point
 212             Point of item (in client coordinates) to obtain
 213
 214         @return Item located at point, or wxNOT_FOUND if unimplemented or the
 215                 item does not exist.
 216
 217         @since 2.7.0
 218     */
 219     int HitTest(const wxPoint& point) const;
 220
 221     /**
 222         @overload
 223     */
 224     int HitTest(int x, int y) const;
 225
 226     /**
 227         Insert the given number of strings before the specified position.
 228
 229         @param nItems
 230             Number of items in the array items
 231         @param items
 232             Labels of items to be inserted
 233         @param pos
 234             Position before which to insert the items: if pos is 0 the
 235             items will be inserted in the beginning of the listbox
 236
 237         @beginWxPerlOnly
 238         Not supported by wxPerl.
 239         @endWxPerlOnly
 240     */
 241     void InsertItems(unsigned int nItems, const wxString *items,
 242                      unsigned int pos);
 243
 244     /**
 245         Insert the given number of strings before the specified position.
 246
 247         @param items
 248             Labels of items to be inserted
 249         @param pos
 250             Position before which to insert the items: if pos is @c 0 the
 251             items will be inserted in the beginning of the listbox
 252
 253         @beginWxPerlOnly
 254         Use an array reference for the @a items parameter.
 255         @endWxPerlOnly
 256     */
 257     void InsertItems(const wxArrayString& items,
 258                      unsigned int pos);
 259
 260     /**
 261         Determines whether an item is selected.
 262
 263         @param n
 264             The zero-based item index.
 265
 266         @return @true if the given item is selected, @false otherwise.
 267     */
 268     virtual bool IsSelected(int n) const;
 269
 270     /**
 271         Set the specified item to be the first visible item.
 272
 273         @param n
 274             The zero-based item index that should be visible.
 275     */
 276     void SetFirstItem(int n);
 277
 278     /**
 279         Set the specified item to be the first visible item.
 280
 281         @param string
 282             The string that should be visible.
 283     */
 284     void SetFirstItem(const wxString& string);
 285
 286     /**
 287         Ensure that the item with the given index is currently shown.
 288
 289         Scroll the listbox if necessary.
 290
 291         This method is currently only implemented in wxGTK and wxOSX and does
 292         nothing in other ports.
 293
 294         @see SetFirstItem()
 295      */
 296     virtual void EnsureVisible(int n);
 297
 298     /**
 299         Return true if the listbox has ::wxLB_SORT style.
 300
 301         This method is mostly meant for internal use only.
 302      */
 303     virtual bool IsSorted() const;
 304
 305
 306     // NOTE: Phoenix needs to see the implementation of pure virtuals so it
 307     // knows that this class is not abstract.
 308     virtual unsigned int GetCount() const;
 309     virtual wxString GetString(unsigned int n) const;
 310     virtual void SetString(unsigned int n, const wxString& s);
 311     virtual int FindString(const wxString& s, bool bCase = false) const;
 312 };
 313