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