interface/wx/richmsgdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/richmsgdlg.h
   3 // Purpose:     interface of wxRichMessageDialog
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   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 };