]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/dialog.tex
Minor doc updates
[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 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