[wxWidgets.git] / interface / checkbox.h

/////////////////////////////////////////////////////////////////////////////
// Name:        checkbox.h
// Purpose:     documentation for wxCheckBox class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @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.
    
    @beginStyleTable
    @style{wxCHK_2STATE}:
           Create a 2-state checkbox. This is the default.
    @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}:
           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}:
           Makes the text appear on the left of the checkbox.
    @endStyleTable
    
    @beginEventTable
    @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}
    
    @seealso
    wxRadioButton, wxCommandEvent
*/
class wxCheckBox : public wxControl
{
public:
    //@{
    /**
        Constructor, creating and showing a checkbox.
        
        @param parent 
        Parent window. Must not be @NULL.
        
        @param id 
        Checkbox identifier. The value wxID_ANY indicates a default value.
        
        @param label 
        Text to be displayed next to the checkbox.
        
        @param pos 
        Checkbox position. If wxDefaultPosition is specified then a default
        position is chosen.
        
        @param size 
        Checkbox size. If wxDefaultSize is specified then a default size is
        chosen.
        
        @param style 
        Window style. See wxCheckBox.
        
        @param validator 
        Window validator.
        
        @param name 
        Window name.
        
        @sa Create(), wxValidator
    */
    wxCheckBox();
        wxCheckBox(wxWindow* parent, wxWindowID id,
                   const wxString& label,
                   const wxPoint& pos = wxDefaultPosition,
                   const wxSize& size = wxDefaultSize,
                   long style = 0,
                   const wxValidator& val,
                   const wxString& name = "checkBox");
    //@}

    /**
        Destructor, destroying the checkbox.
    */
    ~wxCheckBox();

    /**
        Creates the checkbox for two-step construction. See wxCheckBox()
        for details.
    */
    bool Create(wxWindow* parent, wxWindowID id,
                const wxString& label,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                long style = 0,
                const wxValidator& val,
                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();

    /**
        Gets the state of a 2-state checkbox.
        
        @returns Returns @true if it is checked, @false otherwise.
    */
    bool GetValue();

    /**
        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.
    */
    bool Is3State();

    /**
        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.
    */
    bool Is3rdStateAllowedForUser();

    /**
        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();

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