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     @beginEventTable{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,
  78              const wxSize& size, int n,
  79              const wxString choices[],
  80              long style = 0,
  81              const wxValidator& validator = wxDefaultValidator,
  82              const wxString& name = "choice");
  83     wxChoice(wxWindow* parent, wxWindowID id,
  84              const wxPoint& pos,
  85              const wxSize& size,
  86              const wxArrayString& choices,
  87              long style = 0,
  88              const wxValidator& validator = wxDefaultValidator,
  89              const wxString& name = "choice");
  90     //@}
  91
  92     /**
  93         Destructor, destroying the choice item.
  94     */
  95     ~wxChoice();
  96
  97     //@{
  98     /**
  99         Creates the choice for two-step construction. See wxChoice().
 100     */
 101     bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos,
 102                 const wxSize& size, int n,
 103                 const wxString choices[],
 104                 long style = 0,
 105                 const wxValidator& validator = wxDefaultValidator,
 106                 const wxString& name = "choice");
 107     bool Create(wxWindow* parent, wxWindowID id,
 108                 const wxPoint& pos,
 109                 const wxSize& size,
 110                 const wxArrayString& choices,
 111                 long style = 0,
 112                 const wxValidator& validator = wxDefaultValidator,
 113                 const wxString& name = "choice");
 114     //@}
 115
 116     /**
 117         Gets the number of columns in this choice item.
 118
 119         @remarks This is implemented for GTK and Motif only and always
 120                  returns 1 for the other platforms.
 121     */
 122     int GetColumns() const;
 123
 124     /**
 125         Unlike wxControlWithItems::GetSelection() which only returns the
 126         accepted selection value, i.e. the selection in the control once the
 127         user closes the dropdown list, this function returns the current
 128         selection. That is, while the dropdown list is shown, it returns the
 129         currently selected item in it. When it is not shown, its result is the
 130         same as for the other function.
 131
 132         @since 2.6.2.
 133                In older versions, wxControlWithItems::GetSelection() itself
 134                behaved like this.
 135     */
 136     int GetCurrentSelection() const;
 137
 138     /**
 139         Sets the number of columns in this choice item.
 140
 141         @param n
 142             Number of columns.
 143
 144         @remarks This is implemented for GTK and Motif only and doesn’t do
 145                  anything under other platforms.
 146     */
 147     void SetColumns(int n = 1);
 148 };
 149