1. wxWindow::IsTopLevel() added and documented

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

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 22a2375ef0d57f7f1147a86fccff3a830e86584b..32d23e45ec807fd213b636a77d9e0bc19eb790e1 100644 (file)
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -21,20 +21,20 @@ window class.
 \twocolwidtha{5cm}%
 \begin{twocollist}\itemsep=0pt
 \twocolitem{\windowstyle{wxSIMPLE\_BORDER}}{Displays a thin border around the window. wxBORDER is the old name
 \twocolwidtha{5cm}%
 \begin{twocollist}\itemsep=0pt
 \twocolitem{\windowstyle{wxSIMPLE\_BORDER}}{Displays a thin border around the window. wxBORDER is the old name

-for this style.}
+for this style. Windows only. }

 \twocolitem{\windowstyle{wxDOUBLE\_BORDER}}{Displays a double border. Windows only.}
 \twocolitem{\windowstyle{wxSUNKEN\_BORDER}}{Displays a sunken border.}
 \twocolitem{\windowstyle{wxRAISED\_BORDER}}{Displays a raised border.}
 \twocolitem{\windowstyle{wxDOUBLE\_BORDER}}{Displays a double border. Windows only.}
 \twocolitem{\windowstyle{wxSUNKEN\_BORDER}}{Displays a sunken border.}
 \twocolitem{\windowstyle{wxRAISED\_BORDER}}{Displays a raised border.}

-\twocolitem{\windowstyle{wxSTATIC\_BORDER}}{Displays a border suitable for a static control.}
+\twocolitem{\windowstyle{wxSTATIC\_BORDER}}{Displays a border suitable for a static control. Windows only. }

 \twocolitem{\windowstyle{wxTRANSPARENT\_WINDOW}}{The window is transparent, that is, it will not receive paint
 events. Windows only.}
 \twocolitem{\windowstyle{wxNO\_3D}}{Prevents the children of this window taking on 3D styles, even though
 the application-wide policy is for 3D controls. Windows only.}
 \twocolitem{\windowstyle{wxTAB\_TRAVERSAL}}{Use this to enable tab traversal for non-dialog windows.}
 \twocolitem{\windowstyle{wxTRANSPARENT\_WINDOW}}{The window is transparent, that is, it will not receive paint
 events. Windows only.}
 \twocolitem{\windowstyle{wxNO\_3D}}{Prevents the children of this window taking on 3D styles, even though
 the application-wide policy is for 3D controls. Windows only.}
 \twocolitem{\windowstyle{wxTAB\_TRAVERSAL}}{Use this to enable tab traversal for non-dialog windows.}

-\twocolitem{\windowstyle{wxVSCROLL}}{Use this style to enable a vertical scrollbar.}
-\twocolitem{\windowstyle{wxHSCROLL}}{Use this style to enable a horizontal scrollbar.}
+\twocolitem{\windowstyle{wxVSCROLL}}{Use this style to enable a vertical scrollbar. (Still used?) }
+\twocolitem{\windowstyle{wxHSCROLL}}{Use this style to enable a horizontal scrollbar. (Still used?) }

 \twocolitem{\windowstyle{wxCLIP\_CHILDREN}}{Use this style to eliminate flicker caused by the background being
 \twocolitem{\windowstyle{wxCLIP\_CHILDREN}}{Use this style to eliminate flicker caused by the background being

-repainted, then children being painted over them. Windows-only.}
+repainted, then children being painted over them. Windows only.}

 \end{twocollist}
 
 See also \helpref{window styles overview}{windowstyles}.
 \end{twocollist}
 
 See also \helpref{window styles overview}{windowstyles}.


@@ -70,7 +70,9 @@ should generate a default position for the window. If using the wxWindow class d
 an actual position.}
 
 \docparam{size}{Window size. wxDefaultSize is (-1, -1) which indicates that wxWindows
 an actual position.}
 
 \docparam{size}{Window size. wxDefaultSize is (-1, -1) which indicates that wxWindows

-should generate a default size for the window.}
+should generate a default size for the window. If no suitable size can  be found, the
+window will be sized to 20x20 pixels so that the window is visible but obviously not
+correctly sized. }

 
 \docparam{style}{Window style. For generic window styles, please see \helpref{wxWindow}{wxwindow}.}
 
 
 \docparam{style}{Window style. For generic window styles, please see \helpref{wxWindow}{wxwindow}.}
 


