interface/choice.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        choice.h
   3 // Purpose:     documentation for wxChoice class
   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     listbox, 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
  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     @seealso
  33     wxListBox, wxComboBox, wxCommandEvent
  34 */
  35 class wxChoice : public wxControlWithItems
  36 {
  37 public:
  38     //@{
  39     /**
  40         Constructor, creating and showing a choice.
  41
  42         @param parent
  43             Parent window. Must not be @NULL.
  44         @param id
  45             Window identifier. The value wxID_ANY indicates a default value.
  46         @param pos
  47             Window position.
  48         @param size
  49             Window size. If wxDefaultSize is specified then the choice is
  50         sized
  51             appropriately.
  52         @param n
  53             Number of strings with which to initialise the choice control.
  54         @param choices
  55             An array of strings with which to initialise the choice control.
  56         @param style
  57             Window style. See wxChoice.
  58         @param validator
  59             Window validator.
  60         @param name
  61             Window name.
  62
  63         @see Create(), wxValidator
  64     */
  65     wxChoice();
  66     wxChoice(wxWindow* parent, wxWindowID id,
  67              const wxPoint& pos,
  68              const wxSize& size, int n,
  69              const wxString choices[],
  70              long style = 0,
  71              const wxValidator& validator = wxDefaultValidator,
  72              const wxString& name = "choice");
  73     wxChoice(wxWindow* parent, wxWindowID id,
  74              const wxPoint& pos,
  75              const wxSize& size,
  76              const wxArrayString& choices,
  77              long style = 0,
  78              const wxValidator& validator = wxDefaultValidator,
  79              const wxString& name = "choice");
  80     //@}
  81
  82     /**
  83         Destructor, destroying the choice item.
  84     */
  85     ~wxChoice();
  86
  87     //@{
  88     /**
  89         Creates the choice for two-step construction. See wxChoice().
  90     */
  91     bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos,
  92                 const wxSize& size, int n,
  93                 const wxString choices[],
  94                 long style = 0,
  95                 const wxValidator& validator = wxDefaultValidator,
  96                 const wxString& name = "choice");
  97     bool Create(wxWindow* parent, wxWindowID id,
  98                 const wxPoint& pos,
  99                 const wxSize& size,
 100                 const wxArrayString& choices,
 101                 long style = 0,
 102                 const wxValidator& validator = wxDefaultValidator,
 103                 const wxString& name = "choice");
 104     //@}
 105
 106     /**
 107         Gets the number of columns in this choice item.
 108
 109         @remarks This is implemented for Motif only and always returns 1 for the
 110                  other platforms.
 111     */
 112     int GetColumns();
 113
 114     /**
 115         Unlike wxControlWithItems::GetSelection which only
 116         returns the accepted selection value, i.e. the selection in the control once
 117         the user closes the dropdown list, this function returns the current selection.
 118         That is, while the dropdown list is shown, it returns the currently selected
 119         item in it. When it is not shown, its result is the same as for the other
 120         function.
 121         This function is new since wxWidgets version 2.6.2 (before this version
 122         wxControlWithItems::GetSelection itself behaved like
 123         this).
 124     */
 125     int GetCurrentSelection();
 126
 127     /**
 128         Sets the number of columns in this choice item.
 129
 130         @param n
 131             Number of columns.
 132     */
 133     void SetColumns(int n = 1);
 134 };