interface/vlbox.h

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