interface/odcombo.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        odcombo.h
   3 // Purpose:     documentation for wxOwnerDrawnComboBox class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxOwnerDrawnComboBox
  11     @wxheader{odcombo.h}
  12
  13     wxOwnerDrawnComboBox is a combobox with owner-drawn list items.
  14     In essence, it is a wxComboCtrl with
  15     wxVListBox popup and wxControlWithItems
  16     interface.
  17
  18     Implementing item drawing and measuring is similar to wxVListBox.
  19     Application needs to subclass wxOwnerDrawnComboBox and implement
  20     wxOwnerDrawnComboBox::OnDrawItem, wxOwnerDrawnComboBox::OnMeasureItem
  21     and wxOwnerDrawnComboBox::OnMeasureItemWidth.
  22
  23     @beginStyleTable
  24     @style{wxODCB_DCLICK_CYCLES}:
  25            Double-clicking cycles item if wxCB_READONLY is also used.
  26            Synonymous with wxCC_SPECIAL_DCLICK.
  27     @style{wxODCB_STD_CONTROL_PAINT}:
  28            Control itself is not custom painted using OnDrawItem. Even if this
  29            style is not used, writable wxOwnerDrawnComboBox is never custom
  30            painted unless SetCustomPaintWidth is called.
  31     @endStyleTable
  32
  33     @beginEventTable
  34     @event{EVT_COMBOBOX(id\, func)}:
  35            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
  36            the list is selected. Note that calling GetValue returns the new
  37            value of selection.
  38     @endEventTable
  39
  40     @library{wxadv}
  41     @category{ctrl}
  42     @appearance{ownerdrawncombobox.png}
  43
  44     @seealso
  45     wxComboCtrl, wxComboBox, wxVListBox, wxCommandEvent
  46 */
  47 class wxOwnerDrawnComboBox : public wxComboCtrl
  48 {
  49 public:
  50     //@{
  51     /**
  52         Constructor, creating and showing a owner-drawn combobox.
  53
  54         @param parent
  55         Parent window. Must not be @NULL.
  56
  57         @param id
  58         Window identifier. The value wxID_ANY indicates a default value.
  59
  60         @param value
  61         Initial selection string. An empty string indicates no selection.
  62
  63         @param pos
  64         Window position.
  65
  66         @param size
  67         Window size. If wxDefaultSize is specified then the window is sized
  68         appropriately.
  69
  70         @param n
  71         Number of strings with which to initialise the control.
  72
  73         @param choices
  74         An array of strings with which to initialise the control.
  75
  76         @param style
  77         Window style. See wxOwnerDrawnComboBox.
  78
  79         @param validator
  80         Window validator.
  81
  82         @param name
  83         Window name.
  84
  85         @sa Create(), wxValidator
  86     */
  87     wxOwnerDrawnComboBox();
  88     wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id,
  89                          const wxString& value = "",
  90                          const wxPoint& pos = wxDefaultPosition,
  91                          const wxSize& size = wxDefaultSize,
  92                          int n = 0,
  93                          const wxString choices[] = @NULL,
  94                          long style = 0,
  95                          const wxValidator& validator = wxDefaultValidator,
  96                          const wxString& name = "comboBox");
  97     wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id,
  98                          const wxString& value,
  99                          const wxPoint& pos,
 100                          const wxSize& size,
 101                          const wxArrayString& choices,
 102                          long style = 0,
 103                          const wxValidator& validator = wxDefaultValidator,
 104                          const wxString& name = "comboBox");
 105     //@}
 106
 107     /**
 108         Destructor, destroying the owner-drawn combobox.
 109     */
 110     ~wxOwnerDrawnComboBox();
 111
 112     //@{
 113     /**
 114         Creates the combobox for two-step construction. Derived classes
 115         should call or replace this function. See
 116         wxOwnerDrawnComboBox()
 117         for further details.
 118     */
 119     bool Create(wxWindow* parent, wxWindowID id,
 120                 const wxString& value = "",
 121                 const wxPoint& pos = wxDefaultPosition,
 122                 const wxSize& size = wxDefaultSize,
 123                 int n, const wxString choices[],
 124                 long style = 0,
 125                 const wxValidator& validator = wxDefaultValidator,
 126                 const wxString& name = "comboBox");
 127     bool Create(wxWindow* parent, wxWindowID id,
 128                 const wxString& value,
 129                 const wxPoint& pos,
 130                 const wxSize& size,
 131                 const wxArrayString& choices,
 132                 long style = 0,
 133                 const wxValidator& validator = wxDefaultValidator,
 134                 const wxString& name = "comboBox");
 135     //@}
 136
 137     /**
 138         Returns index to the widest item in the list.
 139     */
 140     int GetWidestItem();
 141
 142     /**
 143         Returns width of the widest item in the list.
 144     */
 145     int GetWidestItemWidth();
 146
 147     /**
 148         This method is used to draw the items background and, maybe, a border around it.
 149
 150         The base class version implements a reasonable default behaviour which consists
 151         in drawing the selected item with the standard background colour and drawing a
 152         border around the item if it is either selected or current.
 153
 154         @remarks flags has the same meaning as with OnDrawItem.
 155     */
 156     void OnDrawBackground(wxDC& dc, const wxRect& rect, int item,
 157                           int flags);
 158
 159     /**
 160         The derived class may implement this function to actually draw the item
 161         with the given index on the provided DC. If function is not implemented,
 162         the item text is simply drawn, as if the control was a normal combobox.
 163
 164         @param dc
 165         The device context to use for drawing
 166
 167         @param rect
 168         The bounding rectangle for the item being drawn (DC clipping
 169         region is set to this rectangle before calling this function)
 170
 171         @param item
 172         The index of the item to be drawn
 173
 174         @param flags
 175         Combines any of the following flag values:
 176     */
 177     void OnDrawItem(wxDC& dc, const wxRect& rect, int item,
 178                     int flags);
 179
 180     /**
 181         The derived class may implement this method to return the height of the
 182         specified item (in pixels).
 183
 184         The default implementation returns text height, as if this control was
 185         a normal combobox.
 186     */
 187     wxCoord OnMeasureItem(size_t item);
 188
 189     /**
 190         The derived class may implement this method to return the width of the
 191         specified item (in pixels). If -1 is returned, then the item text width
 192         is used.
 193
 194         The default implementation returns -1.
 195     */
 196     wxCoord OnMeasureItemWidth(size_t item);
 197 };