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