interface/checkbox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        checkbox.h
   3 // Purpose:     documentation for wxCheckBox class
   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     @seealso
  43     wxRadioButton, wxCommandEvent
  44 */
  45 class wxCheckBox : public wxControl
  46 {
  47 public:
  48     //@{
  49     /**
  50         Constructor, creating and showing a checkbox.
  51
  52         @param parent
  53             Parent window. Must not be @NULL.
  54         @param id
  55             Checkbox identifier. The value wxID_ANY indicates a default value.
  56         @param label
  57             Text to be displayed next to the checkbox.
  58         @param pos
  59             Checkbox position. If wxDefaultPosition is specified then a default
  60         position is chosen.
  61         @param size
  62             Checkbox size. If wxDefaultSize is specified then a default
  63         size is chosen.
  64         @param style
  65             Window style. See wxCheckBox.
  66         @param validator
  67             Window validator.
  68         @param name
  69             Window name.
  70
  71         @see Create(), wxValidator
  72     */
  73     wxCheckBox();
  74     wxCheckBox(wxWindow* parent, wxWindowID id,
  75                const wxString& label,
  76                const wxPoint& pos = wxDefaultPosition,
  77                const wxSize& size = wxDefaultSize,
  78                long style = 0,
  79                const wxValidator& val,
  80                const wxString& name = "checkBox");
  81     //@}
  82
  83     /**
  84         Destructor, destroying the checkbox.
  85     */
  86     ~wxCheckBox();
  87
  88     /**
  89         Creates the checkbox for two-step construction. See wxCheckBox()
  90         for details.
  91     */
  92     bool Create(wxWindow* parent, wxWindowID id,
  93                 const wxString& label,
  94                 const wxPoint& pos = wxDefaultPosition,
  95                 const wxSize& size = wxDefaultSize,
  96                 long style = 0,
  97                 const wxValidator& val,
  98                 const wxString& name = "checkBox");
  99
 100     /**
 101         Gets the state of a 3-state checkbox.
 102
 103         @returns Returns wxCHK_UNCHECKED when the checkbox is unchecked,
 104                  wxCHK_CHECKED  when it is checked and
 105                  wxCHK_UNDETERMINED when it's in the undetermined state.
 106                  Asserts when the function is used with a 2-state
 107                  checkbox.
 108     */
 109     wxCheckBoxState Get3StateValue();
 110
 111     /**
 112         Gets the state of a 2-state checkbox.
 113
 114         @returns Returns @true if it is checked, @false otherwise.
 115     */
 116     bool GetValue();
 117
 118     /**
 119         Returns whether or not the checkbox is a 3-state checkbox.
 120
 121         @returns Returns @true if this checkbox is a 3-state checkbox, @false if
 122                  it's a 2-state checkbox.
 123     */
 124     bool Is3State();
 125
 126     /**
 127         Returns whether or not the user can set the checkbox to the third state.
 128
 129         @returns Returns @true if the user can set the third state of this
 130                  checkbox, @false if it can only be set programmatically
 131                  or if it's a 2-state checkbox.
 132     */
 133     bool Is3rdStateAllowedForUser();
 134
 135     /**
 136         This is just a maybe more readable synonym for
 137         GetValue(): just as the latter, it returns
 138         @true if the checkbox is checked and @false otherwise.
 139     */
 140     bool IsChecked();
 141
 142     /**
 143         Sets the checkbox to the given state. This does not cause a
 144         wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted.
 145
 146         @param state
 147             If @true, the check is on, otherwise it is off.
 148     */
 149     void SetValue(bool state);
 150 };