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