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     /**
  51         Default constructor.
  52     */
  53     wxOwnerDrawnComboBox();
  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
  68         sized
  69             appropriately.
  70         @param n
  71             Number of strings with which to initialise the control.
  72         @param choices
  73             An array of strings with which to initialise the control.
  74         @param style
  75             Window style. See wxOwnerDrawnComboBox.
  76         @param validator
  77             Window validator.
  78         @param name
  79             Window name.
  80
  81         @see Create(), wxValidator
  82     */
  83     wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id,
  84                          const wxString& value = "",
  85                          const wxPoint& pos = wxDefaultPosition,
  86                          const wxSize& size = wxDefaultSize,
  87                          int n = 0,
  88                          const wxString[] choices = NULL,
  89                          long style = 0,
  90                          const wxValidator& validator = wxDefaultValidator,
  91                          const wxString& name = "comboBox");
  92     wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id,
  93                          const wxString& value,
  94                          const wxPoint& pos,
  95                          const wxSize& size,
  96                          const wxArrayString& choices,
  97                          long style = 0,
  98                          const wxValidator& validator = wxDefaultValidator,
  99                          const wxString& name = "comboBox");
 100     //@}
 101
 102     /**
 103         Destructor, destroying the owner-drawn combobox.
 104     */
 105     ~wxOwnerDrawnComboBox();
 106
 107     //@{
 108     /**
 109         Creates the combobox for two-step construction.
 110         See wxOwnerDrawnComboBox() for further details.
 111
 112         @remarks Derived classes should call or replace this function.
 113     */
 114     bool Create(wxWindow* parent, wxWindowID id,
 115                 const wxString& value = "",
 116                 const wxPoint& pos = wxDefaultPosition,
 117                 const wxSize& size = wxDefaultSize,
 118                 int n, const wxString choices[],
 119                 long style = 0,
 120                 const wxValidator& validator = wxDefaultValidator,
 121                 const wxString& name = "comboBox");
 122     bool Create(wxWindow* parent, wxWindowID id,
 123                 const wxString& value,
 124                 const wxPoint& pos,
 125                 const wxSize& size,
 126                 const wxArrayString& choices,
 127                 long style = 0,
 128                 const wxValidator& validator = wxDefaultValidator,
 129                 const wxString& name = "comboBox");
 130     //@}
 131
 132     /**
 133         Returns index to the widest item in the list.
 134     */
 135     int GetWidestItem() const;
 136
 137     /**
 138         Returns width of the widest item in the list.
 139     */
 140     int GetWidestItemWidth() const;
 141
 142     /**
 143         This method is used to draw the items background and, maybe, a border around it.
 144
 145         The base class version implements a reasonable default behaviour which consists
 146         in drawing the selected item with the standard background colour and drawing a
 147         border around the item if it is either selected or current.
 148
 149         @remarks flags has the same meaning as with OnDrawItem().
 150     */
 151     void OnDrawBackground(wxDC& dc, const wxRect& rect, int item,
 152                           int flags) const;
 153
 154     /**
 155         The derived class may implement this function to actually draw the item
 156         with the given index on the provided DC.
 157
 158         If function is not implemented, the item text is simply drawn, as if the control
 159         was a normal combobox.
 160
 161         @param dc
 162             The device context to use for drawing
 163         @param rect
 164             The bounding rectangle for the item being drawn (DC clipping
 165             region is set to this rectangle before calling this function)
 166         @param item
 167             The index of the item to be drawn
 168         @param flags
 169             Combines any of the following flag values:
 170
 171             @beginStyleTable
 172             @style{wxODCB_PAINTING_CONTROL}:
 173                    Combo control is being painted, instead of a list item.
 174                    Argument item may be @c wxNOT_FOUND in this case.
 175             @style{wxODCB_PAINTING_SELECTED}:
 176                    An item with selection background is being painted.
 177                    DC text colour should already be correct.
 178             @endStyleTable
 179     */
 180     void OnDrawItem(wxDC& dc, const wxRect& rect, int item,
 181                     int flags) const;
 182
 183     /**
 184         The derived class may implement this method to return the height of the
 185         specified item (in pixels).
 186
 187         The default implementation returns text height, as if this control was
 188         a normal combobox.
 189     */
 190     wxCoord OnMeasureItem(size_t item) const;
 191
 192     /**
 193         The derived class may implement this method to return the width of the
 194         specified item (in pixels). If -1 is returned, then the item text width
 195         is used.
 196
 197         The default implementation returns -1.
 198     */
 199     wxCoord OnMeasureItemWidth(size_t item) const;
 200 };
 201