docs/latex/wx/dialog.tex

   1 \section{\class{wxDialog}}\label{wxdialog}
   2
   3 A dialog box is a window with a title bar and sometimes a system menu, which can be moved around
   4 the screen. It can contain controls and other windows.
   5
   6 \wxheading{Derived from}
   7
   8 \helpref{wxPanel}{wxpanel}\\
   9 \helpref{wxWindow}{wxwindow}\\
  10 \helpref{wxEvtHandler}{wxevthandler}\\
  11 \helpref{wxObject}{wxobject}
  12
  13 \wxheading{Include files}
  14
  15 <wx/dialog.h>
  16
  17 \wxheading{Remarks}
  18
  19 There are two kinds of dialog - {\it modal} and {\it modeless}. A modal dialog
  20 blocks program flow and user input on other windows until it is dismissed, whereas a modeless dialog behaves more
  21 like a frame in that program flow continues, and input on other windows is still possible.
  22 You specify the type of dialog with the {\bf wxDIALOG\_MODAL} and {\bf wxDIALOG\_MODELESS} window
  23 styles.
  24
  25 A dialog may be loaded from a wxWindows resource file (extension {\tt wxr}).
  26
  27 An application can define an \helpref{OnCloseWindow}{wxwindowonclosewindow} handler for the
  28 dialog to respond to system close events.
  29
  30 \wxheading{Window styles}
  31
  32 \twocolwidtha{5cm}
  33 \begin{twocollist}\itemsep=0pt
  34 \twocolitem{\windowstyle{wxCAPTION}}{Puts a caption on the dialog box (Motif only).}
  35 \twocolitem{\windowstyle{wxDEFAULT\_DIALOG\_STYLE}}{Equivalent to a combination of wxCAPTION, wxSYSTEM\_MENU and wxTHICK\_FRAME}
  36 \twocolitem{\windowstyle{wxRESIZE\_BORDER}}{Display a resizeable frame around the window (Unix only).}
  37 \twocolitem{\windowstyle{wxSYSTEM\_MENU}}{Display a system menu.}
  38 \twocolitem{\windowstyle{wxTHICK\_FRAME}}{Display a thick frame around the window.}
  39 \twocolitem{\windowstyle{wxSTAY\_ON\_TOP}}{The dialog stays on top of all other windows (Windows only).}
  40 \twocolitem{\windowstyle{wxNO\_3D}}{Under Windows, specifies that the child controls
  41 should not have 3D borders unless specified in the control.}
  42 \end{twocollist}
  43
  44 Under Unix or Linux, MWM (the Motif Window Manager) or other window managers reckognizing
  45 the MHM hints should be running for any of these styles to have an effect.
  46
  47 See also \helpref{Generic window styles}{windowstyles}.
  48
  49 \wxheading{See also}
  50
  51 \helpref{wxDialog overview}{wxdialogoverview}, \helpref{wxFrame}{wxframe}, \helpref{Resources}{resources},\rtfsp
  52 \helpref{Validator overview}{validatoroverview}
  53
  54 \latexignore{\rtfignore{\wxheading{Members}}}
  55
  56 \membersection{wxDialog::wxDialog}\label{wxdialogconstr}
  57
  58 \func{}{wxDialog}{\void}
  59
  60 Default constructor.
  61
  62 \func{}{wxDialog}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
  63 \param{const wxString\& }{title},\rtfsp
  64 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  65 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  66 \param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp
  67 \param{const wxString\& }{name = ``dialogBox"}}
  68
  69 Constructor.
  70
  71 \wxheading{Parameters}
  72
  73 \docparam{parent}{Can be NULL, a frame or another dialog box.}
  74
  75 \docparam{id}{An identifier for the dialog. A value of -1 is taken to mean a default.}
  76
  77 \docparam{title}{The title of the dialog.}
  78
  79 \docparam{pos}{The dialog position. A value of (-1, -1) indicates a default position, chosen by
  80 either the windowing system or wxWindows, depending on platform.}
  81
  82 \docparam{size}{The dialog size. A value of (-1, -1) indicates a default size, chosen by
  83 either the windowing system or wxWindows, depending on platform.}
  84
  85 \docparam{style}{The window style. See \helpref{wxDialog}{wxdialog}.}
  86
  87 \docparam{name}{Used to associate a name with the window,
  88 allowing the application user to set Motif resource values for
  89 individual dialog boxes.}
  90
  91 \wxheading{See also}
  92
  93 \helpref{wxDialog::Create}{wxdialogcreate}
  94
  95 \membersection{wxDialog::\destruct{wxDialog}}
  96
  97 \func{}{\destruct{wxDialog}}{\void}
  98
  99 Destructor. Deletes any child windows before deleting the physical window.
 100
 101 \membersection{wxDialog::Centre}\label{wxdialogcentre}
 102
 103 \func{void}{Centre}{\param{int}{ direction = wxBOTH}}
 104
 105 Centres the dialog box on the display.
 106
 107 \wxheading{Parameters}
 108
 109 \docparam{direction}{May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL} or {\tt wxBOTH}.}
 110
 111 \membersection{wxDialog::Create}\label{wxdialogcreate}
 112
 113 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
 114 \param{const wxString\& }{title},\rtfsp
 115 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
 116 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 117 \param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp
 118 \param{const wxString\& }{name = ``dialogBox"}}
 119
 120 Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogconstr}\rtfsp
 121 for details.
 122
 123 \membersection{wxDialog::EndModal}\label{wxdialogendmodal}
 124
 125 \func{void}{EndModal}{\param{int }{retCode}}
 126
 127 Ends a modal dialog, passing a value to be returned from the \helpref{wxDialog::ShowModal}{wxdialogshowmodal}\rtfsp
 128 invocation.
 129
 130 \wxheading{Parameters}
 131
 132 \docparam{retCode}{The value that should be returned by {\bf ShowModal}.}
 133
 134 \wxheading{See also}
 135
 136 \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 137 \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp
 138 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
 139
 140 \membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode}
 141
 142 \func{int}{GetReturnCode}{\void}
 143
 144 Gets the return code for this window.
 145
 146 \wxheading{Remarks}
 147
 148 A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
 149 a code to the application.
 150
 151 \wxheading{See also}
 152
 153 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 154 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 155
 156 \membersection{wxDialog::GetTitle}\label{wxdialoggettitle}
 157
 158 \constfunc{wxString}{GetTitle}{\void}
 159
 160 Returns the title of the dialog box.
 161
 162 \membersection{wxDialog::Iconize}\label{wxdialogiconized}
 163
 164 \func{void}{Iconize}{\param{const bool}{ iconize}}
 165
 166 Iconizes or restores the dialog. Windows only.
 167
 168 \wxheading{Parameters}
 169
 170 \docparam{iconize}{If TRUE, iconizes the dialog box; if FALSE, shows and restores it.}
 171
 172 \wxheading{Remarks}
 173
 174 Note that in Windows, iconization has no effect since dialog boxes cannot be
 175 iconized. However, applications may need to explicitly restore dialog
 176 boxes under Motif which have user-iconizable frames, and under Windows
 177 calling {\tt Iconize(FALSE)} will bring the window to the front, as does
 178 \rtfsp{\tt Show(TRUE)}.
 179
 180 \membersection{wxDialog::IsIconized}\label{wxdialogisiconized}
 181
 182 \constfunc{bool}{IsIconized}{\void}
 183
 184 Returns TRUE if the dialog box is iconized. Windows only.
 185
 186 \wxheading{Remarks}
 187
 188 Always returns FALSE under Windows since dialogs cannot be iconized.
 189
 190 \membersection{wxDialog::IsModal}\label{wxdialogismodal}
 191
 192 \constfunc{bool}{IsModal}{\void}
 193
 194 Returns TRUE if the dialog box is modal, FALSE otherwise.
 195
 196 \membersection{wxDialog::OnCharHook}\label{wxdialogoncharhook}
 197
 198 \func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}
 199
 200 This member is called to allow the window to intercept keyboard events
 201 before they are processed by child windows.
 202
 203 For more information, see \helpref{wxWindow::OnCharHook}{wxwindowoncharhook}
 204
 205 \wxheading{Remarks}
 206
 207 wxDialog implements this handler to fake a cancel command if the escape key has been
 208 pressed. This will dismiss the dialog.
 209
 210 \membersection{wxDialog::OnApply}\label{wxdialogonapply}
 211
 212 \func{void}{OnApply}{\param{wxCommandEvent\& }{event}}
 213
 214 The default handler for the wxID\_APPLY identifier.
 215
 216 \wxheading{Remarks}
 217
 218 This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}.
 219
 220 \wxheading{See also}
 221
 222 \helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel}
 223
 224 \membersection{wxDialog::OnCancel}\label{wxdialogoncancel}
 225
 226 \func{void}{OnCancel}{\param{wxCommandEvent\& }{event}}
 227
 228 The default handler for the wxID\_CANCEL identifier.
 229
 230 \wxheading{Remarks}
 231
 232 The function either calls {\bf EndModal(wxID\_CANCEL)} if the dialog is modal, or
 233 sets the return value to wxID\_CANCEL and calls {\bf Show(FALSE)} if the dialog is modeless.
 234
 235 \wxheading{See also}
 236
 237 \helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnApply}{wxdialogonapply}
 238
 239 \membersection{wxDialog::OnOK}\label{wxdialogonok}
 240
 241 \func{void}{OnOK}{\param{wxCommandEvent\& }{event}}
 242
 243 The default handler for the wxID\_OK identifier.
 244
 245 \wxheading{Remarks}
 246
 247 The function calls
 248 \rtfsp\helpref{wxWindow::Validate}{wxwindowvalidate}, then \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}.
 249 If this returns TRUE, the function either calls {\bf EndModal(wxID\_OK)} if the dialog is modal, or
 250 sets the return value to wxID\_OK and calls {\bf Show(FALSE)} if the dialog is modeless.
 251
 252 \wxheading{See also}
 253
 254 \helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply}
 255
 256 \membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged}
 257
 258 \func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}}
 259
 260 The default handler for wxEVT\_SYS\_COLOUR\_CHANGED.
 261
 262 \wxheading{Parameters}
 263
 264 \docparam{event}{The colour change event.}
 265
 266 \wxheading{Remarks}
 267
 268 Changes the dialog's colour to conform to the current settings (Windows only).
 269 Add an event table entry for your dialog class if you wish the behaviour
 270 to be different (such as keeping a user-defined
 271 background colour). If you do override this function, call \helpref{wxWindow::OnSysColourChanged}{wxwindowonsyscolourchanged} to
 272 propagate the notification to child windows and controls.
 273
 274 \wxheading{See also}
 275
 276 \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}
 277
 278 \membersection{wxDialog::SetModal}\label{wxdialogsetmodal}
 279
 280 \func{void}{SetModal}{\param{const bool}{ flag}}
 281
 282 Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control
 283 until the dialog is hidden) or modeless (control returns immediately).
 284
 285 \wxheading{Parameters}
 286
 287 \docparam{flag}{If TRUE, the dialog will be modal, otherwise it will be modeless.}
 288
 289 \membersection{wxDialog::SetReturnCode}\label{wxdialogsetreturncode}
 290
 291 \func{void}{SetReturnCode}{\param{int }{retCode}}
 292
 293 Sets the return code for this window.
 294
 295 \wxheading{Parameters}
 296
 297 \docparam{retCode}{The integer return code, usually a control identifier.}
 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. The function \helpref{wxDialog::EndModal}{wxdialogendmodal} calls {\bf SetReturnCode}.
 303
 304 \wxheading{See also}
 305
 306 \helpref{wxWindow::GetReturnCode}{wxwindowgetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
 307 \helpref{wxDialog::EndModal}{wxdialogendmodal}
 308
 309 \membersection{wxDialog::SetTitle}\label{wxdialogsettitle}
 310
 311 \func{void}{SetTitle}{\param{const wxString\& }{ title}}
 312
 313 Sets the title of the dialog box.
 314
 315 \wxheading{Parameters}
 316
 317 \docparam{title}{The dialog box title.}
 318
 319 \membersection{wxDialog::Show}\label{wxdialogshow}
 320
 321 \func{bool}{Show}{\param{const bool}{ show}}
 322
 323 Hides or shows the dialog.
 324
 325 \wxheading{Parameters}
 326
 327 \docparam{show}{If TRUE, the dialog box is shown and brought to the front;
 328 otherwise the box is hidden. If FALSE and the dialog is
 329 modal, control is returned to the calling program.}
 330
 331 \wxheading{Remarks}
 332
 333 The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}.
 334
 335 \membersection{wxDialog::ShowModal}\label{wxdialogshowmodal}
 336
 337 \func{int}{ShowModal}{\void}
 338
 339 Shows a modal dialog. Program flow does not return until the dialog has been dismissed with\rtfsp
 340 \helpref{wxDialog::EndModal}{wxdialogendmodal}.
 341
 342 \wxheading{Return value}
 343
 344 The return value is the value set with \helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}.
 345
 346 \wxheading{See also}
 347
 348 \helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
 349 \helpref{wxWindow::GetReturnCode}{wxwindowgetreturncode},\rtfsp
 350 \helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}
 351
 352