X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3faa8195d724c3951a6becd501c989ac3c3906ef..b3a029f0bbf8262cfe30914790802f88608ea618:/docs/latex/wx/dialog.tex diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex index 7d3b71676d..f6fa0d8261 100644 --- a/docs/latex/wx/dialog.tex +++ b/docs/latex/wx/dialog.tex @@ -1,8 +1,36 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: dialog.tex +%% Purpose: wxDialog documentation +%% Author: wxWidgets Team +%% Modified by: +%% Created: +%% RCS-ID: $Id$ +%% Copyright: (c) wxWidgets Team +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \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 and -is usually used to allow the user to make some choice or to answer a question. +is often used to allow the user to make some choice or to answer a question. + +Dialogs can be made scrollable, automatically: please see \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for further details. + +\wxheading{Dialog Buttons} + +The dialog usually contains either a single button allowing to close the +dialog or two buttons, one accepting the changes and the other one discarding +them (such button, if present, is automatically activated if the user presses +the \texttt{"Esc"} key). By default, buttons with the standard \texttt{wxID\_OK} +and \texttt{wxID\_CANCEL} identifiers behave as expected. Starting with +wxWidgets 2.7 it is also possible to use a button with a different identifier +instead, see \helpref{SetAffirmativeId}{wxdialogsetaffirmativeid} and +\helpref{SetEscapeId}{wxdialogsetescapeid}. + +Also notice that the \helpref{CreateButtonSizer()}{wxdialogcreatebuttonsizer} +should be used to create the buttons appropriate for the current platform and +positioned correctly (including their order which is platform-dependent). \wxheading{Derived from} @@ -15,7 +43,11 @@ is usually used to allow the user to make some choice or to answer a question. -\wxheading{Remarks} +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + +\wxheading{Modal and modeless dialogs} 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, @@ -74,7 +106,7 @@ the dialog to respond to system close events. \twocolitem{\windowstyle{wxNO\_3D}}{Under Windows, specifies that the child controls should not have 3D borders unless specified in the control.} \twocolitem{\windowstyle{wxDIALOG\_NO\_PARENT}}{By default, a dialog created -with a {\tt NULL} parent window will be given the +with a {\tt NULL} parent window will be given the \helpref{application's top level window}{wxappgettopwindow} as parent. Use this style to prevent this from happening and create an orphan dialog. This is not recommended for modal dialogs.} \twocolitem{\windowstyle{wxDIALOG\_EX\_CONTEXTHELP}}{Under Windows, puts a query button on the @@ -97,6 +129,7 @@ See also \helpref{Generic window styles}{windowstyles}. \latexignore{\rtfignore{\wxheading{Members}}} + \membersection{wxDialog::wxDialog}\label{wxdialogctor} \func{}{wxDialog}{\void} @@ -136,12 +169,30 @@ individual dialog boxes.} \helpref{wxDialog::Create}{wxdialogcreate} + \membersection{wxDialog::\destruct{wxDialog}}\label{wxdialogdtor} \func{}{\destruct{wxDialog}}{\void} Destructor. Deletes any child windows before deleting the physical window. +\membersection{wxDialog::AddMainButtonId}\label{wxdialogaddmainbuttonid} + +\func{void}{AddMainButtonId}{\param{wxWindowID}{ id}} + +Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + +\membersection{wxDialog::CanDoLayoutAdaptation}\label{wxdialogcandolayoutadaptation} + +\func{bool}{CanDoLayoutAdapation}{\void} + +Returns \true if this dialog can and should perform layout adaptation using \helpref{DoLayoutAdaptation}{wxdialogdolayoutadaptation}, usually if +the dialog is too large to fit on the display. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + \membersection{wxDialog::Centre}\label{wxdialogcentre} \func{void}{Centre}{\param{int}{ direction = wxBOTH}} @@ -152,6 +203,7 @@ Centres the dialog box on the display. \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 @@ -164,26 +216,54 @@ Centres the dialog box on the display. Used for two-step dialog box construction. See \helpref{wxDialog::wxDialog}{wxdialogctor}\rtfsp for details. + \membersection{wxDialog::CreateButtonSizer}\label{wxdialogcreatebuttonsizer} \func{wxSizer*}{CreateButtonSizer}{\param{long}{ flags}} Creates a sizer with standard buttons. {\it flags} is a bit list -of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO\_DEFAULT. +of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, +wxHELP, wxNO\_DEFAULT. The sizer lays out the buttons in a manner appropriate to the platform. -This function simply calls \helpref{CreateStdDialogButtonSizer}{wxdialogcreatestddialogbuttonsizer}. +This function uses \helpref{CreateStdDialogButtonSizer}{wxdialogcreatestddialogbuttonsizer} +internally for most platforms but doesn't create the sizer at all for the +platforms with hardware buttons (such as smartphones) for which it sets up the +hardware buttons appropriately and returns \NULL, so don't forget to test that +the return value is valid before using it. + + +\membersection{wxDialog::CreateSeparatedButtonSizer}\label{wxdialogcreateseparatedbuttonsizer} + +\func{wxSizer*}{CreateSeparatedButtonSizer}{\param{long}{ flags}} + +Creates a sizer with standard buttons using +\helpref{CreateButtonSizer}{wxdialogcreatebuttonsizer} separated from the rest +of the dialog contents by a horizontal \helpref{wxStaticLine}{wxstaticline}. + +Please notice that just like CreateButtonSizer() this function may return \NULL +if no buttons were created. + \membersection{wxDialog::CreateStdDialogButtonSizer}\label{wxdialogcreatestddialogbuttonsizer} \func{wxStdDialogButtonSizer*}{CreateStdDialogButtonSizer}{\param{long}{ flags}} Creates a \helpref{wxStdDialogButtonSizer}{wxstddialogbuttonsizer} with standard buttons. {\it flags} is a bit list -of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO\_DEFAULT. +of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, +wxHELP, wxNO\_DEFAULT. The sizer lays out the buttons in a manner appropriate to the platform. +\membersection{wxDialog::DoLayoutAdaptation}\label{wxdialogdolayoutadaptation} + +\func{bool}{DoLayoutAdapation}{\void} + +Performs layout adaptation, usually if the dialog is too large to fit on the display. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + \membersection{wxDialog::DoOK}\label{wxdialogdook} \func{virtual bool}{DoOK}{\void} @@ -193,6 +273,15 @@ A command event for the identifier returned by GetAffirmativeId is sent by default. You can override this function. If the function returns false, wxWidgets will call Close() for the dialog. +\membersection{wxDialog::EnableLayoutAdaptation}\label{wxdialogenablelayoutadaptation} + +\func{static void}{EnableLayoutAdaptation}{\param{bool}{ enable}} + +A static function enabling or disabling layout adaptation for all dialogs. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + \membersection{wxDialog::EndModal}\label{wxdialogendmodal} \func{void}{EndModal}{\param{int }{retCode}} @@ -210,16 +299,82 @@ invocation. \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode},\rtfsp \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode} + \membersection{wxDialog::GetAffirmativeId}\label{wxdialoggetaffirmativeid} \constfunc{int}{GetAffirmativeId}{\void} -Gets the identifier to be used when the user presses an OK button in a PocketPC titlebar. +Gets the identifier of the button which works like standard OK button in this +dialog. \wxheading{See also} \helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid} +\membersection{wxDialog::GetContentWindow}\label{wxdialoggetcontentwindow} + +\constfunc{wxWindow*}{GetContentWindow}{\void} + +Override this to return a window containing the main content of the dialog. This is +particularly useful when the dialog implements pages, such as wxPropertySheetDialog, +and allows the \helpref{layout adaptation code}{wxdialogoverview} to know that only the pages need to be made scrollable. + +\membersection{wxDialog::GetEscapeId}\label{wxdialoggetescapeid} + +\constfunc{int}{GetEscapeId}{\void} + +Gets the identifier of the button to map presses of \texttt{\textsc{ESC}} +button to. + +\wxheading{See also} + +\helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid} + + +\membersection{wxDialog::GetLayoutAdaptationDone}\label{wxdialoggetlayoutadaptationdone} + +\constfunc{bool}{GetLayoutAdaptationDone}{\void} + +Returns \true if the dialog has been adapted, usually by making it scrollable to work with a small display. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::GetLayoutAdaptationLevel}\label{wxdialoggetlayoutadaptationlevel} + +\func{int}{GetLayoutAdaptationLevel}{\void} + +Gets a value representing the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog. +Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::GetLayoutAdaptationMode}\label{wxdialoggetlayoutadaptationmode} + +\constfunc{wxDialogLayoutAdaptationMode}{GetLayoutAdaptationMode}{\void} + +Gets the adaptation mode, overriding the global adaptation flag. + +See also \helpref{SetLayoutAdaptationMode}{wxdialogsetlayoutadaptationmode} and \helpref{Automatic scrolling dialogs}{autoscrollingdialogs}. + +\membersection{wxDialog::GetLayoutAdapter}\label{wxdialoggetlayoutadapter} + +\func{static wxDialogLayoutAdapter*}{GetLayoutAdapter}{\void} + +A static function getting the current layout adapter object. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::GetMainButtonIds}\label{wxdialoggetmainbuttonids} + +\func{wxArrayInt\&}{GetMainButtonIds}{\void} + +Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + \membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode} \func{int}{GetReturnCode}{\void} @@ -236,11 +391,6 @@ a code to the application. \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp \helpref{wxDialog::EndModal}{wxdialogendmodal} -\membersection{wxDialog::GetTitle}\label{wxdialoggettitle} - -\constfunc{wxString}{GetTitle}{\void} - -Returns the title of the dialog box. \membersection{wxDialog::GetToolBar}\label{wxdialoggettoolbar} @@ -252,9 +402,10 @@ arbitrary controls are not currently supported. This function is not available on any other platform. + \membersection{wxDialog::Iconize}\label{wxdialogiconized} -\func{void}{Iconize}{\param{const bool}{ iconize}} +\func{void}{Iconize}{\param{bool}{ iconize}} Iconizes or restores the dialog. Windows only. @@ -270,6 +421,7 @@ 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} @@ -280,57 +432,32 @@ Returns true if the dialog box is iconized. Windows only. 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::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} +\membersection{wxDialog::IsLayoutAdaptationEnabled}\label{wxdialogislayoutadaptationenabled} -\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel} +\func{static bool}{IsLayoutAdaptationEnabled}{\void} -\membersection{wxDialog::OnCancel}\label{wxdialogoncancel} +A static function returning \true if layout adaptation is enabled for all dialogs. -\func{void}{OnCancel}{\param{wxCommandEvent\& }{event}} +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. -The default handler for the wxID\_CANCEL identifier. -\wxheading{Remarks} +\membersection{wxDialog::IsMainButton}\label{wxdialogismainbutton} -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. +\constfunc{bool}{IsMainButton}{\param{wxWindowID\& }{id}} -\wxheading{See also} +Returns \true if {\it id} is in the array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog. -\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnApply}{wxdialogonapply} +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. -\membersection{wxDialog::OnOK}\label{wxdialogonok} -\func{void}{OnOK}{\param{wxCommandEvent\& }{event}} - -The default handler for the wxID\_OK identifier. +\membersection{wxDialog::IsModal}\label{wxdialogismodal} -\wxheading{Remarks} +\constfunc{bool}{IsModal}{\void} -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. +Returns true if the dialog box is modal, false otherwise. -\wxheading{See also} -\helpref{wxDialog::OnCancel}{wxdialogoncancel}, \helpref{wxDialog::OnApply}{wxdialogonapply} \membersection{wxDialog::OnSysColourChanged}\label{wxdialogonsyscolourchanged} @@ -354,16 +481,45 @@ propagate the notification to child windows and controls. \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent} + \membersection{wxDialog::SetAffirmativeId}\label{wxdialogsetaffirmativeid} \func{void}{SetAffirmativeId}{\param{int }{id}} -Sets the identifier to be used when the user presses an OK button in a PocketPC titlebar. -By default, this is wxID\_OK. +Sets the identifier to be used as OK button. When the button with this +identifier is pressed, the dialog calls \helpref{Validate}{wxwindowvalidate} +and \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow} +and, if they both return \true, closes the dialog with \texttt{wxID\_OK} return +code. + +Also, when the user presses a hardware OK button on the devices having one or +the special OK button in the PocketPC title bar, an event with this id is +generated. + +By default, the affirmative id is wxID\_OK. \wxheading{See also} -\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid} +\helpref{wxDialog::GetAffirmativeId}{wxdialoggetaffirmativeid}, \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid} + + +\membersection{wxDialog::SetEscapeId}\label{wxdialogsetescapeid} + +\func{void}{SetEscapeId}{\param{int }{id}} + +Sets the identifier of the button which should work like the standard +\texttt{\textsc{Cancel}} button in this dialog. When the button with this id is +clicked, the dialog is closed. Also, when the user presses \texttt{\textsc{ESC}} +key in the dialog or closes the dialog using the close button in the title bar, +this is mapped to the click of the button with the specified id. + +By default, the escape id is the special value \texttt{wxID\_ANY} meaning that +\texttt{wxID\_CANCEL} button is used if it's present in the dialog and +otherwise the button with \helpref{GetAffirmativeId()}{wxdialoggetaffirmativeid} +is used. Another special value for \arg{id} is \texttt{wxID\_NONE} meaning that +\texttt{\textsc{ESC}} presses should be ignored. If any other value is given, it +is interpreted as the id of the button to map the escape key to. + \membersection{wxDialog::SetIcon}\label{wxdialogseticon} @@ -377,6 +533,7 @@ Sets the icon for this dialog. See also \helpref{wxIcon}{wxicon}. + \membersection{wxDialog::SetIcons}\label{wxdialogseticons} \func{void}{SetIcons}{\param{const wxIconBundle\& }{icons}} @@ -389,11 +546,59 @@ Sets the icons for this dialog. See also \helpref{wxIconBundle}{wxiconbundle}. + +\membersection{wxDialog::SetLayoutAdaptationDone}\label{wxdialogsetlayoutadaptationdone} + +\func{void}{SetLayoutAdaptationDone}{\param{bool }{done}} + +Marks the dialog as having been adapted, usually by making it scrollable to work with a small display. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::SetLayoutAdaptationLevel}\label{wxdialogsetlayoutadaptationlevel} + +\func{void}{SetLayoutAdaptationLevel}{\param{int }{level}} + +Sets the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog. +Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog. + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::SetLayoutAdaptationMode}\label{wxdialogsetlayoutadaptationmode} + +\func{void}{SetLayoutAdaptationMode}{\param{wxDialogLayoutAdaptationMode }{mode}} + +Sets the adaptation mode, overriding the global adaptation flag. {\it mode} may be one of the following values: + +\begin{verbatim} +enum wxDialogLayoutAdaptationMode +{ + wxDIALOG_ADAPTATION_MODE_DEFAULT = 0, // use global adaptation enabled status + wxDIALOG_ADAPTATION_MODE_ENABLED = 1, // enable this dialog overriding global status + wxDIALOG_ADAPTATION_MODE_DISABLED = 2 // disable this dialog overriding global status +}; +\end{verbatim} + +See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation. + + +\membersection{wxDialog::SetLayoutAdapter}\label{wxdialogsetlayoutadapter} + +\func{static wxDialogLayoutAdapter*}{SetLayoutAdapter}{\param{wxDialogLayoutAdapter*}{ adapter}} + +A static function for setting the current layout adapter object, returning the old adapter. If you call this, you should +delete the old adapter object. + +See also \helpref{wxDialogLayoutAdapter}{wxdialoglayoutadapter} and \helpref{Automatic scrolling dialogs}{autoscrollingdialogs}. + + \membersection{wxDialog::SetModal}\label{wxdialogsetmodal} -\func{void}{SetModal}{\param{const bool}{ flag}} +\func{void}{SetModal}{\param{bool}{ flag}} -{\bf NB:} This function is deprecated and doesn't work for all ports, just use +{\bf NB:} This function is deprecated and doesn't work for all ports, just use \helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead. Allows the programmer to specify whether the dialog box is modal (wxDialog::Show blocks control @@ -403,6 +608,7 @@ until the dialog is hidden) or modeless (control returns immediately). \docparam{flag}{If true, the dialog will be modal, otherwise it will be modeless.} + \membersection{wxDialog::SetReturnCode}\label{wxdialogsetreturncode} \func{void}{SetReturnCode}{\param{int }{retCode}} @@ -423,19 +629,10 @@ a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogend \helpref{wxDialog::GetReturnCode}{wxdialoggetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp \helpref{wxDialog::EndModal}{wxdialogendmodal} -\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}} +\func{bool}{Show}{\param{bool}{ show}} Hides or shows the dialog. @@ -449,6 +646,7 @@ modal, control is returned to the calling program.} The preferred way of dismissing a modal dialog is to use \helpref{wxDialog::EndModal}{wxdialogendmodal}. + \membersection{wxDialog::ShowModal}\label{wxdialogshowmodal} \func{int}{ShowModal}{\void}