wxSize/wxPoint/wxRect versions of functions added to wxMSW, wxMotif;

[wxWidgets.git] / docs / latex / wx / dialog.tex

\section{\class{wxDialog}}\label{wxdialog}

A dialog box is a window with a title bar and sometimes a system menu, which can be moved around
the screen. It can contain controls and other windows.

\wxheading{Derived from}

\helpref{wxPanel}{wxpanel}\\
\helpref{wxWindow}{wxwindow}\\
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}

\wxheading{Remarks}

There are two kinds of dialog - {\it modal} and {\it modeless}. A modal dialog
blocks program flow and user input on other windows until it is dismissed, whereas a modeless dialog behaves more
like a frame in that program flow continues, and input on other windows is still possible.
You specify the type of dialog with the {\bf wxDIALOG\_MODAL} and {\bf wxDIALOG\_MODELESS} window
styles.

A dialog may be loaded from a wxWindows resource file (extension {\tt wxr}).

An application can define an \helpref{OnCloseWindow}{wxwindowonclosewindow} handler for the
dialog to respond to system close events.

\wxheading{Window styles}

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{wxCAPTION}}{Puts a caption on the dialog box (Motif only).}
\twocolitem{\windowstyle{wxDEFAULT\_DIALOG\_STYLE}}{Equivalent to a combination of wxCAPTION, wxSYSTEM\_MENU and wxTHICK\_FRAME}
\twocolitem{\windowstyle{wxRESIZE\_BORDER}}{Display a resizeable frame around the window (Motif only).}
\twocolitem{\windowstyle{wxSYSTEM\_MENU}}{Display a system menu.}
\twocolitem{\windowstyle{wxTHICK\_FRAME}}{Display a thick frame around the window.}
\twocolitem{\windowstyle{wxSTAY\_ON\_TOP}}{The dialog stays on top of all other windows (Windows only).}
\twocolitem{\windowstyle{wxNO\_3D}}{Under Windows, specifies that the child controls
should not have 3D borders unless specified in the control.}
\end{twocollist}

Under Motif, MWM (the Motif Window Manager) should be running for any of these styles to have an effect.

See also \helpref{Generic window styles}{windowstyles}.

\wxheading{See also}

\helpref{wxDialog overview}{wxdialogoverview}, \helpref{wxFrame}{wxframe}, \helpref{Resources}{resources},\rtfsp
\helpref{Validator overview}{validatoroverview}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDialog::wxDialog}\label{wxdialogconstr}

\func{}{wxDialog}{\void}

Default constructor.

\func{}{wxDialog}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
\param{const wxString\& }{title},\rtfsp
\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
\param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp
\param{const wxString\& }{name = ``dialogBox"}}

Constructor.

\wxheading{Parameters}

\docparam{parent}{Can be NULL, a frame or another dialog box.}

\docparam{id}{An identifier for the dialog. A value of -1 is taken to mean a default.}

\docparam{title}{The title of the dialog.}

\docparam{pos}{The dialog position. A value of (-1, -1) indicates a default position, chosen by
either the windowing system or wxWindows, depending on platform.}

\docparam{size}{The dialog size. A value of (-1, -1) indicates a default size, chosen by
either the windowing system or wxWindows, depending on platform.}

\docparam{style}{The window style. See \helpref{wxDialog}{wxdialog}.}

\docparam{name}{Used to associate a name with the window,
allowing the application user to set Motif resource values for
individual dialog boxes.}

\wxheading{See also}

\helpref{wxDialog::Create}{wxdialogcreate}

\membersection{wxDialog::\destruct{wxDialog}}

\func{}{\destruct{wxDialog}}{\void}

Destructor. Deletes any child windows before deleting the physical window.

\membersection{wxDialog::Centre}\label{wxdialogcentre}

\func{void}{Centre}{\param{int}{ direction = wxBOTH}}

Centres the dialog box on the display.

\wxheading{Parameters}

\docparam{direction}{May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL} or {\tt wxBOTH}.}

\membersection{wxDialog::Create}\label{wxdialogcreate}

\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
\param{const wxString\& }{title},\rtfsp
\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
\param{long}{ style = wxDEFAULT\_DIALOG\_STYLE},\rtfsp
\param{const wxString\& }{name = ``dialogBox"}}

Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogconstr}\rtfsp
for details.

\membersection{wxDialog::EndModal}\label{wxdialogendmodal}

\func{void}{EndModal}{\param{int }{retCode}}

Ends a modal dialog, passing a value to be returned from the \helpref{wxDialog::ShowModal}{wxdialogshowmodal}\rtfsp
invocation.

\wxheading{Parameters}

\docparam{retCode}{The value that should be returned by {\bf ShowModal}.}

\wxheading{See also}

\helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
\helpref{wxWindow::GetReturnCode}{wxwindowgetreturncode},\rtfsp
\helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}

\membersection{wxDialog::GetTitle}\label{wxdialoggettitle}

\constfunc{wxString}{GetTitle}{\void}

Returns the title of the dialog box.

\membersection{wxDialog::Iconize}\label{wxdialogiconized}

