Commit | Line | Data |
---|---|---|
a1bdd4ab VZ |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: wx/richmsgdlg.h | |
3 | // Purpose: interface of wxRichMessageDialog | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
3fdcd5d5 | 6 | // Licence: wxWindows licence |
a1bdd4ab VZ |
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 | }; |