.\" This is a wxWidgets manpage page generated from the XML docs .TH wxDialog 3wx 2005-02-15 "wxWidgets" "wxWidgets class documentation" .SH NAME wxDialog \- Base class for common dialogs .SH DESCRIPTION A dialog box is a window with a title bar and sometimes a system menu, which can be moved around the screen. It can contain controls and other windows and is usually used to allow the user to make some choice or to answer a question. .SH REMARKS There are two kinds of dialog -- modal and modeless . A modal dialog blocks program flow and user input on other windows until it is dismissed, whereas a modeless dialog behaves more like a frame in that program flow continues, and input in other windows is still possible. To show a modal dialog you should use the ShowModal method while to show a dialog modelessly you simply use Show , just as with frames. Note that the modal dialog is one of the very few examples of wxWindow-derived objects which may be created on the stack and not on the heap. In other words, although this code snippet: void AskUser() { MyAskDialog *dlg = new MyAskDialog(...); if ( dlg->ShowModal() == wxID_OK ) ... //else: dialog was cancelled or some another button pressed dlg->Destroy(); } works, you can also achieve the same result by using a simpler code fragment below: void AskUser() { MyAskDialog dlg(...); if ( dlg.ShowModal() == wxID_OK ) ... // no need to call Destroy() here } An application can define a wxCloseEvent handler for the dialog to respond to system close events. .SH "PARENTS" wxTopLevelWindow wxWindow wxEvtHandler wxObject .SH "INCLUDE FILES" wx/dialog.h .SH MEMBERS .SS wxDialog () Default constructor. .SS wxDialog (wxWindow* parentwxWindowID idconst wxString& titleconst wxPoint& pos = wxDefaultPositionconst wxSize& size = wxDefaultSizelong style = wxDEFAULT_DIALOG_STYLEconst wxString& name = ``dialogBox") Constructor. .SS ~wxDialog () Destructor. Deletes any child windows before deleting the physical window. .SS void Centre (int direction = wxBOTH) Centres the dialog box on the display. .SS bool Create (wxWindow* parentwxWindowID idconst wxString& titleconst wxPoint& pos = wxDefaultPositionconst wxSize& size = wxDefaultSizelong style = wxDEFAULT_DIALOG_STYLEconst wxString& name = ``dialogBox") Used for two-step dialog box construction. See wxDialog::wxDialog for details. .SS wxSizer* CreateButtonSizer (long flags) Creates a sizer with standard buttons. flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO_DEFAULT. The sizer lays out the buttons in a manner appropriate to the platform. This function simply calls CreateStdDialogButtonSizer . .SS wxStdDialogButtonSizer* CreateStdDialogButtonSizer (long flags) Creates a wxStdDialogButtonSizer with standard buttons. flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO_DEFAULT. The sizer lays out the buttons in a manner appropriate to the platform. .SS virtual bool DoOK () This function is called when the titlebar OK button is pressed (PocketPC only). A command event for the identifier returned by GetAffirmativeId is sent by default. You can override this function. If the function returns false, wxWidgets will call Close() for the dialog. .SS void EndModal (int retCode) Ends a modal dialog, passing a value to be returned from the wxDialog::ShowModal invocation. .SS int GetAffirmativeId () Gets the identifier to be used when the user presses an OK button in a PocketPC titlebar. .SS int GetEscapeId () Gets the identifier of the button to map presses of \textsc{ESC button to. .SS int GetReturnCode () .SS wxString GetTitle () Returns the title of the dialog box. .SS wxToolBar* GetToolBar () On PocketPC, a dialog is automatically provided with an empty toolbar. GetToolBar allows you to access the toolbar and add tools to it. Removing tools and adding arbitrary controls are not currently supported. This function is not available on any other platform. .SS void Iconize (const bool iconize) Iconizes or restores the dialog. Windows only. .SS bool IsIconized () Returns true if the dialog box is iconized. Windows only. .SS bool IsModal () Returns true if the dialog box is modal, false otherwise. .SS void OnApply (wxCommandEvent& event) .SS void OnCancel (wxCommandEvent& event) .SS void OnOK (wxCommandEvent& event) .SS void OnSysColourChanged (wxSysColourChangedEvent& event) The default handler for wxEVT_SYS_COLOUR_CHANGED. .SS void SetAffirmativeId (int id) Sets the identifier to be used when the user presses an OK button in a PocketPC titlebar. By default, this is wxID_OK. .SS void SetEscapeId (int id) Sets the identifier to be used when the user presses \textsc{ESC button in the dialog. By default, this is wxID_ANY meaning that the first suitable button is used: if there a wxID_CANCEL button, it is activated, otherwise wxID_OK button is activated if present. Another possible special value for id is wxID_NONE meaning that \textsc{ESC presses should be ignored. If another value is given, it is interpreted as the id of the button to map the escape key to. .SS void SetIcon (const wxIcon& icon) Sets the icon for this dialog. See also wxIcon . .SS void SetIcons (const wxIconBundle& icons) Sets the icons for this dialog. See also wxIconBundle . .SS void SetModal (const bool flag) NB: This function is deprecated and doesn't work for all ports, just use ShowModal to show a modal dialog instead. Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control until the dialog is hidden) or modeless (control returns immediately). .SS void SetReturnCode (int retCode) .SS void SetTitle (const wxString& title) Sets the title of the dialog box. .SS bool Show (const bool show) Hides or shows the dialog. .SS int ShowModal () Shows a modal dialog. Program flow does not return until the dialog has been dismissed with wxDialog::EndModal . .SH "WINDOW STYLES" .SS wxCAPTION Puts a caption on the dialog box. .SS wxDEFAULT_DIALOG_STYLE Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and wxSYSTEM_MENU (the last one is not used under Unix) .SS wxRESIZE_BORDER Display a resizeable frame around the window. .SS wxSYSTEM_MENU Display a system menu. .SS wxCLOSE_BOX Displays a close box on the frame. .SS wxMAXIMIZE_BOX Displays a maximize box on the dialog. .SS wxMINIMIZE_BOX Displays a minimize box on the dialog. .SS wxTHICK_FRAME Display a thick frame around the window. .SS wxSTAY_ON_TOP The dialog stays on top of all other windows. .SS wxNO_3D wxNO_3D .SS wxDIALOG_NO_PARENT wxDIALOG_NO_PARENT .SS wxDIALOG_EX_CONTEXTHELP wxDIALOG_EX_CONTEXTHELP .SS wxDIALOG_EX_METAL On Mac OS X, frames with this style will be shown with a metallic look. This is an extra style. .SH "SEE ALSO" wxTopLevelWindow wxWindow wxEvtHandler wxObject wxDialog overview wxFrame , Validator overview .SH "AUTHORS" Documentation content by Julian Smart, Robert Roebling, Vadim Zeitlin, Robin Dunn, et al Conversion to manpage format by Arnout Engelen (http://bzzt.net), bugreports welcome.