1 \section{\class{wxDialog
}}\label{wxdialog
}
3 A dialog box is a window with a title bar and sometimes a system menu, which
4 can be moved around the screen. It can contain controls and other windows and
5 is usually used to allow the user to make some choice or to answer a question.
7 \wxheading{Derived from
}
9 \helpref{wxTopLevelWindow
}{wxtoplevelwindow
}\\
10 \helpref{wxWindow
}{wxwindow
}\\
11 \helpref{wxEvtHandler
}{wxevthandler
}\\
12 \helpref{wxObject
}{wxobject
}
14 \wxheading{Include files
}
20 There are two kinds of dialog --
{\it modal
}\ and
{\it modeless
}. A modal dialog
21 blocks program flow and user input on other windows until it is dismissed,
22 whereas a modeless dialog behaves more like a frame in that program flow
23 continues, and input in other windows is still possible. To show a modal dialog
24 you should use the
\helpref{ShowModal
}{wxdialogshowmodal
} method while to show
25 a dialog modelessly you simply use
\helpref{Show
}{wxdialogshow
}, just as with
28 Note that the modal dialog is one of the very few examples of
29 wxWindow-derived objects which may be created on the stack and not on the heap.
30 In other words, although this code snippet:
35 MyAskDialog *dlg = new MyAskDialog(...);
36 if ( dlg->ShowModal() == wxID_OK )
38 //else: dialog was cancelled or some another button pressed
44 works, you can also achieve the same result by using a simpler code fragment
51 if ( dlg.ShowModal() == wxID_OK )
54 // no need to call Destroy() here
58 An application can define a
\helpref{wxCloseEvent
}{wxcloseevent
} handler for
59 the dialog to respond to system close events.
61 \wxheading{Window styles
}
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
75 should not have
3D borders unless specified in the control.
}
76 \twocolitem{\windowstyle{wxDIALOG
\_NO\_PARENT}}{By default, a dialog created
77 with a
{\tt NULL
} parent window will be given the
78 \helpref{application's top level window
}{wxappgettopwindow
} as parent. Use this
79 style 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
81 caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets will send
82 a wxEVT
\_HELP event if the user clicked on an application window.
{\it Note
}\ that this is an extended
83 style and must be set by calling
\helpref{SetExtraStyle
}{wxwindowsetextrastyle
} before Create is called (two-step construction).
}
84 \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.
}
87 Under Unix or Linux, MWM (the Motif Window Manager) or other window managers
88 recognizing the MHM hints should be running for any of these styles to have an
91 See also
\helpref{Generic window styles
}{windowstyles
}.
95 \helpref{wxDialog overview
}{wxdialogoverview
},
\helpref{wxFrame
}{wxframe
},
\rtfsp
96 \helpref{Validator overview
}{validatoroverview
}
98 \latexignore{\rtfignore{\wxheading{Members
}}}
100 \membersection{wxDialog::wxDialog
}\label{wxdialogctor
}
102 \func{}{wxDialog
}{\void}
106 \func{}{wxDialog
}{\param{wxWindow*
}{parent
},
\param{wxWindowID
}{id
},
\rtfsp
107 \param{const wxString\&
}{title
},
\rtfsp
108 \param{const wxPoint\&
}{pos = wxDefaultPosition
},
\rtfsp
109 \param{const wxSize\&
}{size = wxDefaultSize
},
\rtfsp
110 \param{long
}{ style = wxDEFAULT
\_DIALOG\_STYLE},
\rtfsp
111 \param{const wxString\&
}{name = ``dialogBox"
}}
115 \wxheading{Parameters
}
117 \docparam{parent
}{Can be NULL, a frame or another dialog box.
}
119 \docparam{id
}{An identifier for the dialog. A value of -
1 is taken to mean a default.
}
121 \docparam{title
}{The title of the dialog.
}
123 \docparam{pos
}{The dialog position. A value of (-
1, -
1) indicates a default position, chosen by
124 either the windowing system or wxWidgets, depending on platform.
}
126 \docparam{size
}{The dialog size. A value of (-
1, -
1) indicates a default size, chosen by
127 either the windowing system or wxWidgets, depending on platform.
}
129 \docparam{style
}{The window style. See
\helpref{wxDialog
}{wxdialog
}.
}
131 \docparam{name
}{Used to associate a name with the window,
132 allowing the application user to set Motif resource values for
133 individual dialog boxes.
}
137 \helpref{wxDialog::Create
}{wxdialogcreate
}
139 \membersection{wxDialog::
\destruct{wxDialog
}}\label{wxdialogdtor
}
141 \func{}{\destruct{wxDialog
}}{\void}
143 Destructor. Deletes any child windows before deleting the physical window.
145 \membersection{wxDialog::Centre
}\label{wxdialogcentre
}
147 \func{void
}{Centre
}{\param{int
}{ direction = wxBOTH
}}
149 Centres the dialog box on the display.
151 \wxheading{Parameters
}
153 \docparam{direction
}{May be
{\tt wxHORIZONTAL
},
{\tt wxVERTICAL
} or
{\tt wxBOTH
}.
}
155 \membersection{wxDialog::Create
}\label{wxdialogcreate
}
157 \func{bool
}{Create
}{\param{wxWindow*
}{parent
},
\param{wxWindowID
}{id
},
\rtfsp
158 \param{const wxString\&
}{title
},
\rtfsp
159 \param{const wxPoint\&
}{pos = wxDefaultPosition
},
\rtfsp
160 \param{const wxSize\&
}{size = wxDefaultSize
},
\rtfsp
161 \param{long
}{ style = wxDEFAULT
\_DIALOG\_STYLE},
\rtfsp
162 \param{const wxString\&
}{name = ``dialogBox"
}}
164 Used for two-step dialog box construction. See
\helpref{wxDialog::wxDialog
}{wxdialogctor
}\rtfsp
167 \membersection{wxDialog::CreateButtonSizer
}\label{wxdialogcreatebuttonsizer
}
169 \func{wxSizer*
}{CreateButtonSizer
}{\param{long
}{ flags
}}
171 Creates a sizer with standard buttons.
{\it flags
} is a bit list
172 of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO
\_DEFAULT.
174 The sizer lays out the buttons in a manner appropriate to the platform.
176 This function simply calls
\helpref{CreateStdDialogButtonSizer
}{wxdialogcreatestddialogbuttonsizer
}.
178 \membersection{wxDialog::CreateStdDialogButtonSizer
}\label{wxdialogcreatestddialogbuttonsizer
}
180 \func{wxStdDialogButtonSizer*
}{CreateStdDialogButtonSizer
}{\param{long
}{ flags
}}
182 Creates a
\helpref{wxStdDialogButtonSizer
}{wxstddialogbuttonsizer
} with standard buttons.
{\it flags
} is a bit list
183 of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO
\_DEFAULT.
185 The sizer lays out the buttons in a manner appropriate to the platform.
187 \membersection{wxDialog::EndModal
}\label{wxdialogendmodal
}
189 \func{void
}{EndModal
}{\param{int
}{retCode
}}
191 Ends a modal dialog, passing a value to be returned from the
\helpref{wxDialog::ShowModal
}{wxdialogshowmodal
}\rtfsp
194 \wxheading{Parameters
}
196 \docparam{retCode
}{The value that should be returned by
{\bf ShowModal
}.
}
200 \helpref{wxDialog::ShowModal
}{wxdialogshowmodal
},
\rtfsp
201 \helpref{wxDialog::GetReturnCode
}{wxdialoggetreturncode
},
\rtfsp
202 \helpref{wxDialog::SetReturnCode
}{wxdialogsetreturncode
}
204 \membersection{wxDialog::GetReturnCode
}\label{wxdialoggetreturncode
}
206 \func{int
}{GetReturnCode
}{\void}
208 Gets the return code for this window.
212 A return code is normally associated with a modal dialog, where
\helpref{wxDialog::ShowModal
}{wxdialogshowmodal
} returns
213 a code to the application.
217 \helpref{wxDialog::SetReturnCode
}{wxdialogsetreturncode
},
\helpref{wxDialog::ShowModal
}{wxdialogshowmodal
},
\rtfsp
218 \helpref{wxDialog::EndModal
}{wxdialogendmodal
}
220 \membersection{wxDialog::GetTitle
}\label{wxdialoggettitle
}
222 \constfunc{wxString
}{GetTitle
}{\void}
224 Returns the title of the dialog box.
226 \membersection{wxDialog::Iconize
}\label{wxdialogiconized
}
228 \func{void
}{Iconize
}{\param{const bool
}{ iconize
}}
230 Iconizes or restores the dialog. Windows only.
232 \wxheading{Parameters
}
234 \docparam{iconize
}{If true, iconizes the dialog box; if false, shows and restores it.
}
238 Note that in Windows, iconization has no effect since dialog boxes cannot be
239 iconized. However, applications may need to explicitly restore dialog
240 boxes under Motif which have user-iconizable frames, and under Windows
241 calling
{\tt Iconize(false)
} will bring the window to the front, as does
242 \rtfsp{\tt Show(true)
}.
244 \membersection{wxDialog::IsIconized
}\label{wxdialogisiconized
}
246 \constfunc{bool
}{IsIconized
}{\void}
248 Returns true if the dialog box is iconized. Windows only.
252 Always returns false under Windows since dialogs cannot be iconized.
254 \membersection{wxDialog::IsModal
}\label{wxdialogismodal
}
256 \constfunc{bool
}{IsModal
}{\void}
258 Returns true if the dialog box is modal, false otherwise.
260 \membersection{wxDialog::OnApply
}\label{wxdialogonapply
}
262 \func{void
}{OnApply
}{\param{wxCommandEvent\&
}{event
}}
264 The default handler for the wxID
\_APPLY identifier.
268 This function calls
\helpref{wxWindow::Validate
}{wxwindowvalidate
} and
\helpref{wxWindow::TransferDataToWindow
}{wxwindowtransferdatatowindow
}.
272 \helpref{wxDialog::OnOK
}{wxdialogonok
},
\helpref{wxDialog::OnCancel
}{wxdialogoncancel
}
274 \membersection{wxDialog::OnCancel
}\label{wxdialogoncancel
}
276 \func{void
}{OnCancel
}{\param{wxCommandEvent\&
}{event
}}
278 The default handler for the wxID
\_CANCEL identifier.
282 The function either calls
{\bf EndModal(wxID
\_CANCEL)
} if the dialog is modal, or
283 sets the return value to wxID
\_CANCEL and calls
{\bf Show(false)
} if the dialog is modeless.
287 \helpref{wxDialog::OnOK
}{wxdialogonok
},
\helpref{wxDialog::OnApply
}{wxdialogonapply
}
289 \membersection{wxDialog::OnOK
}\label{wxdialogonok
}
291 \func{void
}{OnOK
}{\param{wxCommandEvent\&
}{event
}}
293 The default handler for the wxID
\_OK identifier.
298 \rtfsp\helpref{wxWindow::Validate
}{wxwindowvalidate
}, then
\helpref{wxWindow::TransferDataFromWindow
}{wxwindowtransferdatafromwindow
}.
299 If this returns true, the function either calls
{\bf EndModal(wxID
\_OK)
} if the dialog is modal, or
300 sets the return value to wxID
\_OK and calls
{\bf Show(false)
} if the dialog is modeless.
304 \helpref{wxDialog::OnCancel
}{wxdialogoncancel
},
\helpref{wxDialog::OnApply
}{wxdialogonapply
}
306 \membersection{wxDialog::OnSysColourChanged
}\label{wxdialogonsyscolourchanged
}
308 \func{void
}{OnSysColourChanged
}{\param{wxSysColourChangedEvent\&
}{event
}}
310 The default handler for wxEVT
\_SYS\_COLOUR\_CHANGED.
312 \wxheading{Parameters
}
314 \docparam{event
}{The colour change event.
}
318 Changes the dialog's colour to conform to the current settings (Windows only).
319 Add an event table entry for your dialog class if you wish the behaviour
320 to be different (such as keeping a user-defined
321 background colour). If you do override this function, call wxEvent::Skip to
322 propagate the notification to child windows and controls.
326 \helpref{wxSysColourChangedEvent
}{wxsyscolourchangedevent
}
328 \membersection{wxDialog::SetIcon
}\label{wxdialogseticon
}
330 \func{void
}{SetIcon
}{\param{const wxIcon\&
}{icon
}}
332 Sets the icon for this dialog.
334 \wxheading{Parameters
}
336 \docparam{icon
}{The icon to associate with this dialog.
}
338 See also
\helpref{wxIcon
}{wxicon
}.
340 \membersection{wxDialog::SetIcons
}\label{wxdialogseticons
}
342 \func{void
}{SetIcons
}{\param{const wxIconBundle\&
}{icons
}}
344 Sets the icons for this dialog.
346 \wxheading{Parameters
}
348 \docparam{icons
}{The icons to associate with this dialog.
}
350 See also
\helpref{wxIconBundle
}{wxiconbundle
}.
352 \membersection{wxDialog::SetModal
}\label{wxdialogsetmodal
}
354 \func{void
}{SetModal
}{\param{const bool
}{ flag
}}
356 {\bf NB:
} This function is deprecated and doesn't work for all ports, just use
357 \helpref{ShowModal
}{wxdialogshowmodal
} to show a modal dialog instead.
359 Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control
360 until the dialog is hidden) or modeless (control returns immediately).
362 \wxheading{Parameters
}
364 \docparam{flag
}{If true, the dialog will be modal, otherwise it will be modeless.
}
366 \membersection{wxDialog::SetReturnCode
}\label{wxdialogsetreturncode
}
368 \func{void
}{SetReturnCode
}{\param{int
}{retCode
}}
370 Sets the return code for this window.
372 \wxheading{Parameters
}
374 \docparam{retCode
}{The integer return code, usually a control identifier.
}
378 A return code is normally associated with a modal dialog, where
\helpref{wxDialog::ShowModal
}{wxdialogshowmodal
} returns
379 a code to the application. The function
\helpref{wxDialog::EndModal
}{wxdialogendmodal
} calls
{\bf SetReturnCode
}.
383 \helpref{wxDialog::GetReturnCode
}{wxdialoggetreturncode
},
\helpref{wxDialog::ShowModal
}{wxdialogshowmodal
},
\rtfsp
384 \helpref{wxDialog::EndModal
}{wxdialogendmodal
}
386 \membersection{wxDialog::SetTitle
}\label{wxdialogsettitle
}
388 \func{void
}{SetTitle
}{\param{const wxString\&
}{ title
}}
390 Sets the title of the dialog box.
392 \wxheading{Parameters
}
394 \docparam{title
}{The dialog box title.
}
396 \membersection{wxDialog::Show
}\label{wxdialogshow
}
398 \func{bool
}{Show
}{\param{const bool
}{ show
}}
400 Hides or shows the dialog.
402 \wxheading{Parameters
}
404 \docparam{show
}{If true, the dialog box is shown and brought to the front;
405 otherwise the box is hidden. If false and the dialog is
406 modal, control is returned to the calling program.
}
410 The preferred way of dismissing a modal dialog is to use
\helpref{wxDialog::EndModal
}{wxdialogendmodal
}.
412 \membersection{wxDialog::ShowModal
}\label{wxdialogshowmodal
}
414 \func{int
}{ShowModal
}{\void}
416 Shows a modal dialog. Program flow does not return until the dialog has been dismissed with
\rtfsp
417 \helpref{wxDialog::EndModal
}{wxdialogendmodal
}.
419 \wxheading{Return value
}
421 The return value is the value set with
\helpref{wxDialog::SetReturnCode
}{wxdialogsetreturncode
}.
425 \helpref{wxDialog::EndModal
}{wxdialogendmodal
},
\rtfsp
426 \helpref{wxDialog:GetReturnCode
}{wxdialoggetreturncode
},
\rtfsp
427 \helpref{wxDialog::SetReturnCode
}{wxdialogsetreturncode
}