X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4566dcbe24d452b729b0bad3f72ad63e6a60037c..b09857ae000a60704207d63290be937584805fb0:/interface/wx/msgdlg.h?ds=inline

diff --git a/interface/wx/msgdlg.h b/interface/wx/msgdlg.h
index 95a0f80743..1dde94ee77 100644
--- a/interface/wx/msgdlg.h
+++ b/interface/wx/msgdlg.h
@@ -3,9 +3,15 @@
 // Purpose:     interface of wxMessageDialog
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    Default message box caption string.
+*/
+const char wxMessageBoxCaptionStr[] = "Message";
+
+
 /**
     @class wxMessageDialog
 
@@ -19,8 +25,15 @@
         Puts a Cancel button in the message box. Must be combined with
         either @c wxOK or @c wxYES_NO.
     @style{wxYES_NO}
-        Puts Yes and No buttons in the message box. May be combined with
-        @c wxCANCEL.
+        Puts Yes and No buttons in the message box. It is recommended to always
+        use @c wxCANCEL with this style as otherwise the message box won't have
+        a close button under wxMSW and the user will be forced to answer it.
+    @style{wxHELP}
+        Puts a Help button to the message box. This button can have special
+        appearance or be specially positioned if its label is not changed from
+        the default one. Notice that using this button is not supported when
+        showing a message box from non-main thread in wxOSX/Cocoa and it is not
+        supported in wxOSX/Carbon at all. @since 2.9.3.
     @style{wxNO_DEFAULT}
         Makes the "No" button default, can only be used with @c wxYES_NO.
     @style{wxCANCEL_DEFAULT}
@@ -46,6 +59,11 @@
     @style{wxICON_QUESTION}
         Displays a question mark symbol. This icon is automatically used
         with @c wxYES_NO so it's usually unnecessary to specify it explicitly.
+        This style is not supported for message dialogs under wxMSW when a task
+        dialog is used to implement them (i.e. when running under Windows Vista
+        or later) because <a href="http://msdn.microsoft.com/en-us/library/aa511273.aspx">Microsoft
+        guidelines</a> indicate that no icon should be used for routine
+        confirmations. If it is specified, no icon will be displayed.
     @style{wxICON_INFORMATION}
         Displays an information symbol. This icon is used by default if
         @c wxYES_NO is not given so it is usually unnecessary to specify it
@@ -53,16 +71,55 @@
     @style{wxSTAY_ON_TOP}
         Makes the message box stay on top of all other windows and not only
         just its parent (currently implemented only under MSW and GTK).
+    @style{wxCENTRE}
+        Centre the message box on its parent or on the screen if parent is not
+        specified.
+        Setting this style under MSW makes no differences as the dialog is
+        always centered on the parent.
     @endStyleTable
 
     @library{wxcore}
     @category{cmndlg}
 
     @see @ref overview_cmndlg_msg
+    @see wxRichMessageDialog
 */
 class wxMessageDialog : public wxDialog
 {
 public:
+    /**
+        Helper class allowing to use either stock id or string labels.
+
+        This class should never be used explicitly and is not really part of
+        wxWidgets API but rather is just an implementation helper allowing the
+        methods such as SetYesNoLabels() and SetOKCancelLabels() below to be
+        callable with either stock ids (e.g. ::wxID_CLOSE) or strings
+        ("&Close").
+     */
+    class ButtonLabel
+    {
+    public:
+        /// Construct the label from a stock id.
+        ButtonLabel(int stockId);
+
+        /// Construct the label from the specified string.
+        ButtonLabel(const wxString& label);
+
+        /**
+            Return the associated label as string.
+
+            Get the string label, whether it was originally specified directly
+            or as a stock id -- this is only useful for platforms without native
+            stock items id support
+         */
+        wxString GetAsString() const;
+
+        /**
+            Return the stock id or wxID_NONE if this is not a stock label.
+         */
+        int GetStockId() const;
+    };
+
     /**
         Constructor specifying the message box properties.
         Use ShowModal() to show the dialog.
@@ -98,12 +155,29 @@ public:
         If it is set, the main message appears highlighted -- if supported --
         and this message appears beneath it in normal font. On the platforms
         which don't support extended messages, it is simply appended to the
-        normal message with a new line separating them.
+        normal message with an empty line separating them.
+
+        @since 2.9.0
     */
     virtual void SetExtendedMessage(const wxString& extendedMessage);
 
+    /**
+        Sets the label for the Help button.
+
+        Please see the remarks in SetYesNoLabels() documentation.
+
+        Notice that changing the label of the help button resets its special
+        status (if any, this depends on the platform) and it will be treated
+        just like another button in this case.
+
+        @since 2.9.3
+     */
+    virtual bool SetHelpLabel(const ButtonLabel& help);
+
     /**
         Sets the message shown by the dialog.
+
+        @since 2.9.0
     */
     virtual void SetMessage(const wxString& message);
 
@@ -111,6 +185,8 @@ public:
         Overrides the default labels of the OK and Cancel buttons.
 
         Please see the remarks in SetYesNoLabels() documentation.
+
+        @since 2.9.0
     */
     virtual bool SetOKCancelLabels(const ButtonLabel& ok,
                                    const ButtonLabel& cancel);
@@ -119,6 +195,8 @@ public:
         Overrides the default label of the OK button.
 
         Please see the remarks in SetYesNoLabels() documentation.
+
+        @since 2.9.0
     */
     virtual bool SetOKLabel(const ButtonLabel& ok);
 
@@ -126,6 +204,8 @@ public:
         Overrides the default labels of the Yes, No and Cancel buttons.
 
         Please see the remarks in SetYesNoLabels() documentation.
+
+        @since 2.9.0
     */
     virtual bool SetYesNoCancelLabels(const ButtonLabel& yes,
                                       const ButtonLabel& no,
@@ -162,16 +242,33 @@ public:
         else // buttons have standard "Yes"/"No" values, so rephrase the question
             dlg.SetMessage(_("Do you really want to quit?"));
         @endcode
+
+        @since 2.9.0
     */
     virtual bool SetYesNoLabels(const ButtonLabel& yes, const ButtonLabel& no);
 
     /**
-        Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, wxID_NO.
+        Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES,
+        wxID_NO or wxID_HELP.
 
         Notice that this method returns the identifier of the button which was
         clicked unlike wxMessageBox() function.
     */
     virtual int ShowModal();
+
+
+    wxString GetCaption() const;
+    wxString GetMessage() const;
+    wxString GetExtendedMessage() const;
+    long GetMessageDialogStyle() const;
+    bool HasCustomLabels() const;
+    wxString GetYesLabel() const;
+    wxString GetNoLabel() const;
+    wxString GetOKLabel() const;
+    wxString GetCancelLabel() const;
+    wxString GetHelpLabel() const;
+    long GetEffectiveIcon() const;
+
 };
 
 
@@ -191,9 +288,9 @@ public:
     extended text and custom labels for the message box buttons, are not
     provided by this function but only by wxMessageDialog.
 
-    The return value is one of: @c wxYES, @c wxNO, @c wxCANCEL or @c wxOK
-    (notice that this return value is @b different from the return value of
-    wxMessageDialog::ShowModal()).
+    The return value is one of: @c wxYES, @c wxNO, @c wxCANCEL, @c wxOK or @c
+    wxHELP (notice that this return value is @b different from the return value
+    of wxMessageDialog::ShowModal()).
 
     For example:
     @code
@@ -219,11 +316,12 @@ public:
         for @a x and @a y to let the system position the window.
     @param y
         Vertical dialog position (ignored under MSW).
+
     @header{wx/msgdlg.h}
 */
 int wxMessageBox(const wxString& message,
-                 const wxString& caption = "Message",
-                 int style = wxOK,
+                 const wxString& caption = wxMessageBoxCaptionStr,
+                 int style = wxOK | wxCENTRE,
                  wxWindow* parent = NULL,
                  int x = wxDefaultCoord,
                  int y = wxDefaultCoord);