1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: dialog.tex 3%% Purpose: wxDialog documentation 4%% Author: wxWidgets Team 5%% Modified by: 6%% Created: 7%% RCS-ID: $Id: dialog.tex 42921 2006-11-01 20:38:35Z VZ $ 8%% Copyright: (c) wxWidgets Team 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxDialog}}\label{wxdialog} 13 14A dialog box is a window with a title bar and sometimes a system menu, which 15can be moved around the screen. It can contain controls and other windows and 16is often used to allow the user to make some choice or to answer a question. 17 18 19\wxheading{Dialog Buttons} 20 21The dialog usually contains either a single button allowing to close the 22dialog or two buttons, one accepting the changes and the other one discarding 23them (such button, if present, is automatically activated if the user presses 24the \texttt{"Esc"} key). By default, buttons with the standard \texttt{wxID\_OK} 25and \texttt{wxID\_CANCEL} identifiers behave as expected. Starting with 26wxWidgets 2.7 it is also possible to use a button with a different identifier 27instead, see \helpref{SetAffirmativeId}{wxdialogsetaffirmativeid} and 28\helpref{SetEscapeId}{wxdialogsetescapeid}. 29 30Also notice that the \helpref{CreateButtonSizer()}{wxdialogcreatebuttonsizer} 31should be used to create the buttons appropriate for the current platform and 32positioned correctly (including their order which is platform-dependent). 33 34 35 36\wxheading{Derived from} 37 38\helpref{wxTopLevelWindow}{wxtoplevelwindow}\\ 39\helpref{wxWindow}{wxwindow}\\ 40\helpref{wxEvtHandler}{wxevthandler}\\ 41\helpref{wxObject}{wxobject} 42 43\wxheading{Include files} 44 45<wx/dialog.h> 46 47\wxheading{Modal and modeless dialogs} 48 49There are two kinds of dialog -- {\it modal}\ and {\it modeless}. A modal dialog 50blocks program flow and user input on other windows until it is dismissed, 51whereas a modeless dialog behaves more like a frame in that program flow 52continues, and input in other windows is still possible. To show a modal dialog 53you should use the \helpref{ShowModal}{wxdialogshowmodal} method while to show 54a dialog modelessly you simply use \helpref{Show}{wxdialogshow}, just as with 55frames. 56 57Note that the modal dialog is one of the very few examples of 58wxWindow-derived objects which may be created on the stack and not on the heap. 59In other words, although this code snippet: 60 61\begin{verbatim} 62 void AskUser() 63 { 64 MyAskDialog *dlg = new MyAskDialog(...); 65 if ( dlg->ShowModal() == wxID_OK ) 66 ... 67 //else: dialog was cancelled or some another button pressed 68 69 dlg->Destroy(); 70 } 71\end{verbatim} 72 73works, you can also achieve the same result by using a simpler code fragment 74below: 75 76\begin{verbatim} 77 void AskUser() 78 { 79 MyAskDialog dlg(...); 80 if ( dlg.ShowModal() == wxID_OK ) 81 ... 82 83 // no need to call Destroy() here 84 } 85\end{verbatim} 86 87An application can define a \helpref{wxCloseEvent}{wxcloseevent} handler for 88the dialog to respond to system close events. 89 90\wxheading{Window styles} 91 92\twocolwidtha{5cm} 93\begin{twocollist}\itemsep=0pt 94\twocolitem{\windowstyle{wxCAPTION}}{Puts a caption on the dialog box.} 95\twocolitem{\windowstyle{wxDEFAULT\_DIALOG\_STYLE}}{Equivalent to a combination of wxCAPTION, wxCLOSE\_BOX and wxSYSTEM\_MENU (the last one is not used under Unix)} 96\twocolitem{\windowstyle{wxRESIZE\_BORDER}}{Display a resizeable frame around the window.} 97\twocolitem{\windowstyle{wxSYSTEM\_MENU}}{Display a system menu.} 98\twocolitem{\windowstyle{wxCLOSE\_BOX}}{Displays a close box on the frame.} 99\twocolitem{\windowstyle{wxMAXIMIZE\_BOX}}{Displays a maximize box on the dialog.} 100\twocolitem{\windowstyle{wxMINIMIZE\_BOX}}{Displays a minimize box on the dialog.} 101\twocolitem{\windowstyle{wxTHICK\_FRAME}}{Display a thick frame around the window.} 102\twocolitem{\windowstyle{wxSTAY\_ON\_TOP}}{The dialog stays on top of all other windows.} 103\twocolitem{\windowstyle{wxNO\_3D}}{Under Windows, specifies that the child controls 104should not have 3D borders unless specified in the control.} 105\twocolitem{\windowstyle{wxDIALOG\_NO\_PARENT}}{By default, a dialog created 106with a {\tt NULL} parent window will be given the 107\helpref{application's top level window}{wxappgettopwindow} as parent. Use this 108style to prevent this from happening and create an orphan dialog. This is not recommended for modal dialogs.} 109\twocolitem{\windowstyle{wxDIALOG\_EX\_CONTEXTHELP}}{Under Windows, puts a query button on the 110caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets will send 111a wxEVT\_HELP event if the user clicked on an application window. {\it Note}\ that this is an extended 112style and must be set by calling \helpref{SetExtraStyle}{wxwindowsetextrastyle} before Create is called (two-step construction).} 113\twocolitem{\windowstyle{wxDIALOG\_EX\_METAL}}{On Mac OS X, frames with this style will be shown with a metallic look. This is an {\it extra} style.} 114\end{twocollist} 115 116Under Unix or Linux, MWM (the Motif Window Manager) or other window managers 117recognizing the MHM hints should be running for any of these styles to have an 118effect. 119 120See also \helpref{Generic window styles}{windowstyles}. 121 122\wxheading{See also} 123 124\helpref{wxDialog overview}{wxdialogoverview}, \helpref{wxFrame}{wxframe},\rtfsp 125\helpref{Validator overview}{validatoroverview} 126 127\latexignore{\rtfignore{\wxheading{Members}}} 128 129 130\membersection{wxDialog::wxDialog}\label{wxdialogctor} 131 132\func{}{wxDialog}{\void} 133 134Default constructor. 135 136\func{}{wxDialog}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp 137\param{const wxString\& }{title},\rtfsp 138\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp 139\param{const wxSize\& }{size = wxDefaultSize},\rtfsp 140\param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp 141\param{const wxString\& }{name = ``dialogBox"}} 142 143Constructor. 144 145\wxheading{Parameters} 146 147\docparam{parent}{Can be NULL, a frame or another dialog box.} 148 149\docparam{id}{An identifier for the dialog. A value of -1 is taken to mean a default.} 150 151\docparam{title}{The title of the dialog.} 152 153\docparam{pos}{The dialog position. A value of (-1, -1) indicates a default position, chosen by 154either the windowing system or wxWidgets, depending on platform.} 155 156\docparam{size}{The dialog size. A value of (-1, -1) indicates a default size, chosen by 157either the windowing system or wxWidgets, depending on platform.} 158 159\docparam{style}{The window style. See \helpref{wxDialog}{wxdialog}.} 160 161\docparam{name}{Used to associate a name with the window, 162allowing the application user to set Motif resource values for 163individual dialog boxes.} 164 165\wxheading{See also} 166 167\helpref{wxDialog::Create}{wxdialogcreate} 168 169 170\membersection{wxDialog::\destruct{wxDialog}}\label{wxdialogdtor} 171 172\func{}{\destruct{wxDialog}}{\void} 173 174Destructor. Deletes any child windows before deleting the physical window. 175 176 177\membersection{wxDialog::Centre}\label{wxdialogcentre} 178 179\func{void}{Centre}{\param{int}{ direction = wxBOTH}} 180 181Centres the dialog box on the display. 182 183\wxheading{Parameters} 184 185\docparam{direction}{May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL} or {\tt wxBOTH}.} 186 187 188\membersection{wxDialog::Create}\label{wxdialogcreate} 189 190\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp 191\param{const wxString\& }{title},\rtfsp 192\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp 193\param{const wxSize\& }{size = wxDefaultSize},\rtfsp 194\param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp 195\param{const wxString\& }{name = ``dialogBox"}} 196 197Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogctor}\rtfsp 198for details. 199 200 201\membersection{wxDialog::CreateButtonSizer}\label{wxdialogcreatebuttonsizer} 202 203\func{wxSizer*}{CreateButtonSizer}{\param{long}{ flags}} 204 205Creates a sizer with standard buttons. {\it flags} is a bit list 206of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO\_DEFAULT. 207 208The sizer lays out the buttons in a manner appropriate to the platform. 209 210This function uses \helpref{CreateStdDialogButtonSizer}{wxdialogcreatestddialogbuttonsizer} 211internally for most platforms but doesn't create the sizer at all for the 212platforms with hardware buttons (such as smartphones) for which it sets up the 213hardware buttons appropriately and returns \NULL, so don't forget to test that 214the return value is valid before using it. 215 216 217\membersection{wxDialog::CreateSeparatedButtonSizer}\label{wxdialogcreateseparatedbuttonsizer} 218 219\func{wxSizer*}{CreateSeparatedButtonSizer}{\param{long}{ flags}} 220 221Creates a sizer with standard buttons using 222\helpref{CreateButtonSizer}{wxdialogcreatebuttonsizer} separated from the rest 223of the dialog contents by a horizontal \helpref{wxStaticLine}{wxstaticline}. 224 225Please notice that just like CreateButtonSizer() this function may return \NULL 226if no buttons were created. 227 228 229\membersection{wxDialog::CreateStdDialogButtonSizer}\label{wxdialogcreatestddialogbuttonsizer} 230 231\func{wxStdDialogButtonSizer*}{CreateStdDialogButtonSizer}{\param{long}{ flags}} 232 233Creates a \helpref{wxStdDialogButtonSizer}{wxstddialogbuttonsizer} with standard buttons. {\it flags} is a bit list 234of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO\_DEFAULT. 235 236The sizer lays out the buttons in a manner appropriate to the platform. 237 238 239\membersection{wxDialog::DoOK}\label{wxdialogdook} 240 241\func{virtual bool}{DoOK}{\void} 242 243This function is called when the titlebar OK button is pressed (PocketPC only). 244A command event for the identifier returned by GetAffirmativeId is sent by 245default. You can override this function. If the function returns false, wxWidgets 246will call Close() for the dialog. 247 248 249\membersection{wxDialog::EndModal}\label{wxdialogendmodal} 250 251\func{void}{EndModal}{\param{int }{retCode}} 252 253Ends a modal dialog, passing a value to be returned from the \helpref{wxDialog::ShowModal}{wxdialogshowmodal}\rtfsp 254invocation. 255 256\wxheading{Parameters} 257 258\docparam{retCode}{The value that should be returned by {\bf ShowModal}.} 259 260\wxheading{See also} 261 262\helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp 263\helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp 264\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode} 265 266 267\membersection{wxDialog::GetAffirmativeId}\label{wxdialoggetaffirmativeid} 268 269\constfunc{int}{GetAffirmativeId}{\void} 270 271Gets the identifier of the button which works like standard OK button in this 272dialog. 273 274\wxheading{See also} 275 276\helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid} 277 278 279\membersection{wxDialog::GetEscapeId}\label{wxdialoggetescapeid} 280 281\constfunc{int}{GetEscapeId}{\void} 282 283Gets the identifier of the button to map presses of \texttt{\textsc{ESC}} 284button to. 285 286\wxheading{See also} 287 288\helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid} 289 290 291\membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode} 292 293\func{int}{GetReturnCode}{\void} 294 295Gets the return code for this window. 296 297\wxheading{Remarks} 298 299A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns 300a code to the application. 301 302\wxheading{See also} 303 304\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp 305\helpref{wxDialog::EndModal}{wxdialogendmodal} 306 307 308\membersection{wxDialog::GetToolBar}\label{wxdialoggettoolbar} 309 310\constfunc{wxToolBar*}{GetToolBar}{\void} 311 312On PocketPC, a dialog is automatically provided with an empty toolbar. GetToolBar 313allows you to access the toolbar and add tools to it. Removing tools and adding 314arbitrary controls are not currently supported. 315 316This function is not available on any other platform. 317 318 319\membersection{wxDialog::Iconize}\label{wxdialogiconized} 320 321\func{void}{Iconize}{\param{const bool}{ iconize}} 322 323Iconizes or restores the dialog. Windows only. 324 325\wxheading{Parameters} 326 327\docparam{iconize}{If true, iconizes the dialog box; if false, shows and restores it.} 328 329\wxheading{Remarks} 330 331Note that in Windows, iconization has no effect since dialog boxes cannot be 332iconized. However, applications may need to explicitly restore dialog 333boxes under Motif which have user-iconizable frames, and under Windows 334calling {\tt Iconize(false)} will bring the window to the front, as does 335\rtfsp{\tt Show(true)}. 336 337 338\membersection{wxDialog::IsIconized}\label{wxdialogisiconized} 339 340\constfunc{bool}{IsIconized}{\void} 341 342Returns true if the dialog box is iconized. Windows only. 343 344\wxheading{Remarks} 345 346Always returns false under Windows since dialogs cannot be iconized. 347 348 349\membersection{wxDialog::IsModal}\label{wxdialogismodal} 350 351\constfunc{bool}{IsModal}{\void} 352 353Returns true if the dialog box is modal, false otherwise. 354 355 356 357\membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged} 358 359\func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}} 360 361The default handler for wxEVT\_SYS\_COLOUR\_CHANGED. 362 363\wxheading{Parameters} 364 365\docparam{event}{The colour change event.} 366 367\wxheading{Remarks} 368 369Changes the dialog's colour to conform to the current settings (Windows only). 370Add an event table entry for your dialog class if you wish the behaviour 371to be different (such as keeping a user-defined 372background colour). If you do override this function, call wxEvent::Skip to 373propagate the notification to child windows and controls. 374 375\wxheading{See also} 376 377\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent} 378 379 380\membersection{wxDialog::SetAffirmativeId}\label{wxdialogsetaffirmativeid} 381 382\func{void}{SetAffirmativeId}{\param{int }{id}} 383 384Sets the identifier to be used as OK button. When the button with this 385identifier is pressed, the dialog calls \helpref{Validate}{wxwindowvalidate} 386and \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow} 387and, if they both return \true, closes the dialog with \texttt{wxID\_OK} return 388code. 389 390Also, when the user presses a hardware OK button on the devices having one or 391the special OK button in the PocketPC title bar, an event with this id is 392generated. 393 394By default, the affirmative id is wxID\_OK. 395 396\wxheading{See also} 397 398\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid}, \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid} 399 400 401\membersection{wxDialog::SetEscapeId}\label{wxdialogsetescapeid} 402 403\func{void}{SetEscapeId}{\param{int }{id}} 404 405Sets the identifier of the button which should work like the standard 406\texttt{\textsc{Cancel}} button in this dialog. When the button with this id is 407clicked, the dialog is closed. Also, when the user presses \texttt{\textsc{ESC}} 408key in the dialog or closes the dialog using the close button in the title bar, 409this is mapped to the click of the button with the specified id. 410 411By default, the escape id is the special value \texttt{wxID\_ANY} meaning that 412\texttt{wxID\_CANCEL} button is used if it's present in the dialog and 413otherwise the button with \helpref{GetAffirmativeId()}{wxdialoggetaffirmativeid} 414is used. Another special value for \arg{id} is \texttt{wxID\_NONE} meaning that 415\texttt{\textsc{ESC}} presses should be ignored. If any other value is given, it 416is interpreted as the id of the button to map the escape key to. 417 418 419\membersection{wxDialog::SetIcon}\label{wxdialogseticon} 420 421\func{void}{SetIcon}{\param{const wxIcon\& }{icon}} 422 423Sets the icon for this dialog. 424 425\wxheading{Parameters} 426 427\docparam{icon}{The icon to associate with this dialog.} 428 429See also \helpref{wxIcon}{wxicon}. 430 431 432\membersection{wxDialog::SetIcons}\label{wxdialogseticons} 433 434\func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}} 435 436Sets the icons for this dialog. 437 438\wxheading{Parameters} 439 440\docparam{icons}{The icons to associate with this dialog.} 441 442See also \helpref{wxIconBundle}{wxiconbundle}. 443 444 445\membersection{wxDialog::SetModal}\label{wxdialogsetmodal} 446 447\func{void}{SetModal}{\param{const bool}{ flag}} 448 449{\bf NB:} This function is deprecated and doesn't work for all ports, just use 450\helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead. 451 452Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control 453until the dialog is hidden) or modeless (control returns immediately). 454 455\wxheading{Parameters} 456 457\docparam{flag}{If true, the dialog will be modal, otherwise it will be modeless.} 458 459 460\membersection{wxDialog::SetReturnCode}\label{wxdialogsetreturncode} 461 462\func{void}{SetReturnCode}{\param{int }{retCode}} 463 464Sets the return code for this window. 465 466\wxheading{Parameters} 467 468\docparam{retCode}{The integer return code, usually a control identifier.} 469 470\wxheading{Remarks} 471 472A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns 473a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogendmodal} calls {\bf SetReturnCode}. 474 475\wxheading{See also} 476 477\helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp 478\helpref{wxDialog::EndModal}{wxdialogendmodal} 479 480 481\membersection{wxDialog::Show}\label{wxdialogshow} 482 483\func{bool}{Show}{\param{const bool}{ show}} 484 485Hides or shows the dialog. 486 487\wxheading{Parameters} 488 489\docparam{show}{If true, the dialog box is shown and brought to the front; 490otherwise the box is hidden. If false and the dialog is 491modal, control is returned to the calling program.} 492 493\wxheading{Remarks} 494 495The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}. 496 497 498\membersection{wxDialog::ShowModal}\label{wxdialogshowmodal} 499 500\func{int}{ShowModal}{\void} 501 502Shows a modal dialog. Program flow does not return until the dialog has been dismissed with\rtfsp 503\helpref{wxDialog::EndModal}{wxdialogendmodal}. 504 505\wxheading{Return value} 506 507The return value is the value set with \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}. 508 509\wxheading{See also} 510 511\helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp 512\helpref{wxDialog:GetReturnCode}{wxdialoggetreturncode},\rtfsp 513\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode} 514 515