other misc fixes

[wxWidgets.git] / interface / checkbox.h

diff --git a/interface/checkbox.h b/interface/checkbox.h
index 2b99bc2467bb62c0a721eddaa1f38a7c5c03b4df..944f9b248c70c76c645370818a30f1934fced603 100644 (file)
--- a/interface/checkbox.h
+++ b/interface/checkbox.h
@@ -6,45 +6,62 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    The possible states of a 3-state wxCheckBox (Compatible with the 2-state
+    wxCheckBox).
+*/
+enum wxCheckBoxState
+{
+    wxCHK_UNCHECKED,
+    wxCHK_CHECKED,
+    wxCHK_UNDETERMINED  ///< 3-state checkbox only
+};
+
 /**
     @class wxCheckBox
     @wxheader{checkbox.h}
 
     A checkbox is a labelled box which by default is either on (checkmark is
-    visible) or off (no checkmark). Optionally (when the wxCHK_3STATE style flag
-    is set) it can have a third state, called the mixed or undetermined state.
-    Often this is used as a "Does Not Apply" state.
+    visible) or off (no checkmark). Optionally (when the wxCHK_3STATE style
+    flag is set) it can have a third state, called the mixed or undetermined
+    state. Often this is used as a "Does Not Apply" state.
 
     @beginStyleTable
-    @style{wxCHK_2STATE}:
+    @style{wxCHK_2STATE}
            Create a 2-state checkbox. This is the default.
-    @style{wxCHK_3STATE}:
+    @style{wxCHK_3STATE}
            Create a 3-state checkbox. Not implemented in wxMGL, wxOS2 and
            wxGTK built against GTK+ 1.2.
-    @style{wxCHK_ALLOW_3RD_STATE_FOR_USER}:
+    @style{wxCHK_ALLOW_3RD_STATE_FOR_USER}
            By default a user can't set a 3-state checkbox to the third state.
            It can only be done from code. Using this flags allows the user to
            set the checkbox to the third state by clicking.
-    @style{wxALIGN_RIGHT}:
+    @style{wxALIGN_RIGHT}
            Makes the text appear on the left of the checkbox.
     @endStyleTable
 
-    @beginEventTable
-    @event{EVT_CHECKBOX(id, func)}:
+    @beginEventTable{wxCommandEvent}
+    @event{EVT_CHECKBOX(id, func)}
            Process a wxEVT_COMMAND_CHECKBOX_CLICKED event, when the checkbox
            is clicked.
     @endEventTable
 
     @library{wxcore}
     @category{ctrl}
-    @appearance{checkbox.png}
+    <!-- @appearance{checkbox.png} -->
 
     @see wxRadioButton, wxCommandEvent
 */
 class wxCheckBox : public wxControl
 {
 public:
-    //@{
+    /**
+        Default constructor.
+
+        @see Create(), wxValidator
+    */
+    wxCheckBox();
+
     /**
         Constructor, creating and showing a checkbox.
 
@@ -56,10 +73,10 @@ public:
             Text to be displayed next to the checkbox.
         @param pos
             Checkbox position. If wxDefaultPosition is specified then a default
-        position is chosen.
+            position is chosen.
         @param size
-            Checkbox size. If wxDefaultSize is specified then a default
-        size is chosen.
+            Checkbox size. If wxDefaultSize is specified then a default size is
+            chosen.
         @param style
             Window style. See wxCheckBox.
         @param validator
@@ -69,7 +86,6 @@ public:
 
         @see Create(), wxValidator
     */
-    wxCheckBox();
     wxCheckBox(wxWindow* parent, wxWindowID id,
                const wxString& label,
                const wxPoint& pos = wxDefaultPosition,
@@ -77,7 +93,6 @@ public:
                long style = 0,
                const wxValidator& val = wxDefaultValidator,
                const wxString& name = "checkBox");
-    //@}
 
     /**
         Destructor, destroying the checkbox.
@@ -96,17 +111,6 @@ public:
                 const wxValidator& val = wxDefaultValidator,
                 const wxString& name = "checkBox");
 
-    /**
-        Gets the state of a 3-state checkbox.
-
-        @returns Returns wxCHK_UNCHECKED when the checkbox is unchecked,
-                 wxCHK_CHECKED  when it is checked and
-                 wxCHK_UNDETERMINED when it's in the undetermined state.
-                 Asserts when the function is used with a 2-state
-                 checkbox.
-    */
-    wxCheckBoxState Get3StateValue() const;
-
     /**
         Gets the state of a 2-state checkbox.
 
@@ -114,27 +118,34 @@ public:
     */
     bool GetValue() const;
 
+    /**
+        Gets the state of a 3-state checkbox. Asserts when the function is used
+        with a 2-state checkbox.
+    */
+    wxCheckBoxState Get3StateValue() const;
+
     /**
         Returns whether or not the checkbox is a 3-state checkbox.
 
-        @returns Returns @true if this checkbox is a 3-state checkbox, @false if
-                 it's a 2-state checkbox.
+        @returns Returns @true if this checkbox is a 3-state checkbox, @false
+                 if it's a 2-state checkbox.
     */
     bool Is3State() const;
 
     /**
-        Returns whether or not the user can set the checkbox to the third state.
+        Returns whether or not the user can set the checkbox to the third
+        state.
 
         @returns Returns @true if the user can set the third state of this
-                 checkbox, @false if it can only be set programmatically
-                 or if it's a 2-state checkbox.
+                 checkbox, @false if it can only be set programmatically or if
+                 it's a 2-state checkbox.
     */
     bool Is3rdStateAllowedForUser() const;
 
     /**
-        This is just a maybe more readable synonym for
-        GetValue(): just as the latter, it returns
-        @true if the checkbox is checked and @false otherwise.
+        This is just a maybe more readable synonym for GetValue(): just as the
+        latter, it returns @true if the checkbox is checked and @false
+        otherwise.
     */
     bool IsChecked() const;
 
@@ -146,5 +157,14 @@ public:
             If @true, the check is on, otherwise it is off.
     */
     void SetValue(bool state);
+
+    /**
+        Sets the checkbox to the given state. This does not cause a
+        wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted.
+
+        Asserts when the checkbox is a 2-state checkbox and setting the state
+        to wxCHK_UNDETERMINED.
+    */
+    void Set3StateValue(const wxCheckBoxState state);
 };