interface/wx/checkbox.h

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