← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/richmsgdlg.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
interface/wx/richmsgdlg.h
 
1
/////////////////////////////////////////////////////////////////////////////
 
2
// Name:        wx/richmsgdlg.h
 
3
// Purpose:     interface of wxRichMessageDialog
 
4
// Author:      wxWidgets team
 
5
// RCS-ID:      $Id: richmsgdlg.h 67387 2011-04-04 09:21:52Z DS $
 
6
// Licence:     wxWindows licence
 
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
};