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