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 #define wxVListBoxNameStr _T("wxVListBox")
  18
  19 // ----------------------------------------------------------------------------
  20 // wxVListBox
  21 // ----------------------------------------------------------------------------
  22
  23 /*
  24     This class has two main differences from a regular listbox: it can have an
  25     arbitrarily huge number of items because it doesn't store them itself but
  26     uses OnDrawItem() callback to draw them and its items can have variable
  27     height as determined by OnMeasureItem().
  28
  29     It emits the same events as wxListBox and the same event macros may be used
  30     with it.
  31  */
  32 class WXDLLEXPORT wxVListBox : public wxVScrolledWindow
  33 {
  34 public:
  35     // constructors and such
  36     // ---------------------
  37
  38     // default constructor, you must call Create() later
  39     wxVListBox() { Init(); }
  40
  41     // normal constructor which calls Create() internally
  42     wxVListBox(wxWindow *parent,
  43                wxWindowID id = wxID_ANY,
  44                const wxPoint& pos = wxDefaultPosition,
  45                const wxSize& size = wxDefaultSize,
  46                size_t countItems = 0,
  47                long style = 0,
  48                const wxString& name = wxVListBoxNameStr)
  49     {
  50         Init();
  51
  52         (void)Create(parent, id, pos, size, countItems, style, name);
  53     }
  54
  55     // really creates the control and sets the initial number of items in it
  56     // (which may be changed later with SetItemCount())
  57     //
  58     // there are no special styles defined for wxVListBox
  59     //
  60     // returns true on success or false if the control couldn't be created
  61     bool Create(wxWindow *parent,
  62                 wxWindowID id = wxID_ANY,
  63                 const wxPoint& pos = wxDefaultPosition,
  64                 const wxSize& size = wxDefaultSize,
  65                 size_t countItems = 0,
  66                 long style = 0,
  67                 const wxString& name = wxVListBoxNameStr);
  68
  69
  70     // operations
  71     // ----------
  72
  73     // set the number of items to be shown in the control
  74     //
  75     // this is just a synonym for wxVScrolledWindow::SetLineCount()
  76     void SetItemCount(size_t count) { SetLineCount(count); }
  77
  78     // delete all items from the control
  79     void Clear() { SetItemCount(0); }
  80
  81     // set the selection to the specified item, if it is -1 the selection is
  82     // unset
  83     void SetSelection(int selection) { DoSetSelection(selection, false); }
  84
  85     // set the margins: horizontal margin is the distance between the window
  86     // border and the item contents while vertical margin is half of the
  87     // distance between items
  88     //
  89     // by default both margins are 0
  90     void SetMargins(const wxPoint& pt);
  91     void SetMargins(wxCoord x, wxCoord y) { SetMargins(wxPoint(x, y)); }
  92
  93
  94     // accessors
  95     // ---------
  96
  97     // get the number of items in the control
  98     size_t GetItemCount() const { return GetLineCount(); }
  99
 100     // get the currently selected item or -1 if there is no selection
 101     int GetSelection() const { return m_selection; }
 102
 103     // is this item selected?
 104     bool IsSelected(size_t line) const { return (int)line == m_selection; }
 105
 106     // get the margins around each item
 107     wxPoint GetMargins() const { return m_ptMargins; }
 108
 109
 110 protected:
 111     // the derived class must implement this function to actually draw the item
 112     // with the given index on the provided DC
 113     virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const = 0;
 114
 115     // the derived class must implement this method to return the height of the
 116     // specified item
 117     virtual wxCoord OnMeasureItem(size_t n) const = 0;
 118
 119     // this method may be used to draw separators between the lines; note that
 120     // the rectangle may be modified, typically to deflate it a bit before
 121     // passing to OnDrawItem()
 122     //
 123     // the base class version doesn't do anything
 124     virtual void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n) const;
 125
 126
 127     // we implement OnGetLineHeight() in terms of OnMeasureItem() because this
 128     // allows us to add borders to the items easily
 129     //
 130     // this function is not upposed to be overridden by the derived classes
 131     virtual wxCoord OnGetLineHeight(size_t line) const;
 132
 133
 134     // event handlers
 135     void OnPaint(wxPaintEvent& event);
 136     void OnKeyDown(wxKeyEvent& event);
 137     void OnLeftDown(wxMouseEvent& event);
 138     void OnLeftDClick(wxMouseEvent& event);
 139
 140
 141     // common part of all ctors
 142     void Init();
 143
 144     // SetSelection() with additional parameter telling it whether to send a
 145     // notification event or not
 146     void DoSetSelection(int selection, bool sendEvent = true);
 147
 148 private:
 149     // the current selection or -1
 150     int m_selection;
 151
 152     // margins
 153     wxPoint m_ptMargins;
 154
 155
 156     DECLARE_EVENT_TABLE()
 157 };
 158
 159 #endif // _WX_VLBOX_H_
 160