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