interface/wx/bmpcbox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        bmpcbox.h
   3 // Purpose:     interface of wxBitmapComboBox
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxBitmapComboBox
  11
  12     A combobox that displays bitmap in front of the list items.
  13     It currently only allows using bitmaps of one size, and resizes itself
  14     so that a bitmap can be shown next to the text field.
  15
  16     @remarks
  17     While wxBitmapComboBox contains the wxComboBox API, but it might not actually
  18     be derived from that class. In fact, if the platform does not have a native
  19     implementation, wxBitmapComboBox will inherit from wxOwnerDrawnComboBox.
  20     You can determine if the implementation is generic by checking whether
  21     @c wxGENERIC_BITMAPCOMBOBOX is defined. Currently wxBitmapComboBox is
  22     implemented natively for MSW and GTK+.
  23
  24     @beginStyleTable
  25     @style{wxCB_READONLY}
  26            Creates a combobox without a text editor. On some platforms the
  27            control may appear very different when this style is used.
  28     @style{wxCB_SORT}
  29            Sorts the entries in the list alphabetically.
  30     @style{wxTE_PROCESS_ENTER}
  31            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
  32            (otherwise pressing Enter key is either processed internally by the
  33            control or used for navigation between dialog controls).
  34            Windows only.
  35     @endStyleTable
  36
  37     @todo create wxCB_PROCESS_ENTER rather than reusing wxTE_PROCESS_ENTER!
  38
  39     @beginEventEmissionTable{wxCommandEvent}
  40     @event{EVT_COMBOBOX(id, func)}
  41            Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
  42            the list is selected.
  43     @event{EVT_TEXT(id, func)}
  44            Process a @c wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text changes.
  45     @event{EVT_TEXT_ENTER(id, func)}
  46            Process a @c wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
  47            the combobox.
  48     @endEventTable
  49
  50     @library{wxadv}
  51     @category{ctrl}
  52     @appearance{bitmapcombobox}
  53
  54     @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxCommandEvent
  55 */
  56 class wxBitmapComboBox : public wxComboBox
  57 {
  58 public:
  59     /**
  60         Default ctor.
  61     */
  62     wxBitmapComboBox();
  63
  64     /**
  65         Constructor, creating and showing a combobox.
  66
  67         @param parent
  68             Parent window. Must not be @NULL.
  69         @param id
  70             Window identifier. The value wxID_ANY indicates a default value.
  71         @param value
  72             Initial selection string. An empty string indicates no selection.
  73         @param pos
  74             Initial position.
  75         @param size
  76             Initial size.
  77         @param n
  78             Number of strings with which to initialise the control.
  79         @param choices
  80             An array of strings with which to initialise the control.
  81         @param style
  82             The window style, see wxCB_* flags.
  83         @param validator
  84             Validator which can be used for additional data checks.
  85         @param name
  86             Control name.
  87
  88         @see Create(), wxValidator
  89     */
  90     wxBitmapComboBox(wxWindow* parent, wxWindowID id = wxID_ANY,
  91                      const wxString& value = wxEmptyString,
  92                      const wxPoint& pos = wxDefaultPosition,
  93                      const wxSize& size = wxDefaultSize,
  94                      int n = 0,
  95                      const wxString choices[] = NULL,
  96                      long style = 0,
  97                      const wxValidator& validator = wxDefaultValidator,
  98                      const wxString& name = wxBitmapComboBoxNameStr);
  99
 100     /**
 101         Constructor, creating and showing a combobox.
 102
 103         @param parent
 104             Parent window. Must not be @NULL.
 105         @param id
 106             Window identifier. The value wxID_ANY indicates a default value.
 107         @param value
 108             Initial selection string. An empty string indicates no selection.
 109         @param pos
 110             Initial position.
 111         @param size
 112             Initial size.
 113         @param choices
 114             An wxArrayString with which to initialise the control.
 115         @param style
 116             The window style, see wxCB_* flags.
 117         @param validator
 118             Validator which can be used for additional data checks.
 119         @param name
 120             Control name.
 121
 122         @see Create(), wxValidator
 123     */
 124     wxBitmapComboBox(wxWindow* parent, wxWindowID id,
 125                      const wxString& value,
 126                      const wxPoint& pos,
 127                      const wxSize& size,
 128                      const wxArrayString& choices,
 129                      long style,
 130                      const wxValidator& validator = wxDefaultValidator,
 131                      const wxString& name = wxBitmapComboBoxNameStr);
 132
 133     /**
 134         Destructor, destroying the combobox.
 135     */
 136     virtual ~wxBitmapComboBox();
 137
 138     /**
 139         Adds the item to the end of the combo box.
 140     */
 141     int Append(const wxString& item,
 142                const wxBitmap& bitmap = wxNullBitmap);
 143
 144     /**
 145         Adds the item to the end of the combo box, associating the given
 146         untyped, client data pointer @a clientData with the item.
 147     */
 148     int Append(const wxString& item, const wxBitmap& bitmap,
 149                void* clientData);
 150
 151     /**
 152         Adds the item to the end of the combo box, associating the given typed
 153         client data pointer @a clientData with the item.
 154     */
 155     int Append(const wxString& item, const wxBitmap& bitmap,
 156                wxClientData* clientData);
 157
 158     /**
 159         Creates the combobox for two-step construction.
 160     */
 161     bool Create(wxWindow* parent, wxWindowID id,
 162                 const wxString& value,
 163                 const wxPoint& pos,
 164                 const wxSize& size,
 165                 int n, const wxString choices[],
 166                 long style = 0,
 167                 const wxValidator& validator = wxDefaultValidator,
 168                 const wxString& name = wxBitmapComboBoxNameStr);
 169
 170     /**
 171         Creates the combobox for two-step construction.
 172     */
 173     bool Create(wxWindow* parent, wxWindowID id,
 174                 const wxString& value,
 175                 const wxPoint& pos,
 176                 const wxSize& size,
 177                 const wxArrayString& choices,
 178                 long style = 0,
 179                 const wxValidator& validator = wxDefaultValidator,
 180                 const wxString& name = wxBitmapComboBoxNameStr);
 181
 182     /**
 183         Returns the size of the bitmaps used in the combo box.
 184         If the combo box is empty, then ::wxDefaultSize is returned.
 185     */
 186     virtual wxSize GetBitmapSize() const;
 187
 188     /**
 189         Returns the bitmap of the item with the given index.
 190     */
 191     virtual wxBitmap GetItemBitmap(unsigned int n) const;
 192
 193     /**
 194         Inserts the item into the list before @a pos.
 195         Not valid for @c wxCB_SORT style, use Append() instead.
 196     */
 197     int Insert(const wxString& item, const wxBitmap& bitmap,
 198                unsigned int pos);
 199
 200     /**
 201         Inserts the item into the list before pos, associating the given
 202         untyped, client data pointer with the item.
 203         Not valid for @c wxCB_SORT style, use Append() instead.
 204     */
 205     int Insert(const wxString& item, const wxBitmap& bitmap,
 206                unsigned int pos,
 207                void* clientData);
 208
 209     /**
 210         Inserts the item into the list before pos, associating the given typed
 211         client data pointer with the item.
 212         Not valid for @c wxCB_SORT style, use Append() instead.
 213     */
 214     int Insert(const wxString& item, const wxBitmap& bitmap,
 215                unsigned int pos,
 216                wxClientData* clientData);
 217
 218     /**
 219         Sets the bitmap for the given item.
 220     */
 221     virtual void SetItemBitmap(unsigned int n, const wxBitmap& bitmap);
 222 };
 223