interface/wx/bmpcbox.h

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