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