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 wxControlWithItems
  34 {
  35 public:
  36     /**
  37         Default constructor.
  38
  39         @see Create(), wxValidator
  40     */
  41     wxChoice();
  42
  43     /**
  44         Constructor, creating and showing a choice.
  45
  46         @param parent
  47             Parent window. Must not be @NULL.
  48         @param id
  49             Window identifier. The value wxID_ANY indicates a default value.
  50         @param pos
  51             Window position.
  52             If ::wxDefaultPosition is specified then a default position is chosen.
  53         @param size
  54             Window size.
  55             If ::wxDefaultSize is specified then the choice is sized appropriately.
  56         @param n
  57             Number of strings with which to initialise the choice control.
  58         @param choices
  59             An array of strings with which to initialise the choice control.
  60         @param style
  61             Window style. See wxChoice.
  62         @param validator
  63             Window validator.
  64         @param name
  65             Window name.
  66
  67         @see Create(), wxValidator
  68
  69         @beginWxPerlOnly
  70         Not supported by wxPerl.
  71         @endWxPerlOnly
  72     */
  73     wxChoice( wxWindow *parent, wxWindowID id,
  74             const wxPoint& pos = wxDefaultPosition,
  75             const wxSize& size = wxDefaultSize,
  76             int n = 0, const wxString choices[] = NULL,
  77             long style = 0,
  78             const wxValidator& validator = wxDefaultValidator,
  79             const wxString& name = wxChoiceNameStr );
  80
  81     /**
  82         Constructor, creating and showing a choice.
  83
  84         @param parent
  85             Parent window. Must not be @NULL.
  86         @param id
  87             Window identifier. The value wxID_ANY indicates a default value.
  88         @param pos
  89             Window position.
  90         @param size
  91             Window size. If wxDefaultSize is specified then the choice is sized
  92             appropriately.
  93         @param choices
  94             An array of strings with which to initialise the choice control.
  95         @param style
  96             Window style. See wxChoice.
  97         @param validator
  98             Window validator.
  99         @param name
 100             Window name.
 101
 102         @see Create(), wxValidator
 103
 104         @beginWxPerlOnly
 105         Use an array reference for the @a choices parameter.
 106         @endWxPerlOnly
 107     */
 108     wxChoice( wxWindow *parent, wxWindowID id,
 109             const wxPoint& pos,
 110             const wxSize& size,
 111             const wxArrayString& choices,
 112             long style = 0,
 113             const wxValidator& validator = wxDefaultValidator,
 114             const wxString& name = wxChoiceNameStr );
 115
 116     /**
 117         Destructor, destroying the choice item.
 118     */
 119     virtual ~wxChoice();
 120
 121     //@{
 122     /**
 123         Creates the choice for two-step construction. See wxChoice().
 124     */
 125     bool Create( wxWindow *parent, wxWindowID id,
 126             const wxPoint& pos = wxDefaultPosition,
 127             const wxSize& size = wxDefaultSize,
 128             int n = 0, const wxString choices[] = NULL,
 129             long style = 0,
 130             const wxValidator& validator = wxDefaultValidator,
 131             const wxString& name = wxChoiceNameStr );
 132     bool Create( wxWindow *parent, wxWindowID id,
 133             const wxPoint& pos,
 134             const wxSize& size,
 135             const wxArrayString& choices,
 136             long style = 0,
 137             const wxValidator& validator = wxDefaultValidator,
 138             const wxString& name = wxChoiceNameStr );
 139     //@}
 140
 141     /**
 142         Gets the number of columns in this choice item.
 143
 144         @remarks This is implemented for GTK and Motif only and always
 145                  returns 1 for the other platforms.
 146     */
 147     virtual int GetColumns() const;
 148
 149     /**
 150         Unlike wxControlWithItems::GetSelection() which only returns the
 151         accepted selection value, i.e. the selection in the control once the
 152         user closes the dropdown list, this function returns the current
 153         selection. That is, while the dropdown list is shown, it returns the
 154         currently selected item in it. When it is not shown, its result is the
 155         same as for the other function.
 156
 157         @since 2.6.2.
 158                In older versions, wxControlWithItems::GetSelection() itself
 159                behaved like this.
 160     */
 161     virtual int GetCurrentSelection() const;
 162
 163     /**
 164         Sets the number of columns in this choice item.
 165
 166         @param n
 167             Number of columns.
 168
 169         @remarks This is implemented for GTK and Motif only and doesn’t do
 170                  anything under other platforms.
 171     */
 172     virtual void SetColumns(int n = 1);
 173
 174     virtual bool IsSorted() const;
 175
 176     virtual unsigned int GetCount() const ;
 177     virtual int GetSelection() const ;
 178     virtual void SetSelection(int n);
 179
 180     virtual int FindString(const wxString& s, bool bCase = false) const;
 181     virtual wxString GetString(unsigned int n) const ;
 182     virtual void SetString(unsigned int pos, const wxString& s);
 183 };
 184