interface/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     @wxheader{choice.h}
  12
  13     A choice item is used to select one of a list of strings. Unlike a
  14     wxListBox, only the selection is visible until the user pulls down the
  15     menu of choices.
  16
  17     @beginStyleTable
  18     @style{wxCB_SORT}
  19            Sorts the entries alphabetically.
  20     @endStyleTable
  21
  22     @beginEventTable{wxCommandEvent}
  23     @event{EVT_CHOICE(id, func)}
  24            Process a wxEVT_COMMAND_CHOICE_SELECTED event, when an item on the
  25            list is selected.
  26     @endEventTable
  27
  28     @library{wxcore}
  29     @category{ctrl}
  30     <!-- @appearance{choice.png} -->
  31
  32     @see wxListBox, wxComboBox, wxCommandEvent
  33 */
  34 class wxChoice : public wxControlWithItems
  35 {
  36 public:
  37     /**
  38         Default constructor.
  39
  40         @see Create(), wxValidator
  41     */
  42     wxChoice();
  43
  44     //@{
  45     /**
  46         Constructor, creating and showing a choice.
  47
  48         @param parent
  49             Parent window. Must not be @NULL.
  50         @param id
  51             Window identifier. The value wxID_ANY indicates a default value.
  52         @param pos
  53             Window position.
  54         @param size
  55             Window size. If wxDefaultSize is specified then the choice is sized
  56             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,
  79              const wxSize& size, int n,
  80              const wxString choices[],
  81              long style = 0,
  82              const wxValidator& validator = wxDefaultValidator,
  83              const wxString& name = "choice");
  84     wxChoice(wxWindow* parent, wxWindowID id,
  85              const wxPoint& pos,
  86              const wxSize& size,
  87              const wxArrayString& choices,
  88              long style = 0,
  89              const wxValidator& validator = wxDefaultValidator,
  90              const wxString& name = "choice");
  91     //@}
  92
  93     /**
  94         Destructor, destroying the choice item.
  95     */
  96     ~wxChoice();
  97
  98     //@{
  99     /**
 100         Creates the choice for two-step construction. See wxChoice().
 101     */
 102     bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos,
 103                 const wxSize& size, int n,
 104                 const wxString choices[],
 105                 long style = 0,
 106                 const wxValidator& validator = wxDefaultValidator,
 107                 const wxString& name = "choice");
 108     bool Create(wxWindow* parent, wxWindowID id,
 109                 const wxPoint& pos,
 110                 const wxSize& size,
 111                 const wxArrayString& choices,
 112                 long style = 0,
 113                 const wxValidator& validator = wxDefaultValidator,
 114                 const wxString& name = "choice");
 115     //@}
 116
 117     /**
 118         Gets the number of columns in this choice item.
 119
 120         @remarks This is implemented for GTK and Motif only and always
 121                  returns 1 for the other platforms.
 122     */
 123     int GetColumns() const;
 124
 125     /**
 126         Unlike wxControlWithItems::GetSelection() which only returns the
 127         accepted selection value, i.e. the selection in the control once the
 128         user closes the dropdown list, this function returns the current
 129         selection. That is, while the dropdown list is shown, it returns the
 130         currently selected item in it. When it is not shown, its result is the
 131         same as for the other function.
 132
 133         @since 2.6.2.
 134                In older versions, wxControlWithItems::GetSelection() itself
 135                behaved like this.
 136     */
 137     int GetCurrentSelection() const;
 138
 139     /**
 140         Sets the number of columns in this choice item.
 141
 142         @param n
 143             Number of columns.
 144
 145         @remarks This is implemented for GTK and Motif only and doesn’t do
 146                  anything under other platforms.
 147     */
 148     void SetColumns(int n = 1);
 149 };
 150