Fix missing documentation for several GDI functions.

[wxWidgets.git] / include / wx / msgdlg.h

diff --git a/include/wx/msgdlg.h b/include/wx/msgdlg.h
index 7dbffe33a3e4855c6096e51f106f136cd9b8a20a..14df02f9614cfd3c271e159ba93591fb27dd7f63 100644 (file)
--- a/include/wx/msgdlg.h
+++ b/include/wx/msgdlg.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        wx/msgdlgg.h
+// Name:        wx/msgdlg.h

 // Purpose:     common header and base class for wxMessageDialog
 // Author:      Julian Smart
 // Modified by:
 // Purpose:     common header and base class for wxMessageDialog
 // Author:      Julian Smart
 // Modified by:


@@ -19,7 +19,7 @@
 #include "wx/dialog.h"
 #include "wx/stockitem.h"
 
 #include "wx/dialog.h"
 #include "wx/stockitem.h"
 

-WXDLLIMPEXP_DATA_CORE(extern const char) wxMessageBoxCaptionStr[];
+extern WXDLLIMPEXP_DATA_CORE(const char) wxMessageBoxCaptionStr[];

 
 // ----------------------------------------------------------------------------
 // wxMessageDialogBase: base class defining wxMessageDialog interface
 
 // ----------------------------------------------------------------------------
 // wxMessageDialogBase: base class defining wxMessageDialog interface


@@ -68,8 +68,9 @@ public:
         // stock items id support
         wxString GetAsString() const
         {
         // stock items id support
         wxString GetAsString() const
         {

-            return m_stockId == wxID_NONE ? m_label
-                                          : wxGetStockLabel(m_stockId);
+            return m_stockId == wxID_NONE
+                    ? m_label
+                    : wxGetStockLabel(m_stockId, wxSTOCK_FOR_BUTTON);

         }
 
         // return the stock id or wxID_NONE if this is not a stock label
         }
 
         // return the stock id or wxID_NONE if this is not a stock label


@@ -83,7 +84,6 @@ public:
         const int m_stockId;
     };
 
         const int m_stockId;
     };
 