\func{void}{Iconize}{\param{const bool}{ iconize}}

Iconizes or restores the dialog.

\wxheading{Parameters}

\docparam{iconize}{If TRUE, iconizes the dialog box; if FALSE, shows and restores it.}

\wxheading{Remarks}

Note that in Windows, iconization has no effect since dialog boxes cannot be
iconized. However, applications may need to explicitly restore dialog
boxes under Motif which have user-iconizable frames, and under Windows
calling {\tt Iconize(FALSE)} will bring the window to the front, as does
\rtfsp{\tt Show(TRUE)}.

\membersection{wxDialog::IsIconized}\label{wxdialogisiconized}

\constfunc{bool}{IsIconized}{\void}

Returns TRUE if the dialog box is iconized.

\wxheading{Remarks}

Always returns FALSE under Windows since dialogs cannot be iconized.

\membersection{wxDialog::IsModal}\label{wxdialogismodal}

\constfunc{bool}{IsModal}{\void}

Returns TRUE if the dialog box is modal, FALSE otherwise.

\membersection{wxDialog::OnCharHook}\label{wxdialogoncharhook}

\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}}

This member is called to allow the window to intercept keyboard events
before they are processed by child windows.

For more information, see \helpref{wxWindow::OnCharHook}{wxwindowoncharhook}

\wxheading{Remarks}

wxDialog implements this handler to fake a cancel command if the escape key has been
pressed. This will dismiss the dialog.

\membersection{wxDialog::OnApply}\label{wxdialogonapply}

\func{void}{OnApply}{\param{wxCommandEvent\& }{event}}

The default handler for the wxID\_APPLY identifier.

\wxheading{Remarks}

This function calls \helpref{wxWindow::Validate}{wxwindowvalidate} and \helpref{wxWindow::TransferDataToWindow}{wxwindowtransferdatatowindow}.

\wxheading{See also}

\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel}

\membersection{wxDialog::OnCancel}\label{wxdialogoncancel}

\func{void}{OnCancel}{\param{wxCommandEvent\& }{event}}

The default handler for the wxID\_CANCEL identifier.

\wxheading{Remarks}

The function either calls {\bf EndModal(wxID\_CANCEL)} if the dialog is modal, or
sets the return value to wxID\_CANCEL and calls {\bf Show(FALSE)} if the dialog is modeless.

\wxheading{See also}

\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnApply}{wxdialogonapply}

\membersection{wxDialog::OnOK}\label{wxdialogonok}

\func{void}{OnOK}{\param{wxCommandEvent\& }{event}}

The default handler for the wxID\_OK identifier.

\wxheading{Remarks}

The function calls
\rtfsp\helpref{wxWindow::Validate}{wxwindowvalidate}, then \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow}.
If this returns TRUE, the function either calls {\bf EndModal(wxID\_OK)} if the dialog is modal, or
sets the return value to wxID\_OK and calls {\bf Show(FALSE)} if the dialog is modeless.

\wxheading{See also}

\helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply}

\membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged}

\func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}}

The default handler for wxEVT\_SYS\_COLOUR\_CHANGED.

\wxheading{Parameters}

\docparam{event}{The colour change event.}

\wxheading{Remarks}

Changes the dialog's colour to conform to the current settings (Windows only).
Add an event table entry for your dialog class if you wish the behaviour
to be different (such as keeping a user-defined
background colour). If you do override this function, call \helpref{wxWindow::OnSysColourChanged}{wxwindowonsyscolourchanged} to
propagate the notification to child windows and controls.

\wxheading{See also}

\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}

\membersection{wxDialog::SetModal}\label{wxdialogsetmodal}

\func{void}{SetModal}{\param{const bool}{ flag}}

Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control
until the dialog is hidden) or modeless (control returns immediately).

\wxheading{Parameters}

\docparam{flag}{If TRUE, the dialog will be modal, otherwise it will be modeless.}

\membersection{wxDialog::SetTitle}\label{wxdialogsettitle}

\func{void}{SetTitle}{\param{const wxString\& }{ title}}

Sets the title of the dialog box.

\wxheading{Parameters}

\docparam{title}{The dialog box title.}

\membersection{wxDialog::Show}\label{wxdialogshow}

\func{bool}{Show}{\param{const bool}{ show}}

Hides or shows the dialog.

\wxheading{Parameters}

\docparam{show}{If TRUE, the dialog box is shown and brought to the front;
otherwise the box is hidden. If FALSE and the dialog is
modal, control is returned to the calling program.}

\wxheading{Remarks}

The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}.

\membersection{wxDialog::ShowModal}\label{wxdialogshowmodal}

\func{int}{ShowModal}{\void}

Shows a modal dialog. Program flow does not return until the dialog has been dismissed with\rtfsp
\helpref{wxDialog::EndModal}{wxdialogendmodal}.

\wxheading{Return value}

The return value is the value set with \helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}.

\wxheading{See also}

\helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
\helpref{wxWindow::GetReturnCode}{wxwindowgetreturncode},\rtfsp
\helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}