interface/wx/richmsgdlg.h

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