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