interface/wx/checkbox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        checkbox.h
   3 // Purpose:     interface of wxCheckBox
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /*
   9  * wxCheckBox style flags
  10  * (Using wxCHK_* because wxCB_* is used by wxComboBox).
  11  * Determine whether to use a 3-state or 2-state
  12  * checkbox. 3-state enables to differentiate
  13  * between 'unchecked', 'checked' and 'undetermined'.
  14  *
  15  * In addition to the styles here it is also possible to specify just 0 which
  16  * is treated the same as wxCHK_2STATE for compatibility (but using explicit
  17  * flag is preferred).
  18  */
  19 #define wxCHK_2STATE           0x4000
  20 #define wxCHK_3STATE           0x1000
  21
  22 /*
  23  * If this style is set the user can set the checkbox to the
  24  * undetermined state. If not set the undetermined set can only
  25  * be set programmatically.
  26  * This style can only be used with 3 state checkboxes.
  27  */
  28 #define wxCHK_ALLOW_3RD_STATE_FOR_USER 0x2000
  29
  30 /**
  31     The possible states of a 3-state wxCheckBox (Compatible with the 2-state
  32     wxCheckBox).
  33 */
  34 enum wxCheckBoxState
  35 {
  36     wxCHK_UNCHECKED,
  37     wxCHK_CHECKED,
  38     wxCHK_UNDETERMINED  ///< 3-state checkbox only
  39 };
  40
  41 /**
  42     @class wxCheckBox
  43
  44     A checkbox is a labelled box which by default is either on (checkmark is
  45     visible) or off (no checkmark). Optionally (when the wxCHK_3STATE style
  46     flag is set) it can have a third state, called the mixed or undetermined
  47     state. Often this is used as a "Does Not Apply" state.
  48
  49     @beginStyleTable
  50     @style{wxCHK_2STATE}
  51            Create a 2-state checkbox. This is the default.
  52     @style{wxCHK_3STATE}
  53            Create a 3-state checkbox. Not implemented in wxOS2 and
  54            wxGTK built against GTK+ 1.2.
  55     @style{wxCHK_ALLOW_3RD_STATE_FOR_USER}
  56            By default a user can't set a 3-state checkbox to the third state.
  57            It can only be done from code. Using this flags allows the user to
  58            set the checkbox to the third state by clicking.
  59     @style{wxALIGN_RIGHT}
  60            Makes the text appear on the left of the checkbox.
  61     @endStyleTable
  62
  63     @beginEventEmissionTable{wxCommandEvent}
  64     @event{EVT_CHECKBOX(id, func)}
  65            Process a @c wxEVT_CHECKBOX event, when the checkbox
  66            is clicked.
  67     @endEventTable
  68
  69     @library{wxcore}
  70     @category{ctrl}
  71     @appearance{checkbox}
  72
  73     @see wxRadioButton, wxCommandEvent
  74 */
  75 class wxCheckBox : public wxControl
  76 {
  77 public:
  78     /**
  79         Default constructor.
  80
  81         @see Create(), wxValidator
  82     */
  83     wxCheckBox();
  84
  85     /**
  86         Constructor, creating and showing a checkbox.
  87
  88         @param parent
  89             Parent window. Must not be @NULL.
  90         @param id
  91             Checkbox identifier. The value wxID_ANY indicates a default value.
  92         @param label
  93             Text to be displayed next to the checkbox.
  94         @param pos
  95             Checkbox position.
  96             If ::wxDefaultPosition is specified then a default position is chosen.
  97         @param size
  98             Checkbox size.
  99             If ::wxDefaultSize is specified then a default size is chosen.
 100         @param style
 101             Window style. See wxCheckBox.
 102         @param validator
 103             Window validator.
 104         @param name
 105             Window name.
 106
 107         @see Create(), wxValidator
 108     */
 109     wxCheckBox(wxWindow* parent, wxWindowID id,
 110                const wxString& label,
 111                const wxPoint& pos = wxDefaultPosition,
 112                const wxSize& size = wxDefaultSize,
 113                long style = 0,
 114                const wxValidator& validator = wxDefaultValidator,
 115                const wxString& name = wxCheckBoxNameStr);
 116
 117     /**
 118         Destructor, destroying the checkbox.
 119     */
 120     virtual ~wxCheckBox();
 121
 122     /**
 123         Creates the checkbox for two-step construction. See wxCheckBox()
 124         for details.
 125     */
 126     bool Create(wxWindow* parent, wxWindowID id, const wxString& label,
 127                 const wxPoint& pos = wxDefaultPosition,
 128                 const wxSize& size = wxDefaultSize, long style = 0,
 129                 const wxValidator& validator = wxDefaultValidator,
 130                 const wxString& name = wxCheckBoxNameStr);
 131
 132     /**
 133         Gets the state of a 2-state checkbox.
 134
 135         @return Returns @true if it is checked, @false otherwise.
 136     */
 137     virtual bool GetValue() const;
 138
 139     /**
 140         Gets the state of a 3-state checkbox. Asserts when the function is used
 141         with a 2-state checkbox.
 142     */
 143     wxCheckBoxState Get3StateValue() const;
 144
 145     /**
 146         Returns whether or not the checkbox is a 3-state checkbox.
 147
 148         @return @true if this checkbox is a 3-state checkbox, @false if it's
 149                 a 2-state checkbox.
 150     */
 151     bool Is3State() const;
 152
 153     /**
 154         Returns whether or not the user can set the checkbox to the third
 155         state.
 156
 157         @return @true if the user can set the third state of this checkbox,
 158                 @false if it can only be set programmatically or if it's a
 159                 2-state checkbox.
 160     */
 161     bool Is3rdStateAllowedForUser() const;
 162
 163     /**
 164         This is just a maybe more readable synonym for GetValue(): just as the
 165         latter, it returns @true if the checkbox is checked and @false
 166         otherwise.
 167     */
 168     bool IsChecked() const;
 169
 170     /**
 171         Sets the checkbox to the given state. This does not cause a
 172         @c wxEVT_CHECKBOX event to get emitted.
 173
 174         @param state
 175             If @true, the check is on, otherwise it is off.
 176     */
 177     virtual void SetValue(bool state);
 178
 179     /**
 180         Sets the checkbox to the given state. This does not cause a
 181         @c wxEVT_CHECKBOX event to get emitted.
 182
 183         Asserts when the checkbox is a 2-state checkbox and setting the state
 184         to wxCHK_UNDETERMINED.
 185     */
 186     void Set3StateValue(wxCheckBoxState state);
 187 };
 188