interface/wx/choice.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        choice.h
   3 // Purpose:     interface of wxChoice
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxChoice
  11
  12     A choice item is used to select one of a list of strings. Unlike a
  13     wxListBox, only the selection is visible until the user pulls down the
  14     menu of choices.
  15
  16     @beginStyleTable
  17     @style{wxCB_SORT}
  18            Sorts the entries alphabetically.
  19     @endStyleTable
  20
  21     @beginEventEmissionTable{wxCommandEvent}
  22     @event{EVT_CHOICE(id, func)}
  23            Process a @c wxEVT_COMMAND_CHOICE_SELECTED event, when an item on the
  24            list is selected.
  25     @endEventTable
  26
  27     @library{wxcore}
  28     @category{ctrl}
  29     @appearance{choice}
  30
  31     @see wxListBox, wxComboBox, wxCommandEvent
  32 */
  33 class wxChoice : public wxControl,
  34                  public wxItemContainer
  35 {
  36 public:
  37     /**
  38         Default constructor.
  39
  40         @see Create(), wxValidator
  41     */
  42     wxChoice();
  43
  44     /**
  45         Constructor, creating and showing a choice.
  46
  47         @param parent
  48             Parent window. Must not be @NULL.
  49         @param id
  50             Window identifier. The value wxID_ANY indicates a default value.
  51         @param pos
  52             Window position.
  53             If ::wxDefaultPosition is specified then a default position is chosen.
  54         @param size
  55             Window size.
  56             If ::wxDefaultSize is specified then the choice is sized appropriately.
  57         @param n
  58             Number of strings with which to initialise the choice control.
  59         @param choices
  60             An array of strings with which to initialise the choice control.
  61         @param style
  62             Window style. See wxChoice.
  63         @param validator
  64             Window validator.
  65         @param name
  66             Window name.
  67
  68         @see Create(), wxValidator
  69
  70         @beginWxPerlOnly
  71         Not supported by wxPerl.
  72         @endWxPerlOnly
  73     */
  74     wxChoice( wxWindow *parent, wxWindowID id,
  75             const wxPoint& pos = wxDefaultPosition,
  76             const wxSize& size = wxDefaultSize,
  77             int n = 0, const wxString choices[] = NULL,
  78             long style = 0,
  79             const wxValidator& validator = wxDefaultValidator,
  80             const wxString& name = wxChoiceNameStr );
  81
  82     /**
  83         Constructor, creating and showing a choice.
  84
  85         @param parent
  86             Parent window. Must not be @NULL.
  87         @param id
  88             Window identifier. The value wxID_ANY indicates a default value.
  89         @param pos
  90             Window position.
  91         @param size
  92             Window size. If wxDefaultSize is specified then the choice is sized
  93             appropriately.
  94         @param choices
  95             An array of strings with which to initialise the choice control.
  96         @param style
  97             Window style. See wxChoice.
  98         @param validator
  99             Window validator.
 100         @param name
 101             Window name.
 102
 103         @see Create(), wxValidator
 104
 105         @beginWxPerlOnly
 106         Use an array reference for the @a choices parameter.
 107         @endWxPerlOnly
 108     */
 109     wxChoice( wxWindow *parent, wxWindowID id,
 110             const wxPoint& pos,
 111             const wxSize& size,
 112             const wxArrayString& choices,
 113             long style = 0,
 114             const wxValidator& validator = wxDefaultValidator,
 115             const wxString& name = wxChoiceNameStr );
 116
 117     /**
 118         Destructor, destroying the choice item.
 119     */
 120     virtual ~wxChoice();
 121
 122     //@{
 123     /**
 124         Creates the choice for two-step construction. See wxChoice().
 125     */
 126     bool Create( wxWindow *parent, wxWindowID id,
 127             const wxPoint& pos = wxDefaultPosition,
 128             const wxSize& size = wxDefaultSize,
 129             int n = 0, const wxString choices[] = NULL,
 130             long style = 0,
 131             const wxValidator& validator = wxDefaultValidator,
 132             const wxString& name = wxChoiceNameStr );
 133     bool Create( wxWindow *parent, wxWindowID id,
 134             const wxPoint& pos,
 135             const wxSize& size,
 136             const wxArrayString& choices,
 137             long style = 0,
 138             const wxValidator& validator = wxDefaultValidator,
 139             const wxString& name = wxChoiceNameStr );
 140     //@}
 141
 142     /**
 143         Gets the number of columns in this choice item.
 144
 145         @remarks This is implemented for GTK and Motif only and always
 146                  returns 1 for the other platforms.
 147     */
 148     virtual int GetColumns() const;
 149
 150     /**
 151         Unlike wxControlWithItems::GetSelection() which only returns the
 152         accepted selection value, i.e. the selection in the control once the
 153         user closes the dropdown list, this function returns the current
 154         selection. That is, while the dropdown list is shown, it returns the
 155         currently selected item in it. When it is not shown, its result is the
 156         same as for the other function.
 157
 158         @since 2.6.2.
 159                In older versions, wxControlWithItems::GetSelection() itself
 160                behaved like this.
 161     */
 162     virtual int GetCurrentSelection() const;
 163
 164     /**
 165         Sets the number of columns in this choice item.
 166
 167         @param n
 168             Number of columns.
 169
 170         @remarks This is implemented for GTK and Motif only and doesn’t do
 171                  anything under other platforms.
 172     */
 173     virtual void SetColumns(int n = 1);
 174
 175     virtual bool IsSorted() const;
 176
 177     virtual unsigned int GetCount() const ;
 178     virtual int GetSelection() const ;
 179     virtual void SetSelection(int n);
 180
 181     virtual int FindString(const wxString& s, bool bCase = false) const;
 182     virtual wxString GetString(unsigned int n) const ;
 183     virtual void SetString(unsigned int pos, const wxString& s);
 184 };
 185