interface/wx/odcombo.h

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