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