interface/checkbox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        checkbox.h
   3 // Purpose:     documentation for wxCheckBox class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxCheckBox
  11     @wxheader{checkbox.h}
  12
  13     A checkbox is a labelled box which by default is either on (checkmark is
  14     visible) or off (no checkmark). Optionally (when the wxCHK_3STATE style flag
  15     is set) it can have a third state, called the mixed or undetermined state.
  16     Often this is used as a "Does Not Apply" state.
  17
  18     @beginStyleTable
  19     @style{wxCHK_2STATE}:
  20            Create a 2-state checkbox. This is the default.
  21     @style{wxCHK_3STATE}:
  22            Create a 3-state checkbox. Not implemented in wxMGL, wxOS2 and
  23            wxGTK built against GTK+ 1.2.
  24     @style{wxCHK_ALLOW_3RD_STATE_FOR_USER}:
  25            By default a user can't set a 3-state checkbox to the third state.
  26            It can only be done from code. Using this flags allows the user to
  27            set the checkbox to the third state by clicking.
  28     @style{wxALIGN_RIGHT}:
  29            Makes the text appear on the left of the checkbox.
  30     @endStyleTable
  31
  32     @beginEventTable
  33     @event{EVT_CHECKBOX(id\, func)}:
  34            Process a wxEVT_COMMAND_CHECKBOX_CLICKED event, when the checkbox
  35            is clicked.
  36     @endEventTable
  37
  38     @library{wxcore}
  39     @category{ctrl}
  40     @appearance{checkbox.png}
  41
  42     @seealso
  43     wxRadioButton, wxCommandEvent
  44 */
  45 class wxCheckBox : public wxControl
  46 {
  47 public:
  48     //@{
  49     /**
  50         Constructor, creating and showing a checkbox.
  51
  52         @param parent
  53         Parent window. Must not be @NULL.
  54
  55         @param id
  56         Checkbox identifier. The value wxID_ANY indicates a default value.
  57
  58         @param label
  59         Text to be displayed next to the checkbox.
  60
  61         @param pos
  62         Checkbox position. If wxDefaultPosition is specified then a default
  63         position is chosen.
  64
  65         @param size
  66         Checkbox size. If wxDefaultSize is specified then a default size is
  67         chosen.
  68
  69         @param style
  70         Window style. See wxCheckBox.
  71
  72         @param validator
  73         Window validator.
  74
  75         @param name
  76         Window name.
  77
  78         @sa Create(), wxValidator
  79     */
  80     wxCheckBox();
  81     wxCheckBox(wxWindow* parent, wxWindowID id,
  82                const wxString& label,
  83                const wxPoint& pos = wxDefaultPosition,
  84                const wxSize& size = wxDefaultSize,
  85                long style = 0,
  86                const wxValidator& val,
  87                const wxString& name = "checkBox");
  88     //@}
  89
  90     /**
  91         Destructor, destroying the checkbox.
  92     */
  93     ~wxCheckBox();
  94
  95     /**
  96         Creates the checkbox for two-step construction. See wxCheckBox()
  97         for details.
  98     */
  99     bool Create(wxWindow* parent, wxWindowID id,
 100                 const wxString& label,
 101                 const wxPoint& pos = wxDefaultPosition,
 102                 const wxSize& size = wxDefaultSize,
 103                 long style = 0,
 104                 const wxValidator& val,
 105                 const wxString& name = "checkBox");
 106
 107     /**
 108         Gets the state of a 3-state checkbox.
 109
 110         @returns Returns wxCHK_UNCHECKED when the checkbox is unchecked,
 111                    wxCHK_CHECKED  when it is checked and
 112                    wxCHK_UNDETERMINED when it's in the undetermined
 113                    state. Asserts when the function is used with a
 114                    2-state checkbox.
 115     */
 116     wxCheckBoxState Get3StateValue();
 117
 118     /**
 119         Gets the state of a 2-state checkbox.
 120
 121         @returns Returns @true if it is checked, @false otherwise.
 122     */
 123     bool GetValue();
 124
 125     /**
 126         Returns whether or not the checkbox is a 3-state checkbox.
 127
 128         @returns Returns @true if this checkbox is a 3-state checkbox, @false if
 129                    it's a 2-state checkbox.
 130     */
 131     bool Is3State();
 132
 133     /**
 134         Returns whether or not the user can set the checkbox to the third state.
 135
 136         @returns Returns @true if the user can set the third state of this
 137                    checkbox, @false if it can only be set
 138                    programmatically or if it's a 2-state checkbox.
 139     */
 140     bool Is3rdStateAllowedForUser();
 141
 142     /**
 143         This is just a maybe more readable synonym for
 144         GetValue(): just as the latter, it returns
 145         @true if the checkbox is checked and @false otherwise.
 146     */
 147     bool IsChecked();
 148
 149     /**
 150         Sets the checkbox to the given state. This does not cause a
 151         wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted.
 152
 153         @param state
 154         If @true, the check is on, otherwise it is off.
 155     */
 156     void SetValue(bool state);
 157 };