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