interface/bmpcbox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        bmpcbox.h
   3 // Purpose:     documentation for wxBitmapComboBox class
   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     @beginStyleTable
  18     @style{wxCB_READONLY}:
  19            Creates a combobox without a text editor. On some platforms the
  20            control may appear very different when this style is used.
  21     @style{wxCB_SORT}:
  22            Sorts the entries in the list alphabetically.
  23     @style{wxTE_PROCESS_ENTER}:
  24            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
  25            (otherwise pressing Enter key is either processed internally by the
  26            control or used for navigation between dialog controls). Windows
  27            only.
  28     @endStyleTable
  29
  30     @beginEventTable
  31     @event{EVT_COMBOBOX(id\, func)}:
  32            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
  33            the list is selected.
  34     @event{EVT_TEXT(id\, func)}:
  35            Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
  36            changes.
  37     @event{EVT_TEXT_ENTER(id\, func)}:
  38            Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
  39            the combobox.
  40     @endEventTable
  41
  42     @library{wxadv}
  43     @category{ctrl}
  44     @appearance{bitmapcombobox.png}
  45
  46     @seealso
  47     wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxCommandEvent
  48 */
  49 class wxBitmapComboBox : public wxComboBox
  50 {
  51 public:
  52     //@{
  53     /**
  54         Constructor, creating and showing a combobox.
  55
  56         @param parent
  57         Parent window. Must not be @NULL.
  58
  59         @param id
  60         Window identifier. The value wxID_ANY indicates a default value.
  61
  62         @param value
  63         Initial selection string. An empty string indicates no selection.
  64
  65         @param pos
  66         Window position.
  67
  68         @param size
  69         Window size. If wxDefaultSize is specified then the window is sized
  70         appropriately.
  71
  72         @param n
  73         Number of strings with which to initialise the control.
  74
  75         @param choices
  76         An array of strings with which to initialise the control.
  77
  78         @param style
  79         Window style. See wxBitmapComboBox.
  80
  81         @param validator
  82         Window validator.
  83
  84         @param name
  85         Window name.
  86
  87         @sa Create(), wxValidator
  88     */
  89     wxBitmapComboBox();
  90     wxBitmapComboBox(wxWindow* parent, wxWindowID id,
  91                      const wxString& value = "",
  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 = "comboBox");
  99     wxBitmapComboBox(wxWindow* parent, wxWindowID id,
 100                      const wxString& value,
 101                      const wxPoint& pos,
 102                      const wxSize& size,
 103                      const wxArrayString& choices,
 104                      long style = 0,
 105                      const wxValidator& validator = wxDefaultValidator,
 106                      const wxString& name = "comboBox");
 107     //@}
 108
 109     /**
 110         Destructor, destroying the combobox.
 111     */
 112     ~wxBitmapComboBox();
 113
 114     //@{
 115     /**
 116         Adds the item to the end of the combo box, associating the given, typed or
 117         untyped, client data pointer with the item.
 118     */
 119     int Append(const wxString& item,
 120                const wxBitmap& bitmap = wxNullBitmap);
 121     int Append(const wxString& item, const wxBitmap& bitmap,
 122                void * clientData);
 123     int Append(const wxString& item, const wxBitmap& bitmap,
 124                wxClientData * clientData);
 125     //@}
 126
 127     //@{
 128     /**
 129         Creates the combobox for two-step construction. Derived classes
 130         should call or replace this function. See wxBitmapComboBox()
 131         for further details.
 132     */
 133     bool Create(wxWindow* parent, wxWindowID id,
 134                 const wxString& value = "",
 135                 const wxPoint& pos = wxDefaultPosition,
 136                 const wxSize& size = wxDefaultSize,
 137                 int n, const wxString choices[],
 138                 long style = 0,
 139                 const wxValidator& validator = wxDefaultValidator,
 140                 const wxString& name = "comboBox");
 141     bool Create(wxWindow* parent, wxWindowID id,
 142                 const wxString& value,
 143                 const wxPoint& pos,
 144                 const wxSize& size,
 145                 const wxArrayString& choices,
 146                 long style = 0,
 147                 const wxValidator& validator = wxDefaultValidator,
 148                 const wxString& name = "comboBox");
 149     //@}
 150
 151     /**
 152         Returns size of bitmaps used in the list.
 153     */
 154     wxSize GetBitmapSize();
 155
 156     /**
 157         Returns the bitmap of the item with the given index.
 158     */
 159     wxBitmap GetItemBitmap(unsigned int n);
 160
 161     //@{
 162     /**
 163         Inserts the item into the list before pos, associating the given, typed or
 164         untyped, client data pointer with the item.
 165         Not valid for @c wxCB_SORT style, use Append instead.
 166     */
 167     int Insert(const wxString& item, const wxBitmap& bitmap,
 168                unsigned int pos);
 169     int Insert(const wxString& item, const wxBitmap& bitmap,
 170                unsigned int pos,
 171                void * clientData);
 172     int Insert(const wxString& item, const wxBitmap& bitmap,
 173                unsigned int pos,
 174                wxClientData * clientData);
 175     //@}
 176
 177     /**
 178         Sets the bitmap for the given item.
 179     */
 180     void SetItemBitmap(unsigned int n, const wxBitmap& bitmap);
 181 };