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