@@ -196,6 +198,14 @@ destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
 
 Applies to managed windows (wxFrame and wxDialog classes) only.
 
 
 Applies to managed windows (wxFrame and wxDialog classes) only.
 

+{\it Note} that calling Close does not guarantee that the window will be destroyed; but it
+provides a way to simulate a manual close of a window, which may or may not be implemented by
+destroying the window. The default implementation of wxDialog::OnCloseWindow does not
+necessarily delete the dialog, since it will simply simulate an wxID\_CANCEL event which
+itself only hides the dialog.
+
+To guarantee that the window will be destroyed, call \helpref{wxWindow::Destroy}{wxwindowdestroy} instead.
+

 \wxheading{See also}
 
 \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp
 \wxheading{See also}
 
 \helpref{Window deletion overview}{windowdeletionoverview},\rtfsp


@@ -243,9 +253,9 @@ implements the following methods:\par
 
 Additionally, the following helper functions are defined:\par
 \indented{2cm}{\begin{twocollist}
 
 Additionally, the following helper functions are defined:\par
 \indented{2cm}{\begin{twocollist}

-\twocolitem{\bf{wxDLG_PNT(win, point)}}{Converts a wxPoint from dialog
+\twocolitem{\bf{wxDLG\_PNT(win, point)}}{Converts a wxPoint from dialog

 units to pixels}
 units to pixels}

-\twocolitem{\bf{wxDLG_SZE(win, size)}}{Converts a wxSize from dialog
+\twocolitem{\bf{wxDLG\_SZE(win, size)}}{Converts a wxSize from dialog

 units to pixels}
 \end{twocollist}}
 }
 units to pixels}
 \end{twocollist}}
 }


@@ -507,7 +517,7 @@ Returns the grandparent of a window, or NULL if there isn't one.
 \constfunc{void*}{GetHandle}{\void}
 
 Returns the platform-specific handle of the physical window. Cast it to an appropriate
 \constfunc{void*}{GetHandle}{\void}
 
 Returns the platform-specific handle of the physical window. Cast it to an appropriate

-handle, such as {\bf HWND} for Windows or {\bf Widget} for Motif.
+handle, such as {\bf HWND} for Windows, {\bf Widget} for Motif or {\bf GtkWidget} for GTK.

 
 \membersection{wxWindow::GetId}\label{wxwindowgetid}
 
 
 \membersection{wxWindow::GetId}\label{wxwindowgetid}
 


@@ -517,8 +527,8 @@ Returns the identifier of the window.
 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-Each window has an integer identifier. If the application has not provided one,
-an identifier will be generated.
+Each window has an integer identifier. If the application has not provided one
+(or the default Id -1) an unique identifier with a negative value will be generated.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 


@@ -548,7 +558,7 @@ implements the following methods:\par
 
 \membersection{wxWindow::GetLabel}
 
 
 \membersection{wxWindow::GetLabel}
 

-\constfunc{virtual wxString\& }{GetLabel}{\void}
+\constfunc{virtual wxString }{GetLabel}{\void}

 
 Generic way of getting a label from any window, for
 identification purposes.
 
 Generic way of getting a label from any window, for
 identification purposes.


@@ -563,7 +573,7 @@ by name.
 
 \membersection{wxWindow::GetName}\label{wxwindowgetname}
 
 
 \membersection{wxWindow::GetName}\label{wxwindowgetname}
 

-\constfunc{virtual wxString\& }{GetName}{\void}
+\constfunc{virtual wxString }{GetName}{\void}

 
 Returns the window's name.
 
 
 Returns the window's name.
 


@@ -588,22 +598,6 @@ Returns the parent of the window, or NULL if there is no parent.
 
 Returns the size and position of the window as a \helpref{wxRect}{wxrect} object.
 
 
 Returns the size and position of the window as a \helpref{wxRect}{wxrect} object.
 

