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