documentation for window ids allocation and wxIdManager (patch 1870570)

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

diff --git a/docs/latex/wx/dialog.tex b/docs/latex/wx/dialog.tex
index 6e9e17d8b4e1bf71f3586bb7845356452c3614c6..f6fa0d826100714ba1b8f62d064879a255c22a60 100644 (file)
--- a/docs/latex/wx/dialog.tex
+++ b/docs/latex/wx/dialog.tex
@@ -13,7 +13,24 @@
 
 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
 
 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}
 
 
 \wxheading{Derived from}
 


@@ -26,7 +43,11 @@ is usually used to allow the user to make some choice or to answer a question.
 
 <wx/dialog.h>
 
 
 <wx/dialog.h>
 

-\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,
 
 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,


@@ -155,6 +176,22 @@ individual dialog boxes.}
 
 Destructor. Deletes any child windows before deleting the physical window.
 
 
 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}
 
 
 \membersection{wxDialog::Centre}\label{wxdialogcentre}
 


@@ -185,7 +222,8 @@ for details.
 \func{wxSizer*}{CreateButtonSizer}{\param{long}{ flags}}
 
 Creates a sizer with standard buttons. {\it flags} is a bit list
 \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.
 
 
 The sizer lays out the buttons in a manner appropriate to the platform.
 


@@ -213,10 +251,18 @@ if no buttons were created.
 \func{wxStdDialogButtonSizer*}{CreateStdDialogButtonSizer}{\param{long}{ flags}}
 
 Creates a \helpref{wxStdDialogButtonSizer}{wxstddialogbuttonsizer} with standard buttons. {\it flags} is a bit list
 \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.
 
 
 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}
 
 
 \membersection{wxDialog::DoOK}\label{wxdialogdook}
 


@@ -227,6 +273,14 @@ 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.
 
 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}
 
 
 \membersection{wxDialog::EndModal}\label{wxdialogendmodal}
 


@@ -257,6 +311,13 @@ dialog.
 
 \helpref{wxDialog::SetAffirmativeId}{wxdialogsetaffirmativeid}
 
 
 \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}
 
 
 \membersection{wxDialog::GetEscapeId}\label{wxdialoggetescapeid}
 


@@ -270,6 +331,50 @@ button to.
 \helpref{wxDialog::SetEscapeId}{wxdialogsetescapeid}
 
 
 \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}
 \membersection{wxDialog::GetReturnCode}\label{wxdialoggetreturncode}
 
 \func{int}{GetReturnCode}{\void}


@@ -300,7 +405,7 @@ This function is not available on any other platform.
 
 \membersection{wxDialog::Iconize}\label{wxdialogiconized}
 
 
 \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.
 
 
 Iconizes or restores the dialog. Windows only.
 


@@ -328,60 +433,30 @@ Returns true if the dialog box is iconized. Windows only.
 Always returns false under Windows since dialogs cannot be iconized.
 
 
 Always returns false under Windows since dialogs cannot be iconized.
 
 

-\membersection{wxDialog::IsModal}\label{wxdialogismodal}
+\membersection{wxDialog::IsLayoutAdaptationEnabled}\label{wxdialogislayoutadaptationenabled}

 
 

-\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::TransferDataFromWindow}{wxwindowtransferdatafromwindow}.
-
-\wxheading{See also}
-
-\helpref{wxDialog::OnOK}{wxdialogonok}, \helpref{wxDialog::OnCancel}{wxdialogoncancel}
+\func{static bool}{IsLayoutAdaptationEnabled}{\void}

 
 

+A static function returning \true if layout adaptation is enabled for all dialogs.

 
 

-\membersection{wxDialog::OnCancel}\label{wxdialogoncancel}
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.

 
 

-\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::IsMainButton}\label{wxdialogismainbutton}

 
 

+\constfunc{bool}{IsMainButton}{\param{wxWindowID\& }{id}}

 
 

-\membersection{wxDialog::OnOK}\label{wxdialogonok}
+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.

 
 

-\func{void}{OnOK}{\param{wxCommandEvent\& }{event}}
+See also \helpref{Automatic scrolling dialogs}{autoscrollingdialogs} for more on layout adaptation.

 
 

-The default handler for the wxID\_OK identifier.

 
 

-\wxheading{Remarks}
+\membersection{wxDialog::IsModal}\label{wxdialogismodal}

 
 

-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.
+\constfunc{bool}{IsModal}{\void}

 
 

-\wxheading{See also}
+Returns true if the dialog box is modal, false otherwise.

 
 

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

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


@@ -472,9 +547,56 @@ Sets the icons for this dialog.
 See also \helpref{wxIconBundle}{wxiconbundle}.
 
 
 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}
 
 \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
 \helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead.
 
 {\bf NB:} This function is deprecated and doesn't work for all ports, just use
 \helpref{ShowModal}{wxdialogshowmodal} to show a modal dialog instead.


@@ -510,7 +632,7 @@ a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogend
 
 \membersection{wxDialog::Show}\label{wxdialogshow}
 
 
 \membersection{wxDialog::Show}\label{wxdialogshow}
 

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

 
 Hides or shows the dialog.
 
 
 Hides or shows the dialog.
 


@@ -541,3 +663,4 @@ The return value is the value set with \helpref{wxDialog::SetReturnCode}{wxdialo
 \helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
 \helpref{wxDialog:GetReturnCode}{wxdialoggetreturncode},\rtfsp
 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}
 \helpref{wxDialog::EndModal}{wxdialogendmodal},\rtfsp
 \helpref{wxDialog:GetReturnCode}{wxdialoggetreturncode},\rtfsp
 \helpref{wxDialog::SetReturnCode}{wxdialogsetreturncode}

+