-\membersection{wxWindow::GetReturnCode}\label{wxwindowgetreturncode}
-
-\func{int}{GetReturnCode}{\void}
-
-Gets the return code for this window.
-
-\wxheading{Remarks}
-
-A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
-a code to the application.
-
-\wxheading{See also}
-
-\helpref{wxWindow::SetReturnCode}{wxwindowsetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
-\helpref{wxDialog::EndModal}{wxdialogendmodal}
-

 \membersection{wxWindow::GetScrollThumb}\label{wxwindowgetscrollthumb}
 
 \func{virtual int}{GetScrollThumb}{\param{int }{orientation}}
 \membersection{wxWindow::GetScrollThumb}\label{wxwindowgetscrollthumb}
 
 \func{virtual int}{GetScrollThumb}{\param{int }{orientation}}


@@ -713,11 +707,18 @@ only be called within an \helpref{OnPaint}{wxwindowonpaint} event handler.
 
 \helpref{wxRegion}{wxregion}, \helpref{wxRegionIterator}{wxregioniterator}, \helpref{wxWindow::OnPaint}{wxwindowonpaint}
 
 
 \helpref{wxRegion}{wxregion}, \helpref{wxRegionIterator}{wxregioniterator}, \helpref{wxWindow::OnPaint}{wxwindowonpaint}
 

+\membersection{wxWindow::GetValidator}\label{wxwindowgetvalidator}
+
+\constfunc{wxValidator*}{GetValidator}{\void}
+
+Returns a pointer to the current validator for the window, or NULL if there is none.
+

 \membersection{wxWindow::GetWindowStyleFlag}
 
 \constfunc{long}{GetWindowStyleFlag}{\void}
 
 \membersection{wxWindow::GetWindowStyleFlag}
 
 \constfunc{long}{GetWindowStyleFlag}{\void}
 

-Gets the window style that was passed to the consructor or {\bf Create} member.
+Gets the window style that was passed to the consructor or {\bf Create} member. 
+{\bf GetWindowStyle} is synonymous.

 
 \membersection{wxWindow::InitDialog}\label{wxwindowinitdialog}
 
 
 \membersection{wxWindow::InitDialog}\label{wxwindowinitdialog}
 


@@ -756,12 +757,22 @@ Retained windows are only available on X platforms.
 
 Returns TRUE if the window is shown, FALSE if it has been hidden.
 
 
 Returns TRUE if the window is shown, FALSE if it has been hidden.
 

+\membersection{wxWindow::IsTopLevel}\label{wxwindowistoplevel}
+
+\constfunc{bool}{IsTopLevel}{\void}
+
+Returns TRUE if the given window is a top-level one. Currently all frames and
+dialogs are considered to be top-level windows (even if they have a parent
+window).
+

 \membersection{wxWindow::Layout}\label{wxwindowlayout}
 
 \func{void}{Layout}{\void}
 
 \membersection{wxWindow::Layout}\label{wxwindowlayout}
 
 \func{void}{Layout}{\void}
 

-Invokes the constraint-based layout algorithm for this window. It is called
-automatically by the default {\bf wxWindow::OnSize} member.
+Invokes the constraint-based layout algorithm for this window. 
+
+See \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} on when
+this function gets called automatically using auto layout.

 
 \membersection{wxWindow::LoadFromResource}\label{wxwindowloadfromresource}
 
 
 \membersection{wxWindow::LoadFromResource}\label{wxwindowloadfromresource}
 


@@ -795,7 +806,8 @@ or frame).
 \func{virtual void}{MakeModal}{\param{const bool }{flag}}
 
 Disables all other windows in the application so that
 \func{virtual void}{MakeModal}{\param{const bool }{flag}}
 
 Disables all other windows in the application so that

-the user can only interact with this window.
+the user can only interact with this window. (This function
+is not implemented anywhere).

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -917,7 +929,9 @@ Note that the ASCII values do not have explicit key codes: they are passed as AS
 values.
 
 This function is only relevant to top-level windows (frames and dialogs), and under
 values.
 
 This function is only relevant to top-level windows (frames and dialogs), and under

-Windows only.
+Windows only. Under GTK the normal EVT\_CHAR\_ event has the functionality, i.e.
+you can intercepts it and if you don't call \helpref{wxEvent::Skip}{wxeventskip}
+the window won't get the event.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 


