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     wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id,
 109                          const wxString& value,
 110                          const wxPoint& pos,
 111                          const wxSize& size,
 112                          const wxArrayString& choices,
 113                          long style = 0,
 114                          const wxValidator& validator = wxDefaultValidator,
 115                          const wxString& name = "comboBox");
 116     //@}
 117
 118     /**
 119         Destructor, destroying the owner-drawn combobox.
 120     */
 121     ~wxOwnerDrawnComboBox();
 122
 123     //@{
 124     /**
 125         Creates the combobox for two-step construction.
 126         See wxOwnerDrawnComboBox() for further details.
 127
 128         @remarks Derived classes should call or replace this function.
 129     */
 130     bool Create(wxWindow* parent, wxWindowID id,
 131                 const wxString& value = "",
 132                 const wxPoint& pos = wxDefaultPosition,
 133                 const wxSize& size = wxDefaultSize,
 134                 int n, const wxString choices[],
 135                 long style = 0,
 136                 const wxValidator& validator = wxDefaultValidator,
 137                 const wxString& name = "comboBox");
 138     bool Create(wxWindow* parent, wxWindowID id,
 139                 const wxString& value,
 140                 const wxPoint& pos,
 141                 const wxSize& size,
 142                 const wxArrayString& choices,
 143                 long style = 0,
 144                 const wxValidator& validator = wxDefaultValidator,
 145                 const wxString& name = "comboBox");
 146     //@}
 147
 148     /**
 149         Returns index to the widest item in the list.
 150     */
 151     int GetWidestItem() const;
 152
 153     /**
 154         Returns width of the widest item in the list.
 155     */
 156     int GetWidestItemWidth() const;
 157
 158     /**
 159         This method is used to draw the items background and, maybe, a border around it.
 160
 161         The base class version implements a reasonable default behaviour which consists
 162         in drawing the selected item with the standard background colour and drawing a
 163         border around the item if it is either selected or current.
 164
 165         @remarks flags has the same meaning as with OnDrawItem().
 166     */
 167     void OnDrawBackground(wxDC& dc, const wxRect& rect, int item,
 168                           int flags) const;
 169
 170     /**
 171         The derived class may implement this function to actually draw the item
 172         with the given index on the provided DC.
 173
 174         If function is not implemented, the item text is simply drawn, as if the control
 175         was a normal combobox.
 176
 177         @param dc
 178             The device context to use for drawing
 179         @param rect
 180             The bounding rectangle for the item being drawn (DC clipping
 181             region is set to this rectangle before calling this function)
 182         @param item
 183             The index of the item to be drawn
 184         @param flags
 185             A combination of the ::wxOwnerDrawnComboBoxPaintingFlags enumeration values.
 186     */
 187     void OnDrawItem(wxDC& dc, const wxRect& rect, int item,
 188                     int flags) const;
 189
 190     /**
 191         The derived class may implement this method to return the height of the
 192         specified item (in pixels).
 193
 194         The default implementation returns text height, as if this control was
 195         a normal combobox.
 196     */
 197     wxCoord OnMeasureItem(size_t item) const;
 198
 199     /**
 200         The derived class may implement this method to return the width of the
 201         specified item (in pixels). If -1 is returned, then the item text width
 202         is used.
 203
 204         The default implementation returns -1.
 205     */
 206     wxCoord OnMeasureItemWidth(size_t item) const;
 207 };
 208