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