X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b91c4601f2cc8fab375dc49a0a1222d58065cfdb..69358718959f700434643f341bfee8f38b55cbb7:/interface/wx/dialog.h diff --git a/interface/wx/dialog.h b/interface/wx/dialog.h index ce50d802ac..093d0c42ec 100644 --- a/interface/wx/dialog.h +++ b/interface/wx/dialog.h @@ -3,7 +3,7 @@ // Purpose: interface of wxDialog // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -112,7 +112,7 @@ enum wxDialogLayoutAdaptationMode @style{wxDIALOG_EX_CONTEXTHELP} Under Windows, puts a query button on the caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets - will send a wxEVT_HELP event if the user clicked on an application + will send a @c wxEVT_HELP event if the user clicked on an application window. Note that this is an extended style and must be set by calling SetExtraStyle() before Create is called (two-step construction). @@ -125,6 +125,18 @@ enum wxDialogLayoutAdaptationMode managers recognizing the MHM hints should be running for any of these styles to have an effect. + + @beginEventEmissionTable{wxCloseEvent} + @event{EVT_CLOSE(func)} + The dialog is being closed by the user or programmatically (see wxWindow::Close). + The user may generate this event clicking the close button + (typically the 'X' on the top-right of the title bar) if it's present + (see the @c wxCLOSE_BOX style) or by clicking a button with the + @c wxID_CANCEL or @c wxID_OK ids. + @event{EVT_INIT_DIALOG(func)} + Process a @c wxEVT_INIT_DIALOG event. See wxInitDialogEvent. + @endEventTable + @library{wxcore} @category{cmndlg} @@ -167,11 +179,14 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE, - const wxString& name = "dialogBox"); + const wxString& name = wxDialogNameStr); /** - Destructor. Deletes any child windows before deleting the physical - window. + Destructor. + + Deletes any child windows before deleting the physical window. + + See @ref overview_windowdeletion for more info. */ virtual ~wxDialog(); @@ -190,7 +205,7 @@ public: @see @ref overview_dialog_autoscrolling (for more on layout adaptation) */ - bool CanDoLayoutAdapation(); + virtual bool CanDoLayoutAdaptation(); /** Centres the dialog box on the display. @@ -207,7 +222,8 @@ public: */ bool Create(wxWindow* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, long style = 536877056, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE, const wxString& name = wxDialogNameStr); /** @@ -232,9 +248,30 @@ public: @note Just like CreateButtonSizer(), this function may return @NULL if no buttons were created. + + This is a combination of CreateButtonSizer() and + CreateSeparatedSizer(). */ wxSizer* CreateSeparatedButtonSizer(long flags); + /** + Returns the sizer containing the given one with a separating + wxStaticLine if necessarily. + + This function is useful for creating the sizer containing footer-like + contents in dialog boxes. It will add a separating static line only if + it conforms to the current platform convention (currently it is not + added under Mac where the use of static lines for grouping is + discouraged and is added elsewhere). + + @since 2.9.2 + + @param sizer The sizer to wrap, must be non-@NULL. + @return The sizer wrapping the input one or possibly the input sizer + itself if no wrapping is necessary. + */ + wxSizer *CreateSeparatedSizer(wxSizer *sizer); + /** Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, @@ -250,7 +287,7 @@ public: @see @ref overview_dialog_autoscrolling (for more on layout adaptation) */ - bool DoLayoutAdapation(); + virtual bool DoLayoutAdaptation(); /** This function is called when the titlebar OK button is pressed @@ -258,6 +295,8 @@ public: GetAffirmativeId() is sent by default. You can override this function. If the function returns @false, wxWidgets will call Close() for the dialog. + + @onlyfor{wxmsw} */ virtual bool DoOK(); @@ -361,6 +400,8 @@ public: supported. This function is not available on any other platform. + + @onlyfor{wxmsw} */ wxToolBar* GetToolBar() const; @@ -377,7 +418,7 @@ public: Iconize(@false) will bring the window to the front, as does Show(@true). */ - void Iconize(bool iconize); + virtual void Iconize(bool iconize = true); /** Returns @true if the dialog box is iconized. Windows only. @@ -385,7 +426,7 @@ public: @remarks Always returns @false under Windows since dialogs cannot be iconized. */ - bool IsIconized() const; + virtual bool IsIconized() const; /** A static function returning @true if layout adaptation is enabled for @@ -399,9 +440,11 @@ public: Returns @true if @a id is in the array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog. + @onlyfor{wxmsw} + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) */ - bool IsMainButton(wxWindowID& id) const; + bool IsMainButtonId(wxWindowID id) const; /** Returns @true if the dialog box is modal, @false otherwise. @@ -409,7 +452,7 @@ public: virtual bool IsModal() const; /** - The default handler for wxEVT_SYS_COLOUR_CHANGED. + The default handler for @c wxEVT_SYS_COLOUR_CHANGED. @param event The colour change event. @@ -429,7 +472,7 @@ public: Sets the identifier to be used as OK button. When the button with this identifier is pressed, the dialog calls wxWindow::Validate() and wxWindow::TransferDataFromWindow() and, if they both return @true, - closes the dialog with wxID_OK return code. + closes the dialog with the affirmative id return code. Also, when the user presses a hardware OK button on the devices having one or the special OK button in the PocketPC title bar, an event with @@ -551,7 +594,7 @@ public: virtual bool Show(bool show = 1); /** - Shows a modal dialog. + Shows an application-modal dialog. Program flow does not return until the dialog has been dismissed with EndModal(). @@ -561,11 +604,33 @@ public: modeless dialog modal. However ShowModal() can't be called twice without intervening EndModal() calls. + Note that this function creates a temporary event loop which takes + precedence over the application's main event loop (see wxEventLoopBase) + and which is destroyed when the dialog is dismissed. + This also results in a call to wxApp::ProcessPendingEvents(). + @return The value set with SetReturnCode(). - @see EndModal(), GetReturnCode(), SetReturnCode() + @see ShowWindowModal(), EndModal(), GetReturnCode(), SetReturnCode() */ virtual int ShowModal(); + + /** + Shows a dialog modal to the parent top level window only. + + Unlike ShowModal(), dialogs shown with this function only prevent the + user from interacting with their parent frame only but not with the + rest of the application. They also don't block the program execution + but instead return immediately, as Show(), and generate a + wxEVT_WINDOW_MODAL_DIALOG_CLOSED event later when the dialog is closed. + + Currently this function is only fully implemented in wxOSX ports, under + the other platforms it behaves like ShowModal() (but also sends the + above mentioned event). + + @since 2.9.0 + */ + void ShowWindowModal(); };