interface/odcombo.h

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