]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/dialog.tex
change wxTextValidator to use wxArrayString instead of wxStringList
[wxWidgets.git] / docs / latex / wx / dialog.tex
... / ...
CommitLineData
1\section{\class{wxDialog}}\label{wxdialog}
2
3A dialog box is a window with a title bar and sometimes a system menu, which
4can be moved around the screen. It can contain controls and other windows and
5is usually used to allow the user to make some choice or to answer a question.
6
7\wxheading{Derived from}
8
9\helpref{wxTopLevelWindow}{wxtoplevelwindow}\\
10\helpref{wxWindow}{wxwindow}\\
11\helpref{wxEvtHandler}{wxevthandler}\\
12\helpref{wxObject}{wxobject}
13
14\wxheading{Include files}
15
16<wx/dialog.h>
17
18\wxheading{Remarks}
19
20There are two kinds of dialog -- {\it modal}\ and {\it modeless}. A modal dialog
21blocks program flow and user input on other windows until it is dismissed,
22whereas a modeless dialog behaves more like a frame in that program flow
23continues, and input in other windows is still possible. To show a modal dialog
24you should use the \helpref{ShowModal}{wxdialogshowmodal} method while to show
25a dialog modelessly you simply use \helpref{Show}{wxdialogshow}, just as with
26frames.
27
28Note that the modal dialog is one of the very few examples of
29wxWindow-derived objects which may be created on the stack and not on the heap.
30In other words, although this code snippet:
31
32\begin{verbatim}
33 void AskUser()
34 {
35 MyAskDialog *dlg = new MyAskDialog(...);
36 if ( dlg->ShowModal() == wxID_OK )
37 ...
38 //else: dialog was cancelled or some another button pressed
39
40 dlg->Destroy();
41 }
42\end{verbatim}
43
44works, you can also achieve the same result by using a simpler code fragment
45below:
46
47\begin{verbatim}
48 void AskUser()
49 {
50 MyAskDialog dlg(...);
51 if ( dlg.ShowModal() == wxID_OK )
52 ...
53
54 // no need to call Destroy() here
55 }
56\end{verbatim}
57
58An application can define a \helpref{wxCloseEvent}{wxcloseevent} handler for
59the dialog to respond to system close events.
60
61\wxheading{Window styles}
62
63\twocolwidtha{5cm}
64\begin{twocollist}\itemsep=0pt
65\twocolitem{\windowstyle{wxCAPTION}}{Puts a caption on the dialog box.}
66\twocolitem{\windowstyle{wxDEFAULT\_DIALOG\_STYLE}}{Equivalent to a combination of wxCAPTION, wxCLOSE\_BOX and wxSYSTEM\_MENU (the last one is not used under Unix)}
67\twocolitem{\windowstyle{wxRESIZE\_BORDER}}{Display a resizeable frame around the window.}
68\twocolitem{\windowstyle{wxSYSTEM\_MENU}}{Display a system menu.}
69\twocolitem{\windowstyle{wxCLOSE\_BOX}}{Displays a close box on the frame.}
70\twocolitem{\windowstyle{wxMAXIMIZE\_BOX}}{Displays a maximize box on the dialog.}
71\twocolitem{\windowstyle{wxMINIMIZE\_BOX}}{Displays a minimize box on the dialog.}
72\twocolitem{\windowstyle{wxTHICK\_FRAME}}{Display a thick frame around the window.}
73\twocolitem{\windowstyle{wxSTAY\_ON\_TOP}}{The dialog stays on top of all other windows (Windows only).}
74\twocolitem{\windowstyle{wxNO\_3D}}{Under Windows, specifies that the child controls
75should not have 3D borders unless specified in the control.}
76\twocolitem{\windowstyle{wxDIALOG\_NO\_PARENT}}{By default, a dialog created
77with a {\tt NULL} parent window will be given the
78\helpref{application's top level window}{wxappgettopwindow} as parent. Use this
79style to prevent this from happening and create an orphan dialog. This is not recommended for modal dialogs.}
80\twocolitem{\windowstyle{wxDIALOG\_EX\_CONTEXTHELP}}{Under Windows, puts a query button on the
81caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets will send
82a wxEVT\_HELP event if the user clicked on an application window. {\it Note}\ that this is an extended
83style and must be set by calling \helpref{SetExtraStyle}{wxwindowsetextrastyle} before Create is called (two-step construction).}
84\end{twocollist}
85
86Under Unix or Linux, MWM (the Motif Window Manager) or other window managers
87recognizing the MHM hints should be running for any of these styles to have an
88effect.
89
90See also \helpref{Generic window styles}{windowstyles}.
91
92\wxheading{See also}
93
94\helpref{wxDialog overview}{wxdialogoverview}, \helpref{wxFrame}{wxframe},\rtfsp
95\helpref{Validator overview}{validatoroverview}
96
97\latexignore{\rtfignore{\wxheading{Members}}}
98
99\membersection{wxDialog::wxDialog}\label{wxdialogctor}
100
101\func{}{wxDialog}{\void}
102
103Default constructor.
104
105\func{}{wxDialog}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
106\param{const wxString\& }{title},\rtfsp
107\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
108\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
109\param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp
110\param{const wxString\& }{name = ``dialogBox"}}
111
112Constructor.
113
114\wxheading{Parameters}
115
116\docparam{parent}{Can be NULL, a frame or another dialog box.}
117
118\docparam{id}{An identifier for the dialog. A value of -1 is taken to mean a default.}
119
120\docparam{title}{The title of the dialog.}
121
122\docparam{pos}{The dialog position. A value of (-1, -1) indicates a default position, chosen by
123either the windowing system or wxWidgets, depending on platform.}
124
125\docparam{size}{The dialog size. A value of (-1, -1) indicates a default size, chosen by
126either the windowing system or wxWidgets, depending on platform.}
127
128\docparam{style}{The window style. See \helpref{wxDialog}{wxdialog}.}
129
130\docparam{name}{Used to associate a name with the window,
131allowing the application user to set Motif resource values for
132individual dialog boxes.}
133
134\wxheading{See also}
135
136\helpref{wxDialog::Create}{wxdialogcreate}
137
138\membersection{wxDialog::\destruct{wxDialog}}\label{wxdialogdtor}
139
140\func{}{\destruct{wxDialog}}{\void}
141
142Destructor. Deletes any child windows before deleting the physical window.
143
144\membersection{wxDialog::Centre}\label{wxdialogcentre}
145
146\func{void}{Centre}{\param{int}{ direction = wxBOTH}}
147
148Centres the dialog box on the display.
149
150\wxheading{Parameters}
151
152\docparam{direction}{May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL} or {\tt wxBOTH}.}
153
154\membersection{wxDialog::Create}\label{wxdialogcreate}
155
156\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
157\param{const wxString\& }{title},\rtfsp
158\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
159\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
160\param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp
161\param{const wxString\& }{name = ``dialogBox"}}
162
163Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogctor}\rtfsp
164for details.
165
166\membersection{wxDialog::EndModal}\label{wxdialogendmodal}
167
168\func{void}{EndModal}{\param{int }{retCode}}
169
170Ends a modal dialog, passing a value to be returned from the \helpref{wxDialog::ShowModal}{wxdialogshowmodal}\rtfsp
171invocation.
172
173\wxheading{Parameters}
174
175\docparam{retCode}{The value that should be returned by {\bf ShowModal}.}
176
177\wxheading{See also}
178
179\helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
180\helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp
181\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
182
183\membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode}
184
185\func{int}{GetReturnCode}{\void}
186
187Gets the return code for this window.
188
189\wxheading{Remarks}
190
191A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
192a code to the application.
193
194\wxheading{See also}
195
196\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
197\helpref{wxDialog::EndModal}{wxdialogendmodal}
198
199\membersection{wxDialog::GetTitle}\label{wxdialoggettitle}
200
201\constfunc{wxString}{GetTitle}{\void}
202
203Returns the title of the dialog box.
204
205\membersection{wxDialog::Iconize}\label{wxdialogiconized}
206
207\func{void}{Iconize}{\param{const bool}{ iconize}}
208
209Iconizes or restores the dialog. Windows only.
210
211\wxheading{Parameters}
212
213\docparam{iconize}{If true, iconizes the dialog box; if false, shows and restores it.}
214
215\wxheading{Remarks}
216
217Note that in Windows, iconization has no effect since dialog boxes cannot be
218iconized. However, applications may need to explicitly restore dialog
219boxes under Motif which have user-iconizable frames, and under Windows
220calling {\tt Iconize(false)} will bring the window to the front, as does
221\rtfsp{\tt Show(true)}.
222
223\membersection{wxDialog::IsIconized}\label{wxdialogisiconized}
224
225\constfunc{bool}{IsIconized}{\void}
226
227Returns true if the dialog box is iconized. Windows only.
228
229\wxheading{Remarks}
230
231Always returns false under Windows since dialogs cannot be iconized.
232
233\membersection{wxDialog::IsModal}\label{wxdialogismodal}
234
235\constfunc{bool}{IsModal}{\void}
236
237Returns true if the dialog box is modal, false otherwise.
238
239\membersection{wxDialog::OnApply}\label{wxdialogonapply}
240
241\func{void}{OnApply}{\param{wxCommandEvent\& }{event}}
242
243The default handler for the wxID\_APPLY identifier.
244
245\wxheading{Remarks}
246
247This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}.
248
249\wxheading{See also}
250
251\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel}
252
253\membersection{wxDialog::OnCancel}\label{wxdialogoncancel}
254
255\func{void}{OnCancel}{\param{wxCommandEvent\& }{event}}
256
257The default handler for the wxID\_CANCEL identifier.
258
259\wxheading{Remarks}
260
261The function either calls {\bf EndModal(wxID\_CANCEL)} if the dialog is modal, or
262sets the return value to wxID\_CANCEL and calls {\bf Show(false)} if the dialog is modeless.
263
264\wxheading{See also}
265
266\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnApply}{wxdialogonapply}
267
268\membersection{wxDialog::OnOK}\label{wxdialogonok}
269
270\func{void}{OnOK}{\param{wxCommandEvent\& }{event}}
271
272The default handler for the wxID\_OK identifier.
273
274\wxheading{Remarks}
275
276The function calls
277\rtfsp\helpref{wxWindow::Validate}{wxwindowvalidate}, then \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}.
278If this returns true, the function either calls {\bf EndModal(wxID\_OK)} if the dialog is modal, or
279sets the return value to wxID\_OK and calls {\bf Show(false)} if the dialog is modeless.
280
281\wxheading{See also}
282
283\helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply}
284
285\membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged}
286
287\func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}}
288
289The default handler for wxEVT\_SYS\_COLOUR\_CHANGED.
290
291\wxheading{Parameters}
292
293\docparam{event}{The colour change event.}
294
295\wxheading{Remarks}
296
297Changes the dialog's colour to conform to the current settings (Windows only).
298Add an event table entry for your dialog class if you wish the behaviour
299to be different (such as keeping a user-defined
300background colour). If you do override this function, call wxEvent::Skip to
301propagate the notification to child windows and controls.
302
303\wxheading{See also}
304
305\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}
306
307\membersection{wxDialog::SetIcon}\label{wxdialogseticon}
308
309\func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
310
311Sets the icon for this dialog.
312
313\wxheading{Parameters}
314
315\docparam{icon}{The icon to associate with this dialog.}
316
317See also \helpref{wxIcon}{wxicon}.
318
319\membersection{wxDialog::SetIcons}\label{wxdialogseticons}
320
321\func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}}
322
323Sets the icons for this dialog.
324
325\wxheading{Parameters}
326
327\docparam{icons}{The icons to associate with this dialog.}
328
329See also \helpref{wxIconBundle}{wxiconbundle}.
330
331\membersection{wxDialog::SetModal}\label{wxdialogsetmodal}
332
333\func{void}{SetModal}{\param{const bool}{ flag}}
334
335{\bf NB:} This function is deprecated and doesn't work for all ports, just use
336\helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead.
337
338Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control
339until the dialog is hidden) or modeless (control returns immediately).
340
341\wxheading{Parameters}
342
343\docparam{flag}{If true, the dialog will be modal, otherwise it will be modeless.}
344
345\membersection{wxDialog::SetReturnCode}\label{wxdialogsetreturncode}
346
347\func{void}{SetReturnCode}{\param{int }{retCode}}
348
349Sets the return code for this window.
350
351\wxheading{Parameters}
352
353\docparam{retCode}{The integer return code, usually a control identifier.}
354
355\wxheading{Remarks}
356
357A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
358a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogendmodal} calls {\bf SetReturnCode}.
359
360\wxheading{See also}
361
362\helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
363\helpref{wxDialog::EndModal}{wxdialogendmodal}
364
365\membersection{wxDialog::SetTitle}\label{wxdialogsettitle}
366
367\func{void}{SetTitle}{\param{const wxString\& }{ title}}
368
369Sets the title of the dialog box.
370
371\wxheading{Parameters}
372
373\docparam{title}{The dialog box title.}
374
375\membersection{wxDialog::Show}\label{wxdialogshow}
376
377\func{bool}{Show}{\param{const bool}{ show}}
378
379Hides or shows the dialog.
380
381\wxheading{Parameters}
382
383\docparam{show}{If true, the dialog box is shown and brought to the front;
384otherwise the box is hidden. If false and the dialog is
385modal, control is returned to the calling program.}
386
387\wxheading{Remarks}
388
389The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}.
390
391\membersection{wxDialog::ShowModal}\label{wxdialogshowmodal}
392
393\func{int}{ShowModal}{\void}
394
395Shows a modal dialog. Program flow does not return until the dialog has been dismissed with\rtfsp
396\helpref{wxDialog::EndModal}{wxdialogendmodal}.
397
398\wxheading{Return value}
399
400The return value is the value set with \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}.
401
402\wxheading{See also}
403
404\helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
405\helpref{wxDialog:GetReturnCode}{wxdialoggetreturncode},\rtfsp
406\helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
407