interface/vlbox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        vlbox.h
   3 // Purpose:     documentation for wxVListBox class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxVListBox
  11     @wxheader{vlbox.h}
  12
  13     wxVListBox is a listbox-like control with the following two main differences
  14     from a regular listbox: it can have an arbitrarily huge number of items because
  15     it doesn't store them itself but uses wxVListBox::OnDrawItem
  16     callback to draw them (so it is a Virtual listbox) and its items can
  17     have variable height as determined by
  18     wxVListBox::OnMeasureItem (so it is also a listbox
  19     with the lines of Variable height).
  20
  21     Also, as a consequence of its virtual nature, it doesn't have any methods to
  22     append or insert items in it as it isn't necessary to do it: you just have to
  23     call wxVListBox::SetItemCount to tell the control how
  24     many items it should display. Of course, this also means that you will never
  25     use this class directly because it has pure virtual functions, but will need to
  26     derive your own class, such as wxHtmlListBox, from it.
  27
  28     However it emits the same events as wxListBox and the same
  29     event macros may be used with it. Since wxVListBox does not store its items
  30     itself, the events will only contain the index, not any contents such as the
  31     string of an item.
  32
  33     @library{wxcore}
  34     @category{ctrl}
  35     @appearance{vlistbox.png}
  36
  37     @seealso
  38     wxSimpleHtmlListBox, wxHtmlListBox
  39 */
  40 class wxVListBox : public wxVScrolledWindow
  41 {
  42 public:
  43     //@{
  44     /**
  45         Default constructor, you must call Create() later.
  46     */
  47     wxVListBox(wxWindow* parent, wxWindowID id = wxID_ANY,
  48                const wxPoint& pos = wxDefaultPosition,
  49                const wxSize& size = wxDefaultSize,
  50                size_t countItems = 0, long style = 0,
  51                const wxString& name = wxVListBoxNameStr);
  52         wxVListBox();
  53     //@}
  54
  55     /**
  56         Deletes all items from the control.
  57     */
  58     void Clear();
  59
  60     /**
  61         Creates the control. To finish creating it you also should call
  62         SetItemCount() to let it know about the
  63         number of items it contains.
  64
  65         The only special style which may be used with wxVListBox is @c wxLB_MULTIPLE
  66         which indicates that the listbox should support multiple selection.
  67
  68         Returns @true on success or @false if the control couldn't be created
  69     */
  70     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
  71                 const wxPoint& pos = wxDefaultPosition,
  72                 const wxSize& size = wxDefaultSize,
  73                 long style = 0,
  74                 const wxString& name = wxVListBoxNameStr);
  75
  76     /**
  77         Deselects all the items in the listbox.
  78
  79         Returns @true if any items were changed, i.e. if there had been any
  80         selected items before, or @false if all the items were already deselected.
  81
  82         This method is only valid for multi selection listboxes.
  83
  84         @sa SelectAll(), Select()
  85     */
  86     bool DeselectAll();
  87
  88     /**
  89         Returns the index of the first selected item in the listbox or
  90         @c wxNOT_FOUND if no items are currently selected.
  91
  92         @e cookie is an opaque parameter which should be passed to the subsequent
  93         calls to GetNextSelected(). It is needed in
  94         order to allow parallel iterations over the selected items.
  95
  96         Here is a typical example of using these functions:
  97
  98         This method is only valid for multi selection listboxes.
  99     */
 100     int GetFirstSelected(unsigned long& cookie);
 101
 102     /**
 103         Get the number of items in the control.
 104
 105         @sa SetItemCount()
 106     */
 107     size_t GetItemCount();
 108
 109     /**
 110         Returns the margins used by the control. The @c x field of the returned
 111         point is the horizontal margin and the @c y field is the vertical one.
 112
 113         @sa SetMargins()
 114     */
 115     wxPoint GetMargins();
 116
 117     /**
 118         Returns the index of the next selected item or @c wxNOT_FOUND if there are
 119         no more.
 120
 121         This method is only valid for multi selection listboxes.
 122
 123         @sa GetFirstSelected()
 124     */
 125     int GetNextSelected(unsigned long& cookie);
 126
 127     /**
 128         Returns the number of the items currently selected.
 129
 130         It is valid for both single and multi selection controls. In the former case it
 131         may only return 0 or 1 however.
 132
 133         @sa IsSelected(), GetFirstSelected(),
 134               GetNextSelected()
 135     */
 136     size_t GetSelectedCount();
 137
 138     /**
 139         Get the currently selected item or @c wxNOT_FOUND if there is no selection.
 140     */
 141     int GetSelection();
 142
 143     /**
 144         Returns the background colour used for the selected cells. By default the
 145         standard system colour is used.
 146
 147         @sa wxSystemSettings::GetColour, SetSelectionBackground()
 148     */
 149     const wxColour GetSelectionBackground();
 150
 151     /**
 152         Returns @true if the listbox was created with @c wxLB_MULTIPLE style
 153         and so supports multiple selection or @false if it is a single selection
 154         listbox.
 155     */
 156     bool HasMultipleSelection();
 157
 158     /**
 159         Returns @true if this item is the current one, @false otherwise.
 160
 161         Current item is always the same as selected one for the single selection
 162         listbox and in this case this method is equivalent to
 163         IsSelected() but they are different for multi
 164         selection listboxes where many items may be selected but only one (at most) is
 165         current.
 166     */
 167     bool IsCurrent(size_t item);
 168
 169     /**
 170         Returns @true if this item is selected, @false otherwise.
 171     */
 172     bool IsSelected(size_t item);
 173
 174     /**
 175         This method is used to draw the items background and, maybe, a border
 176         around it.
 177
 178         The base class version implements a reasonable default behaviour which
 179         consists in drawing the selected item with the standard background
 180         colour and drawing a border around the item if it is either selected or
 181         current.
 182     */
 183     void OnDrawBackground(wxDC& dc, const wxRect& rect, size_t n);
 184
 185     /**
 186         The derived class must implement this function to actually draw the item
 187         with the given index on the provided DC.
 188
 189         @param dc
 190         The device context to use for drawing
 191
 192         @param rect
 193         The bounding rectangle for the item being drawn (DC clipping
 194         region is set to this rectangle before calling this function)
 195
 196         @param n
 197         The index of the item to be drawn
 198     */
 199     void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n);
 200
 201     /**
 202         This method may be used to draw separators between the lines. The rectangle
 203         passed to it may be modified, typically to deflate it a bit before passing to
 204         OnDrawItem().
 205
 206         The base class version of this method doesn't do anything.
 207
 208         @param dc
 209         The device context to use for drawing
 210
 211         @param rect
 212         The bounding rectangle for the item
 213
 214         @param n
 215         The index of the item
 216     */
 217     void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n);
 218
 219     /**
 220         The derived class must implement this method to return the height of the
 221         specified item (in pixels).
 222     */
 223     wxCoord OnMeasureItem(size_t n);
 224
 225     /**
 226         Selects or deselects the specified item which must be valid (i.e. not
 227         equal to @c wxNOT_FOUND).
 228
 229         Return @true if the items selection status has changed or @false
 230         otherwise.
 231
 232         This function is only valid for the multiple selection listboxes, use
 233         SetSelection() for the single selection ones.
 234     */
 235     bool Select(size_t item, bool select = @true);
 236
 237     /**
 238         Selects all the items in the listbox.
 239
 240         Returns @true if any items were changed, i.e. if there had been any
 241         unselected items before, or @false if all the items were already selected.
 242
 243         This method is only valid for multi selection listboxes.
 244
 245         @sa DeselectAll(), Select()
 246     */
 247     bool SelectAll();
 248
 249     /**
 250         Selects all items in the specified range which may be given in any order.
 251
 252         Return @true if the items selection status has changed or @false
 253         otherwise.
 254
 255         This method is only valid for multi selection listboxes.
 256
 257         @sa SelectAll(), Select()
 258     */
 259     bool SelectRange(size_t from, size_t to);
 260
 261     /**
 262         Set the number of items to be shown in the control.
 263
 264         This is just a synonym for
 265         wxVScrolledWindow::SetRowCount.
 266     */
 267     void SetItemCount(size_t count);
 268
 269     //@{
 270     /**
 271         Set the margins: horizontal margin is the distance between the window
 272         border and the item contents while vertical margin is half of the
 273         distance between items.
 274
 275         By default both margins are 0.
 276     */
 277     void SetMargins(const wxPoint& pt);
 278         void SetMargins(wxCoord x, wxCoord y);
 279     //@}
 280
 281     /**
 282         Set the selection to the specified item, if it is -1 the selection is
 283         unset. The selected item will be automatically scrolled into view if it isn't
 284         currently visible.
 285
 286         This method may be used both with single and multiple selection listboxes.
 287     */
 288     void SetSelection(int selection);
 289
 290     /**
 291         Sets the colour to be used for the selected cells background. The background of
 292         the standard cells may be changed by simply calling
 293         wxWindow::SetBackgroundColour.
 294
 295         Notice that using non-default background colour may result in control having
 296         appearance different from the similar native controls and so should in general
 297         be avoided.
 298
 299         @sa GetSelectionBackground()
 300     */
 301     void SetSelectionBackground(const wxColour& col);
 302
 303     /**
 304         Toggles the state of the specified @e item, i.e. selects it if it was
 305         unselected and deselects it if it was selected.
 306
 307         This method is only valid for multi selection listboxes.
 308     */
 309     void Toggle(size_t item);
 310 };