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