]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/dialog.tex
[ 1574592 ] Documentation for wxBufferedDC improvements
[wxWidgets.git] / 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 uses \helpref{CreateStdDialogButtonSizer}{wxdialogcreatestddialogbuttonsizer}
193 internally for most platforms but doesn't create the sizer at all for the
194 platforms with hardware buttons (such as smartphones) for which it sets up the
195 hardware buttons appropriately and returns \NULL, so don't forget to test that
196 the return value is valid before using it.
197
198
199 \membersection{wxDialog::CreateSeparatedButtonSizer}\label{wxdialogcreateseparatedbuttonsizer}
200
201 \func{wxSizer*}{CreateSeparatedButtonSizer}{\param{long}{ flags}}
202
203 Creates a sizer with standard buttons using
204 \helpref{CreateButtonSizer}{wxdialogcreatebuttonsizer} separated from the rest
205 of the dialog contents by a horizontal \helpref{wxStaticLine}{wxstaticline}.
206
207 Please notice that just like CreateButtonSizer() this function may return \NULL
208 if no buttons were created.
209
210
211 \membersection{wxDialog::CreateStdDialogButtonSizer}\label{wxdialogcreatestddialogbuttonsizer}
212
213 \func{wxStdDialogButtonSizer*}{CreateStdDialogButtonSizer}{\param{long}{ flags}}
214
215 Creates a \helpref{wxStdDialogButtonSizer}{wxstddialogbuttonsizer} with standard buttons. {\it flags} is a bit list
216 of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO\_DEFAULT.
217
218 The sizer lays out the buttons in a manner appropriate to the platform.
219
220
221 \membersection{wxDialog::DoOK}\label{wxdialogdook}
222
223 \func{virtual bool}{DoOK}{\void}
224
225 This function is called when the titlebar OK button is pressed (PocketPC only).
226 A command event for the identifier returned by GetAffirmativeId is sent by
227 default. You can override this function. If the function returns false, wxWidgets
228 will call Close() for the dialog.
229
230
231 \membersection{wxDialog::EndModal}\label{wxdialogendmodal}
232
233 \func{void}{EndModal}{\param{int }{retCode}}
234
235 Ends a modal dialog, passing a value to be returned from the \helpref{wxDialog::ShowModal}{wxdialogshowmodal}\rtfsp
236 invocation.
237
238 \wxheading{Parameters}
239
240 \docparam{retCode}{The value that should be returned by {\bf ShowModal}.}
241
242 \wxheading{See also}
243
244 \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
245 \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp
246 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
247
248
249 \membersection{wxDialog::GetAffirmativeId}\label{wxdialoggetaffirmativeid}
250
251 \constfunc{int}{GetAffirmativeId}{\void}
252
253 Gets the identifier of the button which works like standard OK button in this
254 dialog.
255
256 \wxheading{See also}
257
258 \helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid}
259
260
261 \membersection{wxDialog::GetEscapeId}\label{wxdialoggetescapeid}
262
263 \constfunc{int}{GetEscapeId}{\void}
264
265 Gets the identifier of the button to map presses of \texttt{\textsc{ESC}}
266 button to.
267
268 \wxheading{See also}
269
270 \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid}
271
272
273 \membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode}
274
275 \func{int}{GetReturnCode}{\void}
276
277 Gets the return code for this window.
278
279 \wxheading{Remarks}
280
281 A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
282 a code to the application.
283
284 \wxheading{See also}
285
286 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
287 \helpref{wxDialog::EndModal}{wxdialogendmodal}
288
289
290 \membersection{wxDialog::GetToolBar}\label{wxdialoggettoolbar}
291
292 \constfunc{wxToolBar*}{GetToolBar}{\void}
293
294 On PocketPC, a dialog is automatically provided with an empty toolbar. GetToolBar
295 allows you to access the toolbar and add tools to it. Removing tools and adding
296 arbitrary controls are not currently supported.
297
298 This function is not available on any other platform.
299
300
301 \membersection{wxDialog::Iconize}\label{wxdialogiconized}
302
303 \func{void}{Iconize}{\param{const bool}{ iconize}}
304
305 Iconizes or restores the dialog. Windows only.
306
307 \wxheading{Parameters}
308
309 \docparam{iconize}{If true, iconizes the dialog box; if false, shows and restores it.}
310
311 \wxheading{Remarks}
312
313 Note that in Windows, iconization has no effect since dialog boxes cannot be
314 iconized. However, applications may need to explicitly restore dialog
315 boxes under Motif which have user-iconizable frames, and under Windows
316 calling {\tt Iconize(false)} will bring the window to the front, as does
317 \rtfsp{\tt Show(true)}.
318
319
320 \membersection{wxDialog::IsIconized}\label{wxdialogisiconized}
321
322 \constfunc{bool}{IsIconized}{\void}
323
324 Returns true if the dialog box is iconized. Windows only.
325
326 \wxheading{Remarks}
327
328 Always returns false under Windows since dialogs cannot be iconized.
329
330
331 \membersection{wxDialog::IsModal}\label{wxdialogismodal}
332
333 \constfunc{bool}{IsModal}{\void}
334
335 Returns true if the dialog box is modal, false otherwise.
336
337
338 \membersection{wxDialog::OnApply}\label{wxdialogonapply}
339
340 \func{void}{OnApply}{\param{wxCommandEvent\& }{event}}
341
342 The default handler for the wxID\_APPLY identifier.
343
344 \wxheading{Remarks}
345
346 This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}.
347
348 \wxheading{See also}
349
350 \helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel}
351
352
353 \membersection{wxDialog::OnCancel}\label{wxdialogoncancel}
354
355 \func{void}{OnCancel}{\param{wxCommandEvent\& }{event}}
356
357 The default handler for the wxID\_CANCEL identifier.
358
359 \wxheading{Remarks}
360
361 The function either calls {\bf EndModal(wxID\_CANCEL)} if the dialog is modal, or
362 sets the return value to wxID\_CANCEL and calls {\bf Show(false)} if the dialog is modeless.
363
364 \wxheading{See also}
365
366 \helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnApply}{wxdialogonapply}
367
368
369 \membersection{wxDialog::OnOK}\label{wxdialogonok}
370
371 \func{void}{OnOK}{\param{wxCommandEvent\& }{event}}
372
373 The default handler for the wxID\_OK identifier.
374
375 \wxheading{Remarks}
376
377 The function calls
378 \rtfsp\helpref{wxWindow::Validate}{wxwindowvalidate}, then \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}.
379 If this returns true, the function either calls {\bf EndModal(wxID\_OK)} if the dialog is modal, or
380 sets the return value to wxID\_OK and calls {\bf Show(false)} if the dialog is modeless.
381
382 \wxheading{See also}
383
384 \helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply}
385
386
387 \membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged}
388
389 \func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}}
390
391 The default handler for wxEVT\_SYS\_COLOUR\_CHANGED.
392
393 \wxheading{Parameters}
394
395 \docparam{event}{The colour change event.}
396
397 \wxheading{Remarks}
398
399 Changes the dialog's colour to conform to the current settings (Windows only).
400 Add an event table entry for your dialog class if you wish the behaviour
401 to be different (such as keeping a user-defined
402 background colour). If you do override this function, call wxEvent::Skip to
403 propagate the notification to child windows and controls.
404
405 \wxheading{See also}
406
407 \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}
408
409
410 \membersection{wxDialog::SetAffirmativeId}\label{wxdialogsetaffirmativeid}
411
412 \func{void}{SetAffirmativeId}{\param{int }{id}}
413
414 Sets the identifier to be used as OK button. When the button with this
415 identifier is pressed, the dialog calls \helpref{Validate}{wxwindowvalidate}
416 and \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}
417 and, if they both return \true, closes the dialog with \texttt{wxID\_OK} return
418 code.
419
420 Also, when the user presses a hardware OK button on the devices having one or
421 the special OK button in the PocketPC title bar, an event with this id is
422 generated.
423
424 By default, the affirmative id is wxID\_OK.
425
426 \wxheading{See also}
427
428 \helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid}, \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid}
429
430
431 \membersection{wxDialog::SetEscapeId}\label{wxdialogsetescapeid}
432
433 \func{void}{SetEscapeId}{\param{int }{id}}
434
435 Sets the identifier of the button which should work like the standard
436 \texttt{\textsc{Cancel}} button in this dialog. When the button with this id is
437 clicked, the dialog is closed. Also, when the user presses \texttt{\textsc{ESC}}
438 key in the dialog or closes the dialog using the close button in the title bar,
439 this is mapped to the click of the button with the specified id.
440
441 By default, the escape id is the special value \texttt{wxID\_ANY} meaning that
442 \texttt{wxID\_CANCEL} button is used if it's present in the dialog and
443 otherwise the button with \helpref{GetAffirmativeId()}{wxdialoggetaffirmativeid}
444 is used. Another special value for \arg{id} is \texttt{wxID\_NONE} meaning that
445 \texttt{\textsc{ESC}} presses should be ignored. If any other value is given, it
446 is interpreted as the id of the button to map the escape key to.
447
448
449 \membersection{wxDialog::SetIcon}\label{wxdialogseticon}
450
451 \func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
452
453 Sets the icon for this dialog.
454
455 \wxheading{Parameters}
456
457 \docparam{icon}{The icon to associate with this dialog.}
458
459 See also \helpref{wxIcon}{wxicon}.
460
461
462 \membersection{wxDialog::SetIcons}\label{wxdialogseticons}
463
464 \func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}
465
466 Sets the icons for this dialog.
467
468 \wxheading{Parameters}
469
470 \docparam{icons}{The icons to associate with this dialog.}
471
472 See also \helpref{wxIconBundle}{wxiconbundle}.
473
474
475 \membersection{wxDialog::SetModal}\label{wxdialogsetmodal}
476
477 \func{void}{SetModal}{\param{const bool}{ flag}}
478
479 {\bf NB:} This function is deprecated and doesn't work for all ports, just use
480 \helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead.
481
482 Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control
483 until the dialog is hidden) or modeless (control returns immediately).
484
485 \wxheading{Parameters}
486
487 \docparam{flag}{If true, the dialog will be modal, otherwise it will be modeless.}
488
489
490 \membersection{wxDialog::SetReturnCode}\label{wxdialogsetreturncode}
491
492 \func{void}{SetReturnCode}{\param{int }{retCode}}
493
494 Sets the return code for this window.
495
496 \wxheading{Parameters}
497
498 \docparam{retCode}{The integer return code, usually a control identifier.}
499
500 \wxheading{Remarks}
501
502 A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
503 a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogendmodal} calls {\bf SetReturnCode}.
504
505 \wxheading{See also}
506
507 \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
508 \helpref{wxDialog::EndModal}{wxdialogendmodal}
509
510
511 \membersection{wxDialog::Show}\label{wxdialogshow}
512
513 \func{bool}{Show}{\param{const bool}{ show}}
514
515 Hides or shows the dialog.
516
517 \wxheading{Parameters}
518
519 \docparam{show}{If true, the dialog box is shown and brought to the front;
520 otherwise the box is hidden. If false and the dialog is
521 modal, control is returned to the calling program.}
522
523 \wxheading{Remarks}
524
525 The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}.
526
527
528 \membersection{wxDialog::ShowModal}\label{wxdialogshowmodal}
529
530 \func{int}{ShowModal}{\void}
531
532 Shows a modal dialog. Program flow does not return until the dialog has been dismissed with\rtfsp
533 \helpref{wxDialog::EndModal}{wxdialogendmodal}.
534
535 \wxheading{Return value}
536
537 The return value is the value set with \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}.
538
539 \wxheading{See also}
540
541 \helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
542 \helpref{wxDialog:GetReturnCode}{wxdialoggetreturncode},\rtfsp
543 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
544