git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: wx/richmsgdlg.h
	3	// Purpose: interface of wxRichMessageDialog
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxRichMessageDialog
	11
	12	Extension of wxMessageDialog with additional functionality.
	13
	14	This class adds the possibility of using a checkbox (that is especially
	15	useful for implementing the "Don't ask me again" kind of dialogs) and an
	16	extra explanatory text which is initially collapsed and not shown to the
	17	user but can be expanded to show more information.
	18
	19	Notice that currently the native dialog is used only under MSW when using
	20	Vista or later Windows version. Elsewhere, or for older versions of
	21	Windows, a generic implementation which is less familiar to the users is
	22	used. Because of this it's recommended to use this class only if you do
	23	need its extra functionality and use wxMessageDialog which does have native
	24	implementation under all platforms otherwise. However if you do need to put
	25	e.g. a checkbox in a dialog, you should definitely consider using this
	26	class instead of using your own custom dialog because it will have much
	27	better appearance at least under recent Windows versions.
	28
	29	To use this class, you need to create the dialog object and call
	30	ShowCheckBox() and/or ShowDetailedText() to configure its contents.
	31	Other than that, it is used in exactly the same way as wxMessageDialog and
	32	supports all the styles supported by it. In particular, ShowModal() return
	33	value is the same as for wxMessageDialog. The only difference is that you
	34	need to use IsCheckBoxChecked() to examine the checkbox value if you had
	35	called ShowCheckBox().
	36
	37	Here is a simple example:
	38	@code
	39	void MyFrame::ShowDialog()
	40	{
	41	if ( ... shouldn't show this dialog again ... )
	42	return;
	43
	44	wxRichMessageDialog dlg(this, "Welcome to my wonderful program!");
	45	dlg.ShowCheckBox("Don't show welcome dialog again");
	46	dlg.ShowModal(); // return value ignored as we have "Ok" only anyhow
	47
	48	if ( dlg.IsCheckBoxChecked() )
	49	... make sure we won't show it again the next time ...
	50	}
	51	@endcode
	52
	53	@since 2.9.2
	54
	55	@library{wxcore}
	56	@category{cmndlg}
	57
	58	@see @ref overview_cmndlg_msg
	59	*/
	60	class wxRichMessageDialog : public wxRichMessageDialogBase
	61	{
	62	public:
	63	/**
	64	Constructor specifying the rich message dialog properties.
	65	Works just like the constructor for wxMessageDialog.
	66	*/
	67	wxRichMessageDialog(wxWindow* parent,
	68	const wxString& message,
	69	const wxString& caption = wxMessageBoxCaptionStr,
	70	long style = wxOK \| wxCENTRE,
	71	const wxPoint& pos = wxDefaultPosition);
	72
	73	/**
	74	Shows a checkbox with a given label or hides it.
	75
	76	@param checkBoxText
	77	If the parameter is non-empty a checkbox will be shown with that
	78	label, otherwise it will be hidden.
	79	@param checked
	80	The initial state of the checkbox.
	81	*/
	82	void ShowCheckBox(const wxString& checkBoxText, bool checked = false);
	83
	84
	85	/**
	86	Retrieves the label for the checkbox.
	87
	88	@return
	89	The label for the checkbox, will be the empty string if no
	90	checkbox is used.
	91	*/
	92	wxString GetCheckBoxText() const;
	93
	94	/**
	95	Shows or hides a detailed text and an expander that is used to
	96	show or hide the detailed text.
	97
	98	@param detailedText
	99	The detailed text that can be expanded when the dialog is shown,
	100	if empty no detailed text will be used.
	101	*/
	102	void ShowDetailedText(const wxString& detailedText);
	103
	104	/**
	105	Retrieves the detailed text.
	106
	107	@return
	108	The detailed text or empty if detailed text is not used.
	109	*/
	110	wxString GetDetailedText() const;
	111
	112	/**
	113	Retrieves the state of the checkbox.
	114
	115	If this method is called before showing the dialog, the initial value
	116	of the checkbox, as set by ShowCheckBox() is used. If it is called
	117	after calling wxDialog::ShowModal(), the value set by the user is
	118	returned.
	119
	120	@return @true if the checkbox is checked or @false if not.
	121	*/
	122	bool IsCheckBoxChecked() const;
	123
	124	/**
	125	Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, wxID_NO.
	126
	127	IsCheckBoxChecked() can be called afterwards to retrieve the value of the
	128	check box if one was used.
	129	*/
	130	virtual int ShowModal();
	131	};