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