X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/43c48e1e53d74cef62d15f08f015d9efeb45a0c1..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/msgdlg.h?ds=sidebyside diff --git a/interface/wx/msgdlg.h b/interface/wx/msgdlg.h index 88243d4bec..6bc5426f2e 100644 --- a/interface/wx/msgdlg.h +++ b/interface/wx/msgdlg.h @@ -2,68 +2,137 @@ // Name: msgdlg.h // 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 This class represents a dialog that shows a single or multi-line message, with a choice of OK, Yes, No and Cancel buttons. + @beginStyleTable + @style{wxOK} + Puts an Ok button in the message box. May be combined with @c wxCANCEL. + @style{wxCANCEL} + 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. 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. Available since wxWidgets 2.9.3. + @style{wxNO_DEFAULT} + Makes the "No" button default, can only be used with @c wxYES_NO. + @style{wxCANCEL_DEFAULT} + Makes the "Cancel" button default, can only be used with @c wxCANCEL + @style{wxYES_DEFAULT} + Makes the "Yes" button default, this is the default behaviour and + this flag exists solely for symmetry with @c wxNO_DEFAULT. + @style{wxOK_DEFAULT} + Makes the "OK" button default, this is the default behaviour and + this flag exists solely for symmetry with @c wxCANCEL_DEFAULT. + @style{wxICON_NONE} + Displays no icon in the dialog if possible (an icon might still be + displayed if the current platform mandates its use). This style may be + used to prevent the dialog from using the default icon based on @c + wxYES_NO presence as explained in @c wxICON_QUESTION and @c + wxICON_INFORMATION documentation below. + @style{wxICON_EXCLAMATION} + Displays an exclamation, or warning, icon in the dialog. + @style{wxICON_ERROR} + Displays an error icon in the dialog. + @style{wxICON_HAND} + Displays an error symbol, this is a MSW-inspired synonym for @c wxICON_ERROR. + @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 Microsoft + guidelines 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 + explicitly. + @style{wxICON_AUTH_NEEDED} + Displays an authentication needed symbol. This style is only supported + for message dialogs under wxMSW when a task dialog is used to implement + them (i.e. when running under Windows Vista or later). In other cases + the default icon selection logic will be used. Note this can be + combined with other styles to provide a fallback. For instance, using + wxICON_AUTH_NEEDED | wxICON_QUESTION will show a shield symbol on + Windows Vista or above and a question symbol on other platforms. + Available since wxWidgets 2.9.5 + @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. - @a style may be a bit list of the following identifiers: - - @beginStyleTable - @style{wxOK} - Puts an Ok button in the message box. May be combined with @c - wxCANCEL. - @style{wxCANCEL} - 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. - @style{wxNO_DEFAULT} - Makes the "No" button default, can only be used with @c wxYES_NO. - @style{wxCANCEL_DEFAULT} - Makes the "Cancel" button default, can only be used with @c wxCANCEL - @style{wxYES_DEFAULT} - Makes the "Yes" button default, this is the default behaviour and - this flag exists solely for symmetry with @c wxNO_DEFAULT. - @style{wxOK_DEFAULT} - Makes the "OK" button default, this is the default behaviour and - this flag exists solely for symmetry with @c wxCANCEL_DEFAULT. - @style{wxICON_EXCLAMATION} - Displays an exclamation mark symbol. - @style{wxICON_ERROR} - Displays an error symbol. - @style{wxICON_HAND} - Displays an error symbol, this is a MSW-inspired synonym for @c - wxICON_ERROR. - @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. - @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 - explicitly. - @style{wxSTAY_ON_TOP} - Makes the message box stay on top of all other windows (currently - implemented only under MSW). - @endStyleTable + @a style may be a bit list of the identifiers described above. Notice that not all styles are compatible: only one of @c wxOK and @c wxYES_NO may be specified (and one of them must be specified) and at @@ -82,7 +151,7 @@ public: Dialog position (ignored under MSW). */ wxMessageDialog(wxWindow* parent, const wxString& message, - const wxString& caption = "Message box", + const wxString& caption = wxMessageBoxCaptionStr, long style = wxOK | wxCENTRE, const wxPoint& pos = wxDefaultPosition); @@ -94,12 +163,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); @@ -107,6 +193,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); @@ -115,6 +203,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); @@ -122,6 +212,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, @@ -146,9 +238,11 @@ public: Also notice that this function is not currently available on all platforms (although as of wxWidgets 2.9.0 it is implemented in all major ports), so it may return @false to indicate that the labels - couldn't be changed. If it returns @true (currently only under wxMac), - the labels were set successfully. Typically, if the function was used - successfully, the main dialog message may need to be changed, e.g.: + couldn't be changed. If it returns @true, the labels were set + successfully. + + Typically, if the function was used successfully, the main dialog + message may need to be changed, e.g.: @code wxMessageDialog dlg(...); if ( dlg.SetYesNoLabels(_("&Quit"), _("&Don't quit")) ) @@ -156,16 +250,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; + }; @@ -174,7 +285,7 @@ public: // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_dialog */ +/** @addtogroup group_funcmacro_dialog */ //@{ /** @@ -185,9 +296,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 @@ -209,15 +320,16 @@ public: @param style Combination of style flags described in wxMessageDialog documentation. @param x - Horizontal dialog position (ignored under MSW). Use @c wxDefaultCoord + Horizontal dialog position (ignored under MSW). Use ::wxDefaultCoord 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);