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