// Purpose: interface of wxDialog
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@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).
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}
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();
@see @ref overview_dialog_autoscrolling (for more on layout adaptation)
*/
- bool CanDoLayoutAdapation();
+ virtual bool CanDoLayoutAdaptation();
/**
Centres the dialog box on the display.
*/
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);
/**
@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,
@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
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();
supported.
This function is not available on any other platform.
+
+ @onlyfor{wxmsw}
*/
wxToolBar* GetToolBar() const;
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.
@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
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.
+ The default handler for @c wxEVT_SYS_COLOUR_CHANGED.
@param event
The colour change 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
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().
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();
};
projects / wxWidgets.git / blobdiff