-

     // ctors
     wxMessageDialogBase() { m_dialogStyle = 0; }
     wxMessageDialogBase(wxWindow *parent,
     // ctors
     wxMessageDialogBase() { m_dialogStyle = 0; }
     wxMessageDialogBase(wxWindow *parent,


@@ -100,102 +100,54 @@ public:
     // virtual dtor for the base class
     virtual ~wxMessageDialogBase() { }
 
     // virtual dtor for the base class
     virtual ~wxMessageDialogBase() { }
 

-
-    // methods for setting up more custom message dialogs -- all functions
-    // return false if they're not implemented
-    virtual bool SetYesNoLabels(const ButtonLabel& WXUNUSED(yes),
-                                const ButtonLabel& WXUNUSED(no))
-    {
-        return false;
-    }
-
-    virtual bool SetYesNoCancelLabels(const ButtonLabel& WXUNUSED(yes),
-                                      const ButtonLabel& WXUNUSED(no),
-                                      const ButtonLabel& WXUNUSED(cancel))
-    {
-        return false;
-    }
-
-    virtual bool SetOKLabel(const ButtonLabel& WXUNUSED(ok))
-    {
-        return false;
-    }
-
-    virtual bool SetOKCancelLabels(const ButtonLabel& WXUNUSED(ok),
-                                   const ButtonLabel& WXUNUSED(cancel))
-    {
-        return false;
-    }
+    wxString GetCaption() const { return m_caption; }

 
     virtual void SetMessage(const wxString& message)
     {
         m_message = message;
     }
 
 
     virtual void SetMessage(const wxString& message)
     {
         m_message = message;
     }
 

-    virtual void SetExtendedMessage(const wxString& extendedMessage)
+    wxString GetMessage() const { return m_message; }
+
+    void SetExtendedMessage(const wxString& extendedMessage)

     {
         m_extendedMessage = extendedMessage;
     }
 
     {
         m_extendedMessage = extendedMessage;
     }
 

+    wxString GetExtendedMessage() const { return m_extendedMessage; }
+

     // change the dialog style flag
     void SetMessageDialogStyle(long style)
     {
         wxASSERT_MSG( ((style & wxYES_NO) == wxYES_NO) || !(style & wxYES_NO),
                       "wxYES and wxNO may only be used together" );
 
     // change the dialog style flag
     void SetMessageDialogStyle(long style)
     {
         wxASSERT_MSG( ((style & wxYES_NO) == wxYES_NO) || !(style & wxYES_NO),
                       "wxYES and wxNO may only be used together" );
 

+        wxASSERT_MSG( !(style & wxYES) || !(style & wxOK),
+                      "wxOK and wxYES/wxNO can't be used together" );
+
+        // It is common to specify just the icon, without wxOK, in the existing
+        // code, especially one written by Windows programmers as MB_OK is 0
+        // and so they're used to omitting wxOK. Don't complain about it but
+        // just add wxOK implicitly for compatibility.
+        if ( !(style & wxYES) && !(style & wxOK) )
+            style |= wxOK;
+

         wxASSERT_MSG( (style & wxID_OK) != wxID_OK,
                       "wxMessageBox: Did you mean wxOK (and not wxID_OK)?" );
 
         wxASSERT_MSG( (style & wxID_OK) != wxID_OK,
                       "wxMessageBox: Did you mean wxOK (and not wxID_OK)?" );
 

-        m_dialogStyle = style;
-    }
+        wxASSERT_MSG( !(style & wxNO_DEFAULT) || (style & wxNO),
+                      "wxNO_DEFAULT is invalid without wxNO" );

 
 

-protected:
-    long GetMessageDialogStyle() const { return m_dialogStyle; }
+        wxASSERT_MSG( !(style & wxCANCEL_DEFAULT) || (style & wxCANCEL),
+                      "wxCANCEL_DEFAULT is invalid without wxCANCEL" );

 
 

+        wxASSERT_MSG( !(style & wxCANCEL_DEFAULT) || !(style & wxNO_DEFAULT),
+                      "only one default button can be specified" );

 
 

-    // for the platforms not supporting separate main and extended messages
-    // this function should be used to combine both of them in a single string
-    wxString GetFullMessage() const
-    {
-        wxString msg = m_message;
-        if ( !m_extendedMessage.empty() )
-            msg << "\n\n" << m_extendedMessage;
-
-        return msg;
+        m_dialogStyle = style;

     }
 
     }
 

-    wxString m_message,
-             m_extendedMessage,
-             m_caption;
-    long m_dialogStyle;
-
-    DECLARE_NO_COPY_CLASS(wxMessageDialogBase)
-};
-
-// this is a helper class for native wxMessageDialog implementations which need
-// to store the custom button labels as member variables and then use them in
-// ShowModal() (there could conceivably be a port which would have some native
-// functions for setting these labels immediately and we also don't need to
-// store them at all if custom labels are not supported, which is why we do
-// this in a separate class and not wxMessageDialogBase itself)
-#if defined(__WXCOCOA__) || \
-    defined(__WXGTK20__) || \
-    defined(__WXMAC__) || \
-    defined(__WXMSW__)
-
-class WXDLLIMPEXP_CORE wxMessageDialogWithCustomLabels
-    : public wxMessageDialogBase
-{
-public:
-    // ctors
-    wxMessageDialogWithCustomLabels() { }
-    wxMessageDialogWithCustomLabels(wxWindow *parent,
-                                    const wxString& message,
-                                    const wxString& caption,
-                                    long style)
-        : wxMessageDialogBase(parent, message, caption, style)
-    {
-    }
+    long GetMessageDialogStyle() const { return m_dialogStyle; }

 
     // customization of the message box buttons
     virtual bool SetYesNoLabels(const ButtonLabel& yes,const ButtonLabel& no)
 
     // customization of the message box buttons
     virtual bool SetYesNoLabels(const ButtonLabel& yes,const ButtonLabel& no)


@@ -229,11 +181,16 @@ public:
         return true;
     }
 
         return true;
     }
 

-protected:
+    virtual bool SetHelpLabel(const ButtonLabel& help)
+    {
+        DoSetCustomLabel(m_help, help);
+        return true;
+    }
+

     // test if any custom labels were set
     bool HasCustomLabels() const
     {
     // test if any custom labels were set
     bool HasCustomLabels() const
     {

-        return !(m_ok.empty() && m_cancel.empty() &&
+        return !(m_ok.empty() && m_cancel.empty() && m_help.empty() &&

                  m_yes.empty() && m_no.empty());
     }
 
                  m_yes.empty() && m_no.empty());
     }
 


@@ -248,6 +205,46 @@ protected:
         { return m_ok.empty() ? GetDefaultOKLabel() : m_ok; }
     wxString GetCancelLabel() const
         { return m_cancel.empty() ? GetDefaultCancelLabel() : m_cancel; }
         { return m_ok.empty() ? GetDefaultOKLabel() : m_ok; }
     wxString GetCancelLabel() const
         { return m_cancel.empty() ? GetDefaultCancelLabel() : m_cancel; }

