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{Modal and modeless dialogs}
  48
  49 There are two kinds of dialog -- {\it modal}\ and {\it modeless}. A modal dialog
  50 blocks program flow and user input on other windows until it is dismissed,
  51 whereas a modeless dialog behaves more like a frame in that program flow
  52 continues, and input in other windows is still possible. To show a modal dialog
  53 you should use the \helpref{ShowModal}{wxdialogshowmodal} method while to show
  54 a dialog modelessly you simply use \helpref{Show}{wxdialogshow}, just as with
  55 frames.
  56
  57 Note that the modal dialog is one of the very few examples of
  58 wxWindow-derived objects which may be created on the stack and not on the heap.
  59 In 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
  73 works, you can also achieve the same result by using a simpler code fragment
  74 below:
  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
  87 An application can define a \helpref{wxCloseEvent}{wxcloseevent} handler for
  88 the 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
 104 should not have 3D borders unless specified in the control.}
 105 \twocolitem{\windowstyle{wxDIALOG\_NO\_PARENT}}{By default, a dialog created
 106 with a {\tt NULL} parent window will be given the
 107 \helpref{application's top level window}{wxappgettopwindow} as parent. Use this
 108 style 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
 110 caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets will send
 111 a wxEVT\_HELP event if the user clicked on an application window. {\it Note}\ that this is an extended
 112 style 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
 116 Under Unix or Linux, MWM (the Motif Window Manager) or other window managers
 117 recognizing the MHM hints should be running for any of these styles to have an
 118 effect.
 119
 120 See 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
 134 Default 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
 143 Constructor.
 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
 154 either 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
 157 either 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,
 162 allowing the application user to set Motif resource values for
 163 individual 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
 174 Destructor. 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
 181 Centres 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
 197 Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogctor}\rtfsp
 198 for details.
 199
 200
 201 \membersection{wxDialog::CreateButtonSizer}\label{wxdialogcreatebuttonsizer}
 202
 203 \func{wxSizer*}{CreateButtonSizer}{\param{long}{ flags}}
 204
 205 Creates a sizer with standard buttons. {\it flags} is a bit list
 206 of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE,
 207 wxHELP, wxNO\_DEFAULT.
 208
 209 The sizer lays out the buttons in a manner appropriate to the platform.
 210
 211 This function uses \helpref{CreateStdDialogButtonSizer}{wxdialogcreatestddialogbuttonsizer}
 212 internally for most platforms but doesn't create the sizer at all for the
 213 platforms with hardware buttons (such as smartphones) for which it sets up the
 214 hardware buttons appropriately and returns \NULL, so don't forget to test that
 215 the return value is valid before using it.
 216
 217
 218 \membersection{wxDialog::CreateSeparatedButtonSizer}\label{wxdialogcreateseparatedbuttonsizer}
 219
 220 \func{wxSizer*}{CreateSeparatedButtonSizer}{\param{long}{ flags}}
 221
 222 Creates a sizer with standard buttons using
 223 \helpref{CreateButtonSizer}{wxdialogcreatebuttonsizer} separated from the rest
 224 of the dialog contents by a horizontal \helpref{wxStaticLine}{wxstaticline}.
 225
 226 Please notice that just like CreateButtonSizer() this function may return \NULL
 227 if no buttons were created.
 228
 229
 230 \membersection{wxDialog::CreateStdDialogButtonSizer}\label{wxdialogcreatestddialogbuttonsizer}
 231
 232 \func{wxStdDialogButtonSizer*}{CreateStdDialogButtonSizer}{\param{long}{ flags}}
 233
 234 Creates a \helpref{wxStdDialogButtonSizer}{wxstddialogbuttonsizer} with standard buttons. {\it flags} is a bit list
 235 of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE,
 236 wxHELP, wxNO\_DEFAULT.
 237
 238 The sizer lays out the buttons in a manner appropriate to the platform.
 239
 240
 241 \membersection{wxDialog::DoOK}\label{wxdialogdook}
 242
 243 \func{virtual bool}{DoOK}{\void}
 244
 245 This function is called when the titlebar OK button is pressed (PocketPC only).
 246 A command event for the identifier returned by GetAffirmativeId is sent by
 247 default. You can override this function. If the function returns false, wxWidgets
 248 will call Close() for the dialog.
 249
 250
 251 \membersection{wxDialog::EndModal}\label{wxdialogendmodal}
 252
 253 \func{void}{EndModal}{\param{int }{retCode}}
 254
 255 Ends a modal dialog, passing a value to be returned from the \helpref{wxDialog::ShowModal}{wxdialogshowmodal}\rtfsp
 256 invocation.
 257
 258 \wxheading{Parameters}
 259
 260 \docparam{retCode}{The value that should be returned by {\bf ShowModal}.}
 261
 262 \wxheading{See also}
 263
 264 \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 265 \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp
 266 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
 267
 268
 269 \membersection{wxDialog::GetAffirmativeId}\label{wxdialoggetaffirmativeid}
 270
 271 \constfunc{int}{GetAffirmativeId}{\void}
 272
 273 Gets the identifier of the button which works like standard OK button in this
 274 dialog.
 275
 276 \wxheading{See also}
 277
 278 \helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid}
 279
 280
 281 \membersection{wxDialog::GetEscapeId}\label{wxdialoggetescapeid}
 282
 283 \constfunc{int}{GetEscapeId}{\void}
 284
 285 Gets the identifier of the button to map presses of \texttt{\textsc{ESC}}
 286 button to.
 287
 288 \wxheading{See also}
 289
 290 \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid}
 291
 292
 293 \membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode}
 294
 295 \func{int}{GetReturnCode}{\void}
 296
 297 Gets the return code for this window.
 298
 299 \wxheading{Remarks}
 300
 301 A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
 302 a code to the application.
 303
 304 \wxheading{See also}
 305
 306 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 307 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 308
 309
 310 \membersection{wxDialog::GetToolBar}\label{wxdialoggettoolbar}
 311
 312 \constfunc{wxToolBar*}{GetToolBar}{\void}
 313
 314 On PocketPC, a dialog is automatically provided with an empty toolbar. GetToolBar
 315 allows you to access the toolbar and add tools to it. Removing tools and adding
 316 arbitrary controls are not currently supported.
 317
 318 This function is not available on any other platform.
 319
 320
 321 \membersection{wxDialog::Iconize}\label{wxdialogiconized}
 322
 323 \func{void}{Iconize}{\param{bool}{ iconize}}
 324
 325 Iconizes or restores the dialog. Windows only.
 326
 327 \wxheading{Parameters}
 328
 329 \docparam{iconize}{If true, iconizes the dialog box; if false, shows and restores it.}
 330
 331 \wxheading{Remarks}
 332
 333 Note that in Windows, iconization has no effect since dialog boxes cannot be
 334 iconized. However, applications may need to explicitly restore dialog
 335 boxes under Motif which have user-iconizable frames, and under Windows
 336 calling {\tt Iconize(false)} will bring the window to the front, as does
 337 \rtfsp{\tt Show(true)}.
 338
 339
 340 \membersection{wxDialog::IsIconized}\label{wxdialogisiconized}
 341
 342 \constfunc{bool}{IsIconized}{\void}
 343
 344 Returns true if the dialog box is iconized. Windows only.
 345
 346 \wxheading{Remarks}
 347
 348 Always returns false under Windows since dialogs cannot be iconized.
 349
 350
 351 \membersection{wxDialog::IsModal}\label{wxdialogismodal}
 352
 353 \constfunc{bool}{IsModal}{\void}
 354
 355 Returns true if the dialog box is modal, false otherwise.
 356
 357
 358
 359 \membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged}
 360
 361 \func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}}
 362
 363 The default handler for wxEVT\_SYS\_COLOUR\_CHANGED.
 364
 365 \wxheading{Parameters}
 366
 367 \docparam{event}{The colour change event.}
 368
 369 \wxheading{Remarks}
 370
 371 Changes the dialog's colour to conform to the current settings (Windows only).
 372 Add an event table entry for your dialog class if you wish the behaviour
 373 to be different (such as keeping a user-defined
 374 background colour). If you do override this function, call wxEvent::Skip to
 375 propagate the notification to child windows and controls.
 376
 377 \wxheading{See also}
 378
 379 \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}
 380
 381
 382 \membersection{wxDialog::SetAffirmativeId}\label{wxdialogsetaffirmativeid}
 383
 384 \func{void}{SetAffirmativeId}{\param{int }{id}}
 385
 386 Sets the identifier to be used as OK button. When the button with this
 387 identifier is pressed, the dialog calls \helpref{Validate}{wxwindowvalidate}
 388 and \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}
 389 and, if they both return \true, closes the dialog with \texttt{wxID\_OK} return
 390 code.
 391
 392 Also, when the user presses a hardware OK button on the devices having one or
 393 the special OK button in the PocketPC title bar, an event with this id is
 394 generated.
 395
 396 By default, the affirmative id is wxID\_OK.
 397
 398 \wxheading{See also}
 399
 400 \helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid}, \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid}
 401
 402
 403 \membersection{wxDialog::SetEscapeId}\label{wxdialogsetescapeid}
 404
 405 \func{void}{SetEscapeId}{\param{int }{id}}
 406
 407 Sets the identifier of the button which should work like the standard
 408 \texttt{\textsc{Cancel}} button in this dialog. When the button with this id is
 409 clicked, the dialog is closed. Also, when the user presses \texttt{\textsc{ESC}}
 410 key in the dialog or closes the dialog using the close button in the title bar,
 411 this is mapped to the click of the button with the specified id.
 412
 413 By default, the escape id is the special value \texttt{wxID\_ANY} meaning that
 414 \texttt{wxID\_CANCEL} button is used if it's present in the dialog and
 415 otherwise the button with \helpref{GetAffirmativeId()}{wxdialoggetaffirmativeid}
 416 is used. Another special value for \arg{id} is \texttt{wxID\_NONE} meaning that
 417 \texttt{\textsc{ESC}} presses should be ignored. If any other value is given, it
 418 is interpreted as the id of the button to map the escape key to.
 419
 420
 421 \membersection{wxDialog::SetIcon}\label{wxdialogseticon}
 422
 423 \func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
 424
 425 Sets the icon for this dialog.
 426
 427 \wxheading{Parameters}
 428
 429 \docparam{icon}{The icon to associate with this dialog.}
 430
 431 See also \helpref{wxIcon}{wxicon}.
 432
 433
 434 \membersection{wxDialog::SetIcons}\label{wxdialogseticons}
 435
 436 \func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}
 437
 438 Sets the icons for this dialog.
 439
 440 \wxheading{Parameters}
 441
 442 \docparam{icons}{The icons to associate with this dialog.}
 443
 444 See also \helpref{wxIconBundle}{wxiconbundle}.
 445
 446
 447 \membersection{wxDialog::SetModal}\label{wxdialogsetmodal}
 448
 449 \func{void}{SetModal}{\param{bool}{ flag}}
 450
 451 {\bf NB:} This function is deprecated and doesn't work for all ports, just use
 452 \helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead.
 453
 454 Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control
 455 until the dialog is hidden) or modeless (control returns immediately).
 456
 457 \wxheading{Parameters}
 458
 459 \docparam{flag}{If true, the dialog will be modal, otherwise it will be modeless.}
 460
 461
 462 \membersection{wxDialog::SetReturnCode}\label{wxdialogsetreturncode}
 463
 464 \func{void}{SetReturnCode}{\param{int }{retCode}}
 465
 466 Sets the return code for this window.
 467
 468 \wxheading{Parameters}
 469
 470 \docparam{retCode}{The integer return code, usually a control identifier.}
 471
 472 \wxheading{Remarks}
 473
 474 A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
 475 a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogendmodal} calls {\bf SetReturnCode}.
 476
 477 \wxheading{See also}
 478
 479 \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 480 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 481
 482
 483 \membersection{wxDialog::Show}\label{wxdialogshow}
 484
 485 \func{bool}{Show}{\param{bool}{ show}}
 486
 487 Hides or shows the dialog.
 488
 489 \wxheading{Parameters}
 490
 491 \docparam{show}{If true, the dialog box is shown and brought to the front;
 492 otherwise the box is hidden. If false and the dialog is
 493 modal, control is returned to the calling program.}
 494
 495 \wxheading{Remarks}
 496
 497 The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}.
 498
 499
 500 \membersection{wxDialog::ShowModal}\label{wxdialogshowmodal}
 501
 502 \func{int}{ShowModal}{\void}
 503
 504 Shows a modal dialog. Program flow does not return until the dialog has been dismissed with\rtfsp
 505 \helpref{wxDialog::EndModal}{wxdialogendmodal}.
 506
 507 \wxheading{Return value}
 508
 509 The return value is the value set with \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}.
 510
 511 \wxheading{See also}
 512
 513 \helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
 514 \helpref{wxDialog:GetReturnCode}{wxdialoggetreturncode},\rtfsp
 515 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
 516