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@wxwindows.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 protected:
 193     // the derived class must implement this function to actually draw the item
 194     // with the given index on the provided DC
 195     virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const = 0;
 196
 197     // the derived class must implement this method to return the height of the
 198     // specified item
 199     virtual wxCoord OnMeasureItem(size_t n) const = 0;
 200
 201     // this method may be used to draw separators between the lines; note that
 202     // the rectangle may be modified, typically to deflate it a bit before
 203     // passing to OnDrawItem()
 204     //
 205     // the base class version doesn't do anything
 206     virtual void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n) const;
 207
 208     // this method is used to draw the items background and, maybe, a border
 209     // around it
 210     //
 211     // the base class version implements a reasonable default behaviour which
 212     // consists in drawing the selected item with the standard background
 213     // colour and drawing a border around the item if it is either selected or
 214     // current
 215     virtual void OnDrawBackground(wxDC& dc, const wxRect& rect, size_t n) const;
 216
 217     // we implement OnGetLineHeight() in terms of OnMeasureItem() because this
 218     // allows us to add borders to the items easily
 219     //
 220     // this function is not supposed to be overridden by the derived classes
 221     virtual wxCoord OnGetLineHeight(size_t line) const;
 222
 223
 224     // event handlers
 225     void OnPaint(wxPaintEvent& event);
 226     void OnKeyDown(wxKeyEvent& event);
 227     void OnLeftDown(wxMouseEvent& event);
 228     void OnLeftDClick(wxMouseEvent& event);
 229
 230
 231     // common part of all ctors
 232     void Init();
 233
 234     // send the wxEVT_COMMAND_LISTBOX_SELECTED event
 235     void SendSelectedEvent();
 236
 237     // common implementation of SelectAll() and DeselectAll()
 238     bool DoSelectAll(bool select);
 239
 240     // change the current item (in single selection listbox it also implicitly
 241     // changes the selection); current may be wxNOT_FOUND in which case there
 242     // will be no current item any more
 243     //
 244     // return true if the current item changed, false otherwise
 245     bool DoSetCurrent(int current);
 246
 247     // flags for DoHandleItemClick
 248     enum
 249     {
 250         ItemClick_Shift = 1,        // item shift-clicked
 251         ItemClick_Ctrl  = 2,        //       ctrl
 252         ItemClick_Kbd   = 4         // item selected from keyboard
 253     };
 254
 255     // common part of keyboard and mouse handling processing code
 256     void DoHandleItemClick(int item, int flags);
 257
 258 private:
 259     // the current item or wxNOT_FOUND
 260     //
 261     // if m_selStore == NULL this is also the selected item, otherwise the
 262     // selections are managed by m_selStore
 263     int m_current;
 264
 265     // the anchor of the selection for the multiselection listboxes:
 266     // shift-clicking an item extends the selection from m_anchor to the item
 267     // clicked, for example
 268     //
 269     // always wxNOT_FOUND for single selection listboxes
 270     int m_anchor;
 271
 272     // the object managing our selected items if not NULL
 273     wxSelectionStore *m_selStore;
 274
 275     // margins
 276     wxPoint m_ptMargins;
 277
 278     // the selection bg colour
 279     wxColour m_colBgSel;
 280
 281
 282     DECLARE_EVENT_TABLE()
 283     DECLARE_NO_COPY_CLASS(wxVListBox)
 284     DECLARE_ABSTRACT_CLASS(wxVListBox)
 285 };
 286
 287 #endif // _WX_VLBOX_H_
 288