interface/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     @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     @see wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
  60 */
  61 class wxListBox : public wxControlWithItems
  62 {
  63 public:
  64     //@{
  65     /**
  66         Constructor, creating and showing a list box.
  67
  68         @param parent
  69             Parent window. Must not be @NULL.
  70         @param id
  71             Window identifier. The value wxID_ANY indicates a default value.
  72         @param pos
  73             Window position.
  74         @param size
  75             Window size. If wxDefaultSize is specified then the window is
  76         sized
  77             appropriately.
  78         @param n
  79             Number of strings with which to initialise the control.
  80         @param choices
  81             An array of strings with which to initialise the control.
  82         @param style
  83             Window style. See wxListBox.
  84         @param validator
  85             Window validator.
  86         @param name
  87             Window name.
  88
  89         @see Create(), wxValidator
  90     */
  91     wxListBox();
  92     wxListBox(wxWindow* parent, wxWindowID id,
  93               const wxPoint& pos = wxDefaultPosition,
  94               const wxSize& size = wxDefaultSize,
  95               int n = 0,
  96               const wxString choices[] = NULL,
  97               long style = 0,
  98               const wxValidator& validator = wxDefaultValidator,
  99               const wxString& name = "listBox");
 100     wxListBox(wxWindow* parent, wxWindowID id,
 101               const wxPoint& pos,
 102               const wxSize& size,
 103               const wxArrayString& choices,
 104               long style = 0,
 105               const wxValidator& validator = wxDefaultValidator,
 106               const wxString& name = "listBox");
 107     //@}
 108
 109     /**
 110         Destructor, destroying the list box.
 111     */
 112     ~wxListBox();
 113
 114     //@{
 115     /**
 116         Creates the listbox for two-step construction. See wxListBox()
 117         for further details.
 118     */
 119     bool Create(wxWindow* parent, wxWindowID id,
 120                 const wxPoint& pos = wxDefaultPosition,
 121                 const wxSize& size = wxDefaultSize,
 122                 int n,
 123                 const wxString choices[] = NULL,
 124                 long style = 0,
 125                 const wxValidator& validator = wxDefaultValidator,
 126                 const wxString& name = "listBox");
 127     bool Create(wxWindow* parent, wxWindowID id,
 128                 const wxPoint& pos,
 129                 const wxSize& size,
 130                 const wxArrayString& choices,
 131                 long style = 0,
 132                 const wxValidator& validator = wxDefaultValidator,
 133                 const wxString& name = "listBox");
 134     //@}
 135
 136     /**
 137         Deselects an item in the list box.
 138
 139         @param n
 140             The zero-based item to deselect.
 141
 142         @remarks This applies to multiple selection listboxes only.
 143     */
 144     void Deselect(int n);
 145
 146     /**
 147         Fill an array of ints with the positions of the currently selected items.
 148
 149         @param selections
 150             A reference to an wxArrayInt instance that is used to store the result of
 151         the query.
 152
 153         @returns The number of selections.
 154
 155         @remarks Use this with a multiple selection listbox.
 156
 157         @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
 158              wxControlWithItems::SetSelection
 159     */
 160     int GetSelections(wxArrayInt& selections) const;
 161
 162     /**
 163         Returns the item located at @e point, or @c wxNOT_FOUND if there
 164         is no item located at @e point.
 165
 166         @wxsince{2.7.0}. It is currently implemented
 167         for wxMSW, wxMac and wxGTK2
 168         ports.
 169
 170         @param point
 171             Point of item (in client coordinates) to obtain
 172
 173         @returns Item located at point, or wxNOT_FOUND if unimplemented or the
 174                  item does not exist.
 175     */
 176     int HitTest(const wxPoint point) const;
 177
 178     //@{
 179     /**
 180         Insert the given number of strings before the specified position.
 181
 182         @param nItems
 183             Number of items in the array items
 184         @param items
 185             Labels of items to be inserted
 186         @param pos
 187             Position before which to insert the items: for example, if pos is 0 the
 188         items
 189             will be inserted in the beginning of the listbox
 190     */
 191     void InsertItems(int nItems, const wxString items,
 192                      unsigned int pos);
 193     void InsertItems(const wxArrayString& nItems,
 194                      unsigned int pos);
 195     //@}
 196
 197     /**
 198         Determines whether an item is selected.
 199
 200         @param n
 201             The zero-based item index.
 202
 203         @returns @true if the given item is selected, @false otherwise.
 204     */
 205     bool IsSelected(int n) const;
 206
 207     //@{
 208     /**
 209         Clears the list box and adds the given strings to it.
 210
 211         @param n
 212             The number of strings to set.
 213         @param choices
 214             An array of strings to set.
 215         @param clientData
 216             Options array of client data pointers
 217
 218         @remarks You may free the array from the calling program after this
 219                  function has been called.
 220     */
 221     void Set(int n, const wxString* choices, void clientData = NULL);
 222     void Set(const wxArrayString& choices,
 223              void clientData = NULL);
 224     //@}
 225
 226     //@{
 227     /**
 228         Set the specified item to be the first visible item.
 229
 230         @param n
 231             The zero-based item index.
 232         @param string
 233             The string that should be visible.
 234     */
 235     void SetFirstItem(int n);
 236     void SetFirstItem(const wxString& string);
 237     //@}
 238 };
 239