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