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