docs/latex/wx/dialog.tex

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