docs/latex/wx/dialog.tex

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