X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/adaaa68635b4c8a4d8c5284add40366ea3eefb07..d6cf9064d4e7e342e99f368c38f9affc63c9bceb:/interface/wx/dialog.h diff --git a/interface/wx/dialog.h b/interface/wx/dialog.h index c76d05b3bc..736b97488d 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 ///////////////////////////////////////////////////////////////////////////// /** @@ -16,6 +16,8 @@ enum wxDialogLayoutAdaptationMode wxDIALOG_ADAPTATION_MODE_DISABLED = 2 ///< Disable this dialog overriding global status. }; +#define wxDEFAULT_DIALOG_STYLE (wxCAPTION | wxSYSTEM_MENU | wxCLOSE_BOX) + /** @class wxDialog @@ -88,7 +90,7 @@ enum wxDialogLayoutAdaptationMode Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and wxSYSTEM_MENU (the last one is not used under Unix). @style{wxRESIZE_BORDER} - Display a resizeable frame around the window. + Display a resizable frame around the window. @style{wxSYSTEM_MENU} Display a system menu. @style{wxCLOSE_BOX} @@ -102,8 +104,8 @@ enum wxDialogLayoutAdaptationMode @style{wxSTAY_ON_TOP} The dialog stays on top of all other windows. @style{wxNO_3D} - Under Windows, specifies that the child controls should not have 3D - borders unless specified in the control. + This style is obsolete and doesn't do anything any more, don't use + it in any new code. @style{wxDIALOG_NO_PARENT} By default, a dialog created with a @NULL parent window will be given the @ref wxApp::GetTopWindow() "application's top level window" @@ -112,7 +114,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 +127,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 +181,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 +207,7 @@ public: @see @ref overview_dialog_autoscrolling (for more on layout adaptation) */ - bool CanDoLayoutAdapation(); + virtual bool CanDoLayoutAdaptation(); /** Centres the dialog box on the display. @@ -209,7 +226,7 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE, - const wxString& name = "dialogBox"); + const wxString& name = wxDialogNameStr); /** Creates a sizer with standard buttons. @a flags is a bit list of the @@ -233,9 +250,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, @@ -245,13 +283,19 @@ public: */ wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags); + /** + Splits text up at newlines and places the lines into wxStaticText + objects in a vertical wxBoxSizer. + */ + wxSizer *CreateTextSizer( const wxString& message ); + /** Performs layout adaptation, usually if the dialog is too large to fit on the display. @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 @@ -259,6 +303,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(); @@ -343,7 +389,7 @@ public: @see @ref overview_dialog_autoscrolling (for more on layout adaptation) */ - wxArrayInt GetMainButtonIds(); + wxArrayInt& GetMainButtonIds(); /** Gets the return code for this window. @@ -362,6 +408,8 @@ public: supported. This function is not available on any other platform. + + @onlyfor{wxmsw} */ wxToolBar* GetToolBar() const; @@ -378,7 +426,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. @@ -386,7 +434,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 @@ -400,37 +448,22 @@ 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. */ virtual bool IsModal() const; - /** - The default handler for wxEVT_SYS_COLOUR_CHANGED. - - @param event - The colour change event. - - @remarks Changes the dialog's colour to conform to the current settings - (Windows only). Add an event table entry for your dialog class - if you wish the behaviour to be different (such as keeping a - user-defined background colour). If you do override this - function, call wxEvent::Skip() to propagate the notification - to child windows and controls. - - @see wxSysColourChangedEvent - */ - void OnSysColourChanged(wxSysColourChangedEvent& event); - /** 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 @@ -549,10 +582,10 @@ public: otherwise the box is hidden. If @false and the dialog is modal, control is returned to the calling program. */ - bool Show(bool show); + 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(). @@ -562,11 +595,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(); }; @@ -574,7 +629,7 @@ public: /** @class wxDialogLayoutAdapter - This abstract class is the base for classes that help wxWidgets peform + This abstract class is the base for classes that help wxWidgets perform run-time layout adaptation of dialogs. Principally, this is to cater for small displays by making part of the dialog scroll, but the application developer may find other uses for layout adaption. @@ -599,13 +654,23 @@ public: /** Override this to returns @true if adaptation can and should be done. */ - bool CanDoLayoutAdaptation(wxDialog* dialog); + virtual bool CanDoLayoutAdaptation(wxDialog* dialog) = 0; /** Override this to perform layout adaptation, such as making parts of the dialog scroll and resizing the dialog to fit the display. Normally this function will be called just before the dialog is shown. */ - bool DoLayoutAdaptation(wxDialog* dialog); + virtual bool DoLayoutAdaptation(wxDialog* dialog) = 0; }; + +class wxWindowModalDialogEvent : public wxCommandEvent +{ +public: + wxWindowModalDialogEvent (wxEventType commandType = wxEVT_NULL, int id = 0); + + wxDialog *GetDialog() const; + int GetReturnCode() const; + virtual wxEvent *Clone() const; +};