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