interface/wx/odcombo.h

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