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 license
   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     @beginEventTable{wxCommandEvent}
  40     @event{EVT_COMBOBOX(id, func)}
  41            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
  42            the list is selected.
  43     @event{EVT_TEXT(id, func)}
  44            Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text changes.
  45     @event{EVT_TEXT_ENTER(id, func)}
  46            Process a 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.png} -->
  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 n
  74             Number of strings with which to initialise the control.
  75         @param choices
  76             An array of strings with which to initialise the control.
  77
  78         @see Create(), wxValidator
  79     */
  80     wxBitmapComboBox(wxWindow* parent, wxWindowID id = wxID_ANY,
  81                      const wxString& value = wxEmptyString,
  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 = wxBitmapComboBoxNameStr);
  89
  90     /**
  91         Constructor, creating and showing a combobox.
  92
  93         @param parent
  94             Parent window. Must not be @NULL.
  95         @param id
  96             Window identifier. The value wxID_ANY indicates a default value.
  97         @param value
  98             Initial selection string. An empty string indicates no selection.
  99         @param choices
 100             An wxArrayString with which to initialise the control.
 101
 102         @see Create(), wxValidator
 103     */
 104     wxBitmapComboBox(wxWindow* parent, wxWindowID id,
 105                      const wxString& value,
 106                      const wxPoint& pos,
 107                      const wxSize& size,
 108                      const wxArrayString& choices,
 109                      long style,
 110                      const wxValidator& validator = wxDefaultValidator,
 111                      const wxString& name = wxBitmapComboBoxNameStr);
 112
 113     /**
 114         Destructor, destroying the combobox.
 115     */
 116     virtual ~wxBitmapComboBox();
 117
 118     /**
 119         Adds the item to the end of the combo box.
 120     */
 121     int Append(const wxString& item,
 122                const wxBitmap& bitmap = wxNullBitmap);
 123
 124     /**
 125         Adds the item to the end of the combo box, associating the given
 126         untyped, client data pointer @a clientData with the item.
 127     */
 128     int Append(const wxString& item, const wxBitmap& bitmap,
 129                void* clientData);
 130
 131     /**
 132         Adds the item to the end of the combo box, associating the given typed
 133         client data pointer @a clientData with the item.
 134     */
 135     int Append(const wxString& item, const wxBitmap& bitmap,
 136                wxClientData* clientData);
 137
 138     /**
 139         Creates the combobox for two-step construction.
 140     */
 141     bool Create(wxWindow* parent, wxWindowID id,
 142                 const wxString& value,
 143                 const wxPoint& pos,
 144                 const wxSize& size,
 145                 int n, const wxString choices[],
 146                 long style = 0,
 147                 const wxValidator& validator = wxDefaultValidator,
 148                 const wxString& name = wxBitmapComboBoxNameStr);
 149
 150     /**
 151         Creates the combobox for two-step construction.
 152     */
 153     bool Create(wxWindow* parent, wxWindowID id,
 154                 const wxString& value,
 155                 const wxPoint& pos,
 156                 const wxSize& size,
 157                 const wxArrayString& choices,
 158                 long style = 0,
 159                 const wxValidator& validator = wxDefaultValidator,
 160                 const wxString& name = wxBitmapComboBoxNameStr);
 161
 162     /**
 163         Returns size of bitmaps used in the list.
 164     */
 165     virtual wxSize GetBitmapSize() const;
 166
 167     /**
 168         Returns the bitmap of the item with the given index.
 169     */
 170     virtual wxBitmap GetItemBitmap(unsigned int n) const;
 171
 172     /**
 173         Inserts the item into the list before @a pos.
 174         Not valid for @c wxCB_SORT style, use Append() instead.
 175     */
 176     int Insert(const wxString& item, const wxBitmap& bitmap,
 177                unsigned int pos);
 178
 179     /**
 180         Inserts the item into the list before pos, associating the given
 181         untyped, client data pointer with the item.
 182         Not valid for @c wxCB_SORT style, use Append() instead.
 183     */
 184     int Insert(const wxString& item, const wxBitmap& bitmap,
 185                unsigned int pos,
 186                void* clientData);
 187
 188     /**
 189         Inserts the item into the list before pos, associating the given typed
 190         client data pointer with the item.
 191         Not valid for @c wxCB_SORT style, use Append() instead.
 192     */
 193     int Insert(const wxString& item, const wxBitmap& bitmap,
 194                unsigned int pos,
 195                wxClientData* clientData);
 196
 197     /**
 198         Sets the bitmap for the given item.
 199     */
 200     virtual void SetItemBitmap(unsigned int n, const wxBitmap& bitmap);
 201 };
 202