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