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