interface/listbox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        listbox.h
   3 // Purpose:     documentation for wxListBox class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxListBox
  11     @wxheader{listbox.h}
  12
  13     A listbox is used to select one or more of a list of strings. The
  14     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
  16     is 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. Their number may be limited
  21     under some platforms.
  22
  23     A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for single
  24     clicks, and
  25     wxEVT_COMMAND_LISTBOX_DOUBLE_CLICKED for double clicks.
  26
  27     @beginStyleTable
  28     @style{wxLB_SINGLE}:
  29            Single-selection list.
  30     @style{wxLB_MULTIPLE}:
  31            Multiple-selection list: the user can toggle multiple items on and
  32            off.
  33     @style{wxLB_EXTENDED}:
  34            Extended-selection list: the user can select multiple items using
  35            the SHIFT key and the mouse or special key combinations.
  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     @beginEventTable
  47     @event{EVT_LISTBOX(id\, func)}:
  48            Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the
  49            list is selected or the selection changes.
  50     @event{EVT_LISTBOX_DCLICK(id\, func)}:
  51            Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the
  52            listbox is double-clicked.
  53     @endEventTable
  54
  55     @library{wxcore}
  56     @category{ctrl}
  57     @appearance{listbox.png}
  58
  59     @seealso
  60     wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
  61 */
  62 class wxListBox : public wxControlWithItems
  63 {
  64 public:
  65     //@{
  66     /**
  67         Constructor, creating and showing a list box.
  68
  69         @param parent
  70         Parent window. Must not be @NULL.
  71
  72         @param id
  73         Window identifier. The value wxID_ANY indicates a default value.
  74
  75         @param pos
  76         Window position.
  77
  78         @param size
  79         Window size. If wxDefaultSize is specified then the window is sized
  80         appropriately.
  81
  82         @param n
  83         Number of strings with which to initialise the control.
  84
  85         @param choices
  86         An array of strings with which to initialise the control.
  87
  88         @param style
  89         Window style. See wxListBox.
  90
  91         @param validator
  92         Window validator.
  93
  94         @param name
  95         Window name.
  96
  97         @sa Create(), wxValidator
  98     */
  99     wxListBox();
 100     wxListBox(wxWindow* parent, wxWindowID id,
 101               const wxPoint& pos = wxDefaultPosition,
 102               const wxSize& size = wxDefaultSize,
 103               int n = 0,
 104               const wxString choices[] = @NULL,
 105               long style = 0,
 106               const wxValidator& validator = wxDefaultValidator,
 107               const wxString& name = "listBox");
 108     wxListBox(wxWindow* parent, wxWindowID id,
 109               const wxPoint& pos,
 110               const wxSize& size,
 111               const wxArrayString& choices,
 112               long style = 0,
 113               const wxValidator& validator = wxDefaultValidator,
 114               const wxString& name = "listBox");
 115     //@}
 116
 117     /**
 118         Destructor, destroying the list box.
 119     */
 120     ~wxListBox();
 121
 122     //@{
 123     /**
 124         Creates the listbox for two-step construction. See wxListBox()
 125         for further details.
 126     */
 127     bool Create(wxWindow* parent, wxWindowID id,
 128                 const wxPoint& pos = wxDefaultPosition,
 129                 const wxSize& size = wxDefaultSize,
 130                 int n,
 131                 const wxString choices[] = @NULL,
 132                 long style = 0,
 133                 const wxValidator& validator = wxDefaultValidator,
 134                 const wxString& name = "listBox");
 135     bool Create(wxWindow* parent, wxWindowID id,
 136                 const wxPoint& pos,
 137                 const wxSize& size,
 138                 const wxArrayString& choices,
 139                 long style = 0,
 140                 const wxValidator& validator = wxDefaultValidator,
 141                 const wxString& name = "listBox");
 142     //@}
 143
 144     /**
 145         Deselects an item in the list box.
 146
 147         @param n
 148         The zero-based item to deselect.
 149
 150         @remarks This applies to multiple selection listboxes only.
 151     */
 152     void Deselect(int n);
 153
 154     /**
 155         Fill an array of ints with the positions of the currently selected items.
 156
 157         @param selections
 158         A reference to an wxArrayInt instance that is used to store the result of the
 159         query.
 160
 161         @returns The number of selections.
 162
 163         @remarks Use this with a multiple selection listbox.
 164
 165         @sa wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
 166               wxControlWithItems::SetSelection
 167     */
 168     int GetSelections(wxArrayInt& selections);
 169
 170     /**
 171         Returns the item located at @e point, or @c wxNOT_FOUND if there
 172         is no item located at @e point.
 173
 174         This function is new since wxWidgets version 2.7.0. It is currently implemented
 175         for wxMSW, wxMac and wxGTK2
 176         ports.
 177
 178         @param point
 179         Point of item (in client coordinates) to obtain
 180
 181         @returns Item located at point, or wxNOT_FOUND if unimplemented or the
 182                    item does not exist.
 183     */
 184     int HitTest(const wxPoint point);
 185
 186     //@{
 187     /**
 188         Insert the given number of strings before the specified position.
 189
 190         @param nItems
 191         Number of items in the array items
 192
 193         @param items
 194         Labels of items to be inserted
 195
 196         @param pos
 197         Position before which to insert the items: for example, if pos is 0 the items
 198         will be inserted in the beginning of the listbox
 199     */
 200     void InsertItems(int nItems, const wxString items,
 201                      unsigned int pos);
 202     void InsertItems(const wxArrayString& nItems,
 203                      unsigned int pos);
 204     //@}
 205
 206     /**
 207         Determines whether an item is selected.
 208
 209         @param n
 210         The zero-based item index.
 211
 212         @returns @true if the given item is selected, @false otherwise.
 213     */
 214     bool IsSelected(int n);
 215
 216     //@{
 217     /**
 218         Clears the list box and adds the given strings to it.
 219
 220         @param n
 221         The number of strings to set.
 222
 223         @param choices
 224         An array of strings to set.
 225
 226         @param clientData
 227         Options array of client data pointers
 228
 229         @remarks You may free the array from the calling program after this
 230                    function has been called.
 231     */
 232     void Set(int n, const wxString* choices, void clientData = @NULL);
 233     void Set(const wxArrayString& choices,
 234              void clientData = @NULL);
 235     //@}
 236
 237     //@{
 238     /**
 239         Set the specified item to be the first visible item.
 240
 241         @param n
 242         The zero-based item index.
 243
 244         @param string
 245         The string that should be visible.
 246     */
 247     void SetFirstItem(int n);
 248     void SetFirstItem(const wxString& string);
 249     //@}
 250 };