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 = "",
 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, wxWindowID id,
 156                 const wxString& value = "",
 157                 const wxPoint& pos = wxDefaultPosition,
 158                 const wxSize& size = wxDefaultSize,
 159                 int n, const wxString choices[],
 160                 long style = 0,
 161                 const wxValidator& validator = wxDefaultValidator,
 162                 const wxString& name = "comboBox");
 163     bool Create(wxWindow* parent, wxWindowID id,
 164                 const wxString& value,
 165                 const wxPoint& pos,
 166                 const wxSize& size,
 167                 const wxArrayString& choices,
 168                 long style = 0,
 169                 const wxValidator& validator = wxDefaultValidator,
 170                 const wxString& name = "comboBox");
 171     //@}
 172
 173     /**
 174         Returns index to the widest item in the list.
 175     */
 176     virtual int GetWidestItem();
 177
 178     /**
 179         Returns width of the widest item in the list.
 180     */
 181     virtual int GetWidestItemWidth();
 182
 183 protected:
 184
 185     /**
 186         This method is used to draw the items background and, maybe, a border around it.
 187
 188         The base class version implements a reasonable default behaviour which consists
 189         in drawing the selected item with the standard background colour and drawing a
 190         border around the item if it is either selected or current.
 191
 192         @remarks flags has the same meaning as with OnDrawItem().
 193     */
 194     virtual void OnDrawBackground(wxDC& dc, const wxRect& rect, int item,
 195                                   int flags) const;
 196
 197     /**
 198         The derived class may implement this function to actually draw the item
 199         with the given index on the provided DC.
 200
 201         If function is not implemented, the item text is simply drawn, as if the control
 202         was a normal combobox.
 203
 204         @param dc
 205             The device context to use for drawing
 206         @param rect
 207             The bounding rectangle for the item being drawn (DC clipping
 208             region is set to this rectangle before calling this function)
 209         @param item
 210             The index of the item to be drawn
 211         @param flags
 212             A combination of the ::wxOwnerDrawnComboBoxPaintingFlags enumeration values.
 213     */
 214     virtual void OnDrawItem(wxDC& dc, const wxRect& rect, int item,
 215                             int flags) const;
 216
 217     /**
 218         The derived class may implement this method to return the height of the
 219         specified item (in pixels).
 220
 221         The default implementation returns text height, as if this control was
 222         a normal combobox.
 223     */
 224     virtual wxCoord OnMeasureItem(size_t item) const;
 225
 226     /**
 227         The derived class may implement this method to return the width of the
 228         specified item (in pixels). If -1 is returned, then the item text width
 229         is used.
 230
 231         The default implementation returns -1.
 232     */
 233     virtual wxCoord OnMeasureItemWidth(size_t item) const;
 234 };
 235