+    wxString GetHelpLabel() const
+        { return m_help.empty() ? GetDefaultHelpLabel() : m_help; }
+
+    // based on message dialog style, returns exactly one of: wxICON_NONE,
+    // wxICON_ERROR, wxICON_WARNING, wxICON_QUESTION, wxICON_INFORMATION,
+    // wxICON_AUTH_NEEDED
+    virtual long GetEffectiveIcon() const
+    {
+        if ( m_dialogStyle & wxICON_NONE )
+            return wxICON_NONE;
+        else if ( m_dialogStyle & wxICON_ERROR )
+            return wxICON_ERROR;
+        else if ( m_dialogStyle & wxICON_WARNING )
+            return wxICON_WARNING;
+        else if ( m_dialogStyle & wxICON_QUESTION )
+            return wxICON_QUESTION;
+        else if ( m_dialogStyle & wxICON_INFORMATION )
+            return wxICON_INFORMATION;
+        else if ( m_dialogStyle & wxYES )
+            return wxICON_QUESTION;
+        else
+            return wxICON_INFORMATION;
+    }
+
+protected:
+    // for the platforms not supporting separate main and extended messages
+    // this function should be used to combine both of them in a single string
+    wxString GetFullMessage() const
+    {
+        wxString msg = m_message;
+        if ( !m_extendedMessage.empty() )
+            msg << "\n\n" << m_extendedMessage;
+
+        return msg;
+    }
+
+    wxString m_message,
+             m_extendedMessage,
+             m_caption;
+    long m_dialogStyle;

 
     // this function is called by our public SetXXXLabels() and should assign
     // the value to var with possibly some transformation (e.g. Cocoa version
 
     // this function is called by our public SetXXXLabels() and should assign
     // the value to var with possibly some transformation (e.g. Cocoa version


@@ -258,36 +255,46 @@ protected:
         var = label.GetAsString();
     }
 
         var = label.GetAsString();
     }
 

+    // these functions return the custom label or empty string and should be
+    // used only in specific circumstances such as creating the buttons with
+    // these labels (in which case it makes sense to only use a custom label if
+    // it was really given and fall back on stock label otherwise), use the
+    // Get{Yes,No,OK,Cancel}Label() methods above otherwise
+    const wxString& GetCustomYesLabel() const { return m_yes; }
+    const wxString& GetCustomNoLabel() const { return m_no; }
+    const wxString& GetCustomOKLabel() const { return m_ok; }
+    const wxString& GetCustomHelpLabel() const { return m_help; }
+    const wxString& GetCustomCancelLabel() const { return m_cancel; }
+

 private:
     // these functions may be overridden to provide different defaults for the
     // default button labels (this is used by wxGTK)
 private:
     // these functions may be overridden to provide different defaults for the
     // default button labels (this is used by wxGTK)

-    virtual wxString GetDefaultYesLabel() const { return _("Yes"); }
-    virtual wxString GetDefaultNoLabel() const { return _("No"); }
-    virtual wxString GetDefaultOKLabel() const { return _("OK"); }
-    virtual wxString GetDefaultCancelLabel() const { return _("Cancel"); }
+    virtual wxString GetDefaultYesLabel() const { return wxGetTranslation("Yes"); }
+    virtual wxString GetDefaultNoLabel() const { return wxGetTranslation("No"); }
+    virtual wxString GetDefaultOKLabel() const { return wxGetTranslation("OK"); }
+    virtual wxString GetDefaultCancelLabel() const { return wxGetTranslation("Cancel"); }
+    virtual wxString GetDefaultHelpLabel() const { return wxGetTranslation("Help"); }

 
     // labels for the buttons, initially empty meaning that the defaults should
     // be used, use GetYes/No/OK/CancelLabel() to access them
     wxString m_yes,
              m_no,
              m_ok,
 
     // labels for the buttons, initially empty meaning that the defaults should
     // be used, use GetYes/No/OK/CancelLabel() to access them
     wxString m_yes,
              m_no,
              m_ok,

-             m_cancel;
+             m_cancel,
+             m_help;

 
 

-    DECLARE_NO_COPY_CLASS(wxMessageDialogWithCustomLabels)
+    wxDECLARE_NO_COPY_CLASS(wxMessageDialogBase);

 };
 
 };
 

-#endif // ports needing wxMessageDialogWithCustomLabels
+#include "wx/generic/msgdlgg.h"

 
 #if defined(__WX_COMPILING_MSGDLGG_CPP__) || \
     defined(__WXUNIVERSAL__) || defined(__WXGPE__) || \
     (defined(__WXGTK__) && !defined(__WXGTK20__))
 
 #if defined(__WX_COMPILING_MSGDLGG_CPP__) || \
     defined(__WXUNIVERSAL__) || defined(__WXGPE__) || \
     (defined(__WXGTK__) && !defined(__WXGTK20__))

-    #include "wx/generic/msgdlgg.h"

 
     #define wxMessageDialog wxGenericMessageDialog
 #elif defined(__WXCOCOA__)
     #include "wx/cocoa/msgdlg.h"
 
     #define wxMessageDialog wxGenericMessageDialog
 #elif defined(__WXCOCOA__)
     #include "wx/cocoa/msgdlg.h"

-#elif defined(__WXPALMOS__)
-    #include "wx/palmos/msgdlg.h"

 #elif defined(__WXMSW__)
     #include "wx/msw/msgdlg.h"
 #elif defined(__WXMOTIF__)
 #elif defined(__WXMSW__)
     #include "wx/msw/msgdlg.h"
 #elif defined(__WXMOTIF__)