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     @beginEventEmissionTable{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.
  75             If ::wxDefaultPosition is specified then a default position is chosen.
  76         @param size
  77             Checkbox size.
  78             If ::wxDefaultSize is specified then a default size is 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& validator = wxDefaultValidator,
  94                const wxString& name = wxCheckBoxNameStr);
  95
  96     /**
  97         Destructor, destroying the checkbox.
  98     */
  99     virtual ~wxCheckBox();
 100
 101     /**
 102         Creates the checkbox for two-step construction. See wxCheckBox()
 103         for details.
 104     */
 105     bool Create(wxWindow* parent, wxWindowID id, const wxString& label,
 106                 const wxPoint& pos = wxDefaultPosition,
 107                 const wxSize& size = wxDefaultSize, long style = 0,
 108                 const wxValidator& validator = wxDefaultValidator,
 109                 const wxString& = wxCheckBoxNameStr);
 110
 111     /**
 112         Gets the state of a 2-state checkbox.
 113
 114         @return Returns @true if it is checked, @false otherwise.
 115     */
 116     virtual bool GetValue() const;
 117
 118     /**
 119         Gets the state of a 3-state checkbox. Asserts when the function is used
 120         with a 2-state checkbox.
 121     */
 122     wxCheckBoxState Get3StateValue() const;
 123
 124     /**
 125         Returns whether or not the checkbox is a 3-state checkbox.
 126
 127         @return @true if this checkbox is a 3-state checkbox, @false if it's
 128                 a 2-state checkbox.
 129     */
 130     bool Is3State() const;
 131
 132     /**
 133         Returns whether or not the user can set the checkbox to the third
 134         state.
 135
 136         @return @true if the user can set the third state of this checkbox,
 137                 @false if it can only be set programmatically or if it's a
 138                 2-state checkbox.
 139     */
 140     bool Is3rdStateAllowedForUser() const;
 141
 142     /**
 143         This is just a maybe more readable synonym for GetValue(): just as the
 144         latter, it returns @true if the checkbox is checked and @false
 145         otherwise.
 146     */
 147     bool IsChecked() const;
 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     virtual void SetValue(bool state);
 157
 158     /**
 159         Sets the checkbox to the given state. This does not cause a
 160         wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted.
 161
 162         Asserts when the checkbox is a 2-state checkbox and setting the state
 163         to wxCHK_UNDETERMINED.
 164     */
 165     void Set3StateValue(wxCheckBoxState state);
 166 };
 167