include/wx/vlbox.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/vlbox.h
   3 // Purpose:     wxVListBox is a virtual listbox with lines of variable height
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     31.05.03
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2003 Vadim Zeitlin <vadim@wxwidgets.org>
   9 // Licence:     wxWindows licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_VLBOX_H_
  13 #define _WX_VLBOX_H_
  14
  15 #include "wx/vscroll.h"         // base class
  16
  17 class WXDLLEXPORT wxSelectionStore;
  18
  19 #define wxVListBoxNameStr _T("wxVListBox")
  20
  21 // ----------------------------------------------------------------------------
  22 // wxVListBox
  23 // ----------------------------------------------------------------------------
  24
  25 /*
  26     This class has two main differences from a regular listbox: it can have an
  27     arbitrarily huge number of items because it doesn't store them itself but
  28     uses OnDrawItem() callback to draw them and its items can have variable
  29     height as determined by OnMeasureItem().
  30
  31     It emits the same events as wxListBox and the same event macros may be used
  32     with it.
  33  */
  34 class WXDLLEXPORT wxVListBox : public wxVScrolledWindow
  35 {
  36 public:
  37     // constructors and such
  38     // ---------------------
  39
  40     // default constructor, you must call Create() later
  41     wxVListBox() { Init(); }
  42
  43     // normal constructor which calls Create() internally
  44     wxVListBox(wxWindow *parent,
  45                wxWindowID id = wxID_ANY,
  46                const wxPoint& pos = wxDefaultPosition,
  47                const wxSize& size = wxDefaultSize,
  48                long style = 0,
  49                const wxString& name = wxVListBoxNameStr)
  50     {
  51         Init();
  52
  53         (void)Create(parent, id, pos, size, style, name);
  54     }
  55
  56     // really creates the control and sets the initial number of items in it
  57     // (which may be changed later with SetItemCount())
  58     //
  59     // the only special style which may be specified here is wxLB_MULTIPLE
  60     //
  61     // returns true on success or false if the control couldn't be created
  62     bool Create(wxWindow *parent,
  63                 wxWindowID id = wxID_ANY,
  64                 const wxPoint& pos = wxDefaultPosition,
  65                 const wxSize& size = wxDefaultSize,
  66                 long style = 0,
  67                 const wxString& name = wxVListBoxNameStr);
  68
  69     // dtor does some internal cleanup (deletes m_selStore if any)
  70     virtual ~wxVListBox();
  71
  72
  73     // accessors
  74     // ---------
  75
  76     // get the number of items in the control
  77     size_t GetItemCount() const { return GetLineCount(); }
  78
  79     // does this control use multiple selection?
  80     bool HasMultipleSelection() const { return m_selStore != NULL; }
  81
  82     // get the currently selected item or wxNOT_FOUND if there is no selection
  83     //
  84     // this method is only valid for the single selection listboxes
  85     int GetSelection() const
  86     {
  87         wxASSERT_MSG( !HasMultipleSelection(),
  88                         _T("GetSelection() can't be used with wxLB_MULTIPLE") );
  89
  90         return m_current;
  91     }
  92
  93     // is this item the current one?
  94     bool IsCurrent(size_t item) const { return item == (size_t)m_current; }
  95     #ifdef __WXUNIVERSAL__
  96     bool IsCurrent() const { return wxVScrolledWindow::IsCurrent(); }
  97     #endif
  98
  99     // is this item selected?
 100     bool IsSelected(size_t item) const;
 101
 102     // get the number of the selected items (maybe 0)
 103     //
 104     // this method is valid for both single and multi selection listboxes
 105     size_t GetSelectedCount() const;
 106
 107     // get the first selected item, returns wxNOT_FOUND if none
 108     //
 109     // cookie is an opaque parameter which should be passed to
 110     // GetNextSelected() later
 111     //
 112     // this method is only valid for the multi selection listboxes
 113     int GetFirstSelected(unsigned long& cookie) const;
 114
 115     // get next selection item, return wxNOT_FOUND if no more
 116     //
 117     // cookie must be the same parameter that was passed to GetFirstSelected()
 118     // before
 119     //
 120     // this method is only valid for the multi selection listboxes
 121     int GetNextSelected(unsigned long& cookie) const;
 122
 123     // get the margins around each item
 124     wxPoint GetMargins() const { return m_ptMargins; }
 125
 126     // get the background colour of selected cells
 127     const wxColour& GetSelectionBackground() const { return m_colBgSel; }
 128
 129
 130     // operations
 131     // ----------
 132
 133     // set the number of items to be shown in the control
 134     //
 135     // this is just a synonym for wxVScrolledWindow::SetLineCount()
 136     virtual void SetItemCount(size_t count);
 137
 138     // delete all items from the control
 139     void Clear() { SetItemCount(0); }
 140
 141     // set the selection to the specified item, if it is wxNOT_FOUND the
 142     // selection is unset
 143     //
 144     // this function is only valid for the single selection listboxes
 145     void SetSelection(int selection);
 146
 147     // selects or deselects the specified item which must be valid (i.e. not
 148     // equal to wxNOT_FOUND)
 149     //
 150     // return true if the items selection status has changed or false
 151     // otherwise
 152     //
 153     // this function is only valid for the multiple selection listboxes
 154     bool Select(size_t item, bool select = true);
 155
 156     // selects the items in the specified range whose end points may be given
 157     // in any order
 158     //
 159     // return true if any items selection status has changed, false otherwise
 160     //
 161     // this function is only valid for the single selection listboxes
 162     bool SelectRange(size_t from, size_t to);
 163
 164     // toggle the selection of the specified item (must be valid)
 165     //
 166     // this function is only valid for the multiple selection listboxes
 167     void Toggle(size_t item) { Select(item, !IsSelected(item)); }
 168
 169     // select all items in the listbox
 170     //
 171     // the return code indicates if any items were affected by this operation
 172     // (true) or if nothing has changed (false)
 173     bool SelectAll() { return DoSelectAll(true); }
 174
 175     // unselect all items in the listbox
 176     //
 177     // the return code has the same meaning as for SelectAll()
 178     bool DeselectAll() { return DoSelectAll(false); }
 179
 180     // set the margins: horizontal margin is the distance between the window
 181     // border and the item contents while vertical margin is half of the
 182     // distance between items
 183     //
 184     // by default both margins are 0
 185     void SetMargins(const wxPoint& pt);
 186     void SetMargins(wxCoord x, wxCoord y) { SetMargins(wxPoint(x, y)); }
 187
 188     // change the background colour of the selected cells
 189     void SetSelectionBackground(const wxColour& col);
 190
 191
 192     virtual wxVisualAttributes GetDefaultAttributes() const
 193     {
 194         return GetClassDefaultAttributes(GetWindowVariant());
 195     }
 196
 197     static wxVisualAttributes
 198     GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
 199
 200 protected:
 201     // the derived class must implement this function to actually draw the item
 202     // with the given index on the provided DC
 203     virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const = 0;
 204
 205     // the derived class must implement this method to return the height of the
 206     // specified item
 207     virtual wxCoord OnMeasureItem(size_t n) const = 0;
 208
 209     // this method may be used to draw separators between the lines; note that
 210     // the rectangle may be modified, typically to deflate it a bit before
 211     // passing to OnDrawItem()
 212     //
 213     // the base class version doesn't do anything
 214     virtual void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n) const;
 215
 216     // this method is used to draw the items background and, maybe, a border
 217     // around it
 218     //
 219     // the base class version implements a reasonable default behaviour which
 220     // consists in drawing the selected item with the standard background
 221     // colour and drawing a border around the item if it is either selected or
 222     // current
 223     virtual void OnDrawBackground(wxDC& dc, const wxRect& rect, size_t n) const;
 224
 225     // we implement OnGetLineHeight() in terms of OnMeasureItem() because this
 226     // allows us to add borders to the items easily
 227     //
 228     // this function is not supposed to be overridden by the derived classes
 229     virtual wxCoord OnGetLineHeight(size_t line) const;
 230
 231
 232     // event handlers
 233     void OnPaint(wxPaintEvent& event);
 234     void OnKeyDown(wxKeyEvent& event);
 235     void OnLeftDown(wxMouseEvent& event);
 236     void OnLeftDClick(wxMouseEvent& event);
 237
 238
 239     // common part of all ctors
 240     void Init();
 241
 242     // send the wxEVT_COMMAND_LISTBOX_SELECTED event
 243     void SendSelectedEvent();
 244
 245     // common implementation of SelectAll() and DeselectAll()
 246     bool DoSelectAll(bool select);
 247
 248     // change the current item (in single selection listbox it also implicitly
 249     // changes the selection); current may be wxNOT_FOUND in which case there
 250     // will be no current item any more
 251     //
 252     // return true if the current item changed, false otherwise
 253     bool DoSetCurrent(int current);
 254
 255     // flags for DoHandleItemClick
 256     enum
 257     {
 258         ItemClick_Shift = 1,        // item shift-clicked
 259         ItemClick_Ctrl  = 2,        //       ctrl
 260         ItemClick_Kbd   = 4         // item selected from keyboard
 261     };
 262
 263     // common part of keyboard and mouse handling processing code
 264     void DoHandleItemClick(int item, int flags);
 265
 266 private:
 267     // the current item or wxNOT_FOUND
 268     //
 269     // if m_selStore == NULL this is also the selected item, otherwise the
 270     // selections are managed by m_selStore
 271     int m_current;
 272
 273     // the anchor of the selection for the multiselection listboxes:
 274     // shift-clicking an item extends the selection from m_anchor to the item
 275     // clicked, for example
 276     //
 277     // always wxNOT_FOUND for single selection listboxes
 278     int m_anchor;
 279
 280     // the object managing our selected items if not NULL
 281     wxSelectionStore *m_selStore;
 282
 283     // margins
 284     wxPoint m_ptMargins;
 285
 286     // the selection bg colour
 287     wxColour m_colBgSel;
 288
 289
 290     DECLARE_EVENT_TABLE()
 291     DECLARE_NO_COPY_CLASS(wxVListBox)
 292     DECLARE_ABSTRACT_CLASS(wxVListBox)
 293 };
 294
 295 #endif // _WX_VLBOX_H_
 296