@@ -1049,7 +1063,9 @@ Called when the background of the window needs to be erased.
 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-This event is only generated under Windows.
+This event is only generated under Windows. It is therefore recommended that
+you set the text background colour explicitly in order to prevent flicker.
+The default background colour under GTK is grey.

 
 To intercept this event, use the EVT\_ERASE\_BACKGROUND macro in an event table definition.
 
 
 To intercept this event, use the EVT\_ERASE\_BACKGROUND macro in an event table definition.
 


@@ -1416,7 +1432,7 @@ used by the application.
 
 \func{void}{OnSysColourChanged}{\param{wxOnSysColourChangedEvent\& }{event}}
 
 
 \func{void}{OnSysColourChanged}{\param{wxOnSysColourChangedEvent\& }{event}}
 

-Called when the user has changed the system colours.
+Called when the user has changed the system colours. Windows only.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -1577,7 +1593,7 @@ implements the following methods:\par
 
 \func{virtual void}{ScrollWindow}{\param{int }{dx}, \param{int }{dy}, \param{const wxRect*}{ rect = NULL}}
 
 
 \func{virtual void}{ScrollWindow}{\param{int }{dx}, \param{int }{dy}, \param{const wxRect*}{ rect = NULL}}
 

-Physically scrolls the pixels in the window.
+Physically scrolls the pixels in the window and move child windows accordingly.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -1587,14 +1603,13 @@ Physically scrolls the pixels in the window.
 
 \docparam{rect}{Rectangle to invalidate. If this is NULL, the whole window is invalidated. If you
 pass a rectangle corresponding to the area of the window exposed by the scroll, your painting handler
 
 \docparam{rect}{Rectangle to invalidate. If this is NULL, the whole window is invalidated. If you
 pass a rectangle corresponding to the area of the window exposed by the scroll, your painting handler

-can optimise painting by checking for the invalidated region.}
+can optimise painting by checking for the invalidated region. This paramter is ignored under GTK,
+instead the regions to be invalidated are calculated automatically. }

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-Available only under Windows.
-

 Use this function to optimise your scrolling implementations, to minimise the area that must be
 Use this function to optimise your scrolling implementations, to minimise the area that must be

-redrawn.
+redrawn. Note that it is rarely required to call this function from a user program.

 
 \membersection{wxWindow::SetAcceleratorTable}\label{wxwindowsetacceleratortable}
 
 
 \membersection{wxWindow::SetAcceleratorTable}\label{wxwindowsetacceleratortable}
 


@@ -1614,6 +1629,11 @@ be called automatically when the window is resized.
 \docparam{autoLayout}{Set this to TRUE if you wish the Layout function to be called
 from within wxWindow::OnSize functions.}
 
 \docparam{autoLayout}{Set this to TRUE if you wish the Layout function to be called
 from within wxWindow::OnSize functions.}
 

+\wxheading{Remarks}
+
+Note that this function is actually disabled for wxWindow and only indirectly
+takes affect for children of wxDialog, wxFrame, wxNotebook and wxSplitterWindow.
+

 \wxheading{See also}
 
 \helpref{wxWindow::SetConstraints}{wxwindowsetconstraints}
 \wxheading{See also}
 
 \helpref{wxWindow::SetConstraints}{wxwindowsetconstraints}


@@ -1631,12 +1651,17 @@ Sets the background colour of the window.
 \wxheading{Remarks}
 
 The background colour is usually painted by the default\rtfsp
 \wxheading{Remarks}
 
 The background colour is usually painted by the default\rtfsp

-\helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground} event handler function.
+\helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground} event handler function
+under Windows and automatically under GTK.

 
 Note that setting the background colour does not cause an immediate refresh, so you
 may wish to call \helpref{wxWindow::Clear}{wxwindowclear} or \helpref{wxWindow::Refresh}{wxwindowrefresh} after
 calling this function.
 
 
 Note that setting the background colour does not cause an immediate refresh, so you
 may wish to call \helpref{wxWindow::Clear}{wxwindowclear} or \helpref{wxWindow::Refresh}{wxwindowrefresh} after
 calling this function.
 

