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