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     /**
 184         This method is used to draw the items background and, maybe, a border around it.
 185
 186         The base class version implements a reasonable default behaviour which consists
 187         in drawing the selected item with the standard background colour and drawing a
 188         border around the item if it is either selected or current.
 189
 190         @remarks flags has the same meaning as with OnDrawItem().
 191     */
 192     void OnDrawBackground(wxDC& dc, const wxRect& rect, int item,
 193                           int flags) const;
 194
 195     /**
 196         The derived class may implement this function to actually draw the item
 197         with the given index on the provided DC.
 198
 199         If function is not implemented, the item text is simply drawn, as if the control
 200         was a normal combobox.
 201
 202         @param dc
 203             The device context to use for drawing
 204         @param rect
 205             The bounding rectangle for the item being drawn (DC clipping
 206             region is set to this rectangle before calling this function)
 207         @param item
 208             The index of the item to be drawn
 209         @param flags
 210             A combination of the ::wxOwnerDrawnComboBoxPaintingFlags enumeration values.
 211     */
 212     void OnDrawItem(wxDC& dc, const wxRect& rect, int item,
 213                     int flags) const;
 214
 215     /**
 216         The derived class may implement this method to return the height of the
 217         specified item (in pixels).
 218
 219         The default implementation returns text height, as if this control was
 220         a normal combobox.
 221     */
 222     wxCoord OnMeasureItem(size_t item) const;
 223
 224     /**
 225         The derived class may implement this method to return the width of the
 226         specified item (in pixels). If -1 is returned, then the item text width
 227         is used.
 228
 229         The default implementation returns -1.
 230     */
 231     wxCoord OnMeasureItemWidth(size_t item) const;
 232 };
 233