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     @beginEventEmissionTable{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         Constructor, creating and showing a owner-drawn combobox.
  73
  74         @param parent
  75             Parent window. Must not be @NULL.
  76         @param id
  77             Window identifier. The value @c wxID_ANY indicates a default value.
  78         @param value
  79             Initial selection string. An empty string indicates no selection.
  80         @param pos
  81             Window position.
  82         @param size
  83             Window size.
  84             If ::wxDefaultSize is specified then the window is sized appropriately.
  85         @param n
  86             Number of strings with which to initialise the control.
  87         @param choices
  88             An array of strings with which to initialise the control.
  89         @param style
  90             Window style. See wxOwnerDrawnComboBox.
  91         @param validator
  92             Window validator.
  93         @param name
  94             Window name.
  95
  96         @see Create(), wxValidator
  97     */
  98     wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id,
  99                          const wxString& value = wxEmptyString,
 100                          const wxPoint& pos = wxDefaultPosition,
 101                          const wxSize& size = wxDefaultSize,
 102                          int n = 0,
 103                          const wxString[] choices = NULL,
 104                          long style = 0,
 105                          const wxValidator& validator = wxDefaultValidator,
 106                          const wxString& name = "comboBox");
 107     /**
 108         Constructor, creating and showing a owner-drawn combobox.
 109
 110         @param parent
 111             Parent window. Must not be @NULL.
 112         @param id
 113             Window identifier. The value @c wxID_ANY indicates a default value.
 114         @param value
 115             Initial selection string. An empty string indicates no selection.
 116         @param pos
 117             Window position.
 118         @param size
 119             Window size.
 120             If ::wxDefaultSize is specified then the window is sized appropriately.
 121         @param choices
 122             An array of strings with which to initialise the control.
 123         @param style
 124             Window style. See wxOwnerDrawnComboBox.
 125         @param validator
 126             Window validator.
 127         @param name
 128             Window name.
 129
 130         @see Create(), wxValidator
 131     */
 132     wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id,
 133                          const wxString& value,
 134                          const wxPoint& pos,
 135                          const wxSize& size,
 136                          const wxArrayString& choices,
 137                          long style = 0,
 138                          const wxValidator& validator = wxDefaultValidator,
 139                          const wxString& name = "comboBox");
 140
 141     /**
 142         Destructor, destroying the owner-drawn combobox.
 143     */
 144     virtual ~wxOwnerDrawnComboBox();
 145
 146     //@{
 147     /**
 148         Creates the combobox for two-step construction.
 149         See wxOwnerDrawnComboBox() for further details.
 150
 151         @remarks Derived classes should call or replace this function.
 152     */
 153     bool Create(wxWindow *parent,
 154                 wxWindowID id,
 155                 const wxString& value = wxEmptyString,
 156                 const wxPoint& pos = wxDefaultPosition,
 157                 const wxSize& size = wxDefaultSize,
 158                 long style = 0,
 159                 const wxValidator& validator = wxDefaultValidator,
 160                 const wxString& name = wxComboBoxNameStr);
 161     bool Create(wxWindow *parent,
 162                 wxWindowID id,
 163                 const wxString& value,
 164                 const wxPoint& pos,
 165                 const wxSize& size,
 166                 int n,
 167                 const wxString choices[],
 168                 long style = 0,
 169                 const wxValidator& validator = wxDefaultValidator,
 170                 const wxString& name = wxComboBoxNameStr);
 171     bool Create(wxWindow *parent,
 172                 wxWindowID id,
 173                 const wxString& value,
 174                 const wxPoint& pos,
 175                 const wxSize& size,
 176                 const wxArrayString& choices,
 177                 long style = 0,
 178                 const wxValidator& validator = wxDefaultValidator,
 179                 const wxString& name = wxComboBoxNameStr);
 180     //@}
 181
 182     /**
 183         Returns index to the widest item in the list.
 184     */
 185     virtual int GetWidestItem();
 186
 187     /**
 188         Returns width of the widest item in the list.
 189     */
 190     virtual int GetWidestItemWidth();
 191
 192 protected:
 193
 194     /**
 195         This method is used to draw the items background and, maybe, a border around it.
 196
 197         The base class version implements a reasonable default behaviour which consists
 198         in drawing the selected item with the standard background colour and drawing a
 199         border around the item if it is either selected or current.
 200
 201         @remarks flags has the same meaning as with OnDrawItem().
 202     */
 203     virtual void OnDrawBackground(wxDC& dc, const wxRect& rect, int item,
 204                                   int flags) const;
 205
 206     /**
 207         The derived class may implement this function to actually draw the item
 208         with the given index on the provided DC.
 209
 210         If function is not implemented, the item text is simply drawn, as if the control
 211         was a normal combobox.
 212
 213         @param dc
 214             The device context to use for drawing
 215         @param rect
 216             The bounding rectangle for the item being drawn (DC clipping
 217             region is set to this rectangle before calling this function)
 218         @param item
 219             The index of the item to be drawn
 220         @param flags
 221             A combination of the ::wxOwnerDrawnComboBoxPaintingFlags enumeration values.
 222     */
 223     virtual void OnDrawItem(wxDC& dc, const wxRect& rect, int item,
 224                             int flags) const;
 225
 226     /**
 227         The derived class may implement this method to return the height of the
 228         specified item (in pixels).
 229
 230         The default implementation returns text height, as if this control was
 231         a normal combobox.
 232     */
 233     virtual wxCoord OnMeasureItem(size_t item) const;
 234
 235     /**
 236         The derived class may implement this method to return the width of the
 237         specified item (in pixels). If -1 is returned, then the item text width
 238         is used.
 239
 240         The default implementation returns -1.
 241     */
 242     virtual wxCoord OnMeasureItemWidth(size_t item) const;
 243 };
 244