+Note that when using this functions under GTK, you will disable the so called "themes",
+i.e. the user chosen apperance of windows and controls, including the themes of
+their parent windows.
+

 \wxheading{See also}
 
 \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour},\rtfsp
 \wxheading{See also}
 
 \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour},\rtfsp


@@ -1677,18 +1702,14 @@ implements the following methods:\par
 
 \func{virtual void}{SetCursor}{\param{const wxCursor\&}{cursor}}
 
 
 \func{virtual void}{SetCursor}{\param{const wxCursor\&}{cursor}}
 

-Sets the window's cursor.
+Sets the window's cursor. Notice that setting the cursor for this window does
+not set it for its children so you'll need to explicitly call SetCursor() for
+them too if you need it.

 
 \wxheading{Parameters}
 
 \docparam{cursor}{Specifies the cursor that the window should normally display.}
 
 
 \wxheading{Parameters}
 
 \docparam{cursor}{Specifies the cursor that the window should normally display.}
 

-\wxheading{Remarks}
-
-Under Windows, you sometimes need to call ::wxSetCursor in addition to this
-function if you want the cursor to change immediately, because under Windows,
-wxWindows only sets the global cursor when it detects mouse movement.
-

 \wxheading{See also}
 
 \helpref{::wxSetCursor}{wxsetcursor}, \helpref{wxCursor}{wxcursor}
 \wxheading{See also}
 
 \helpref{::wxSetCursor}{wxsetcursor}, \helpref{wxCursor}{wxcursor}


@@ -1792,6 +1813,10 @@ The interpretation of foreground colour is open to interpretation according
 to the window class; it may be the text colour or other colour, or it may not
 be used at all.
 
 to the window class; it may be the text colour or other colour, or it may not
 be used at all.
 

+Note that when using this functions under GTK, you will disable the so called "themes",
+i.e. the user chosen apperance of windows and controls, including the themes of
+their parent windows.
+

 \wxheading{See also}
 
 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp
 \wxheading{See also}
 
 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp


@@ -1835,26 +1860,6 @@ Sets the window's name.
 
 Obsolete - use \helpref{wxDC::SetPalette}{wxdcsetpalette} instead.
 
 
 Obsolete - use \helpref{wxDC::SetPalette}{wxdcsetpalette} instead.
 

-\membersection{wxWindow::SetReturnCode}\label{wxwindowsetreturncode}
-
-\func{void}{SetReturnCode}{\param{int }{retCode}}
-
-Sets the return code for this window.
-
-\wxheading{Parameters}
-
-\docparam{retCode}{The integer return code, usually a control identifier.}
-
-\wxheading{Remarks}
-
-A return code is normally associated with a modal dialog, where \helpref{wxDialog::ShowModal}{wxdialogshowmodal} returns
-a code to the application. The function \helpref{wxDialog::EndModal}{wxdialogendmodal} calls {\bf SetReturnCode}.
-
-\wxheading{See also}
-
-\helpref{wxWindow::GetReturnCode}{wxwindowgetreturncode}, \helpref{wxDialog::ShowModal}{wxdialogshowmodal},\rtfsp
-\helpref{wxDialog::EndModal}{wxdialogendmodal}
-

 \membersection{wxWindow::SetScrollbar}\label{wxwindowsetscrollbar}
 
 \func{virtual void}{SetScrollbar}{\param{int }{orientation}, \param{int }{position},\rtfsp
 \membersection{wxWindow::SetScrollbar}\label{wxwindowsetscrollbar}
 
 \func{virtual void}{SetScrollbar}{\param{int }{orientation}, \param{int }{position},\rtfsp


@@ -2114,7 +2119,14 @@ Sets the window's title. Applicable only to frames and dialogs.
 
 \helpref{wxWindow::GetTitle}{wxwindowgettitle}
 
 
 \helpref{wxWindow::GetTitle}{wxwindowgettitle}
 

-\membersection{wxWindow::Show}
+\membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator}
+
+\func{virtual void}{SetValidator}{\param{const wxValidator\&}{ validator}}
+
+Deletes the current validator (if any) and sets the window validator, having called wxValidator::Clone to
+create a new validator of this type.
+
+\membersection{wxWindow::Show}\label{wxwindowshow}

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