Several changes and updates

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

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 26e3a73155966e28cda6e3b83af0fccb47447a88..d877e1cf846b67da38086721f630fcbb2d098fff 100644 (file)
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -1,8 +1,15 @@
 \section{\class{wxWindow}}\label{wxwindow}
 
 \section{\class{wxWindow}}\label{wxwindow}
 

-wxWindow is the base class for all windows.  Any
-children of the window will be deleted automatically by the destructor
-before the window itself is deleted.
+wxWindow is the base class for all windows. Any children of the window will be deleted 
+automatically by the destructor before the window itself is deleted.
+
+Please note that we documented a number of handler functions (OnChar(), OnMouse() etc.) in this 
+help text. These must not be called by a user program and are documented only for illustration. 
+On several platforms, only a few of these handlers are actually written (they are not always
+needed) and if you are uncertain on how to add a certain behaviour to a window class, intercept
+the respective event as usual and call \helpref{wxEvent::Skip}{wxeventskip} so that the native
+platform can implement its native behaviour or just ignore the event if nothing needs to be
+done.

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 


@@ -16,7 +23,7 @@ before the window itself is deleted.
 \wxheading{Window styles}
 
 The following styles can apply to all windows, although they will not always make sense for a particular
 \wxheading{Window styles}
 
 The following styles can apply to all windows, although they will not always make sense for a particular

-window class.
+window class or on all platforms.

 
 \twocolwidtha{5cm}%
 \begin{twocollist}\itemsep=0pt
 
 \twocolwidtha{5cm}%
 \begin{twocollist}\itemsep=0pt


@@ -31,6 +38,14 @@ 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{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{wxWANTS\_CHARS}}{Use this to indicate that the window
+wants to get all char events - even for keys like TAB or ENTER which are
+usually used for dialog navigation and which wouldn't be generated without
+this style}
+\twocolitem{\windowstyle{wxNO\_FULLREPAINT\_ON\_RESIZE}}{Disables repainting
+the window completely when its size is changed - you will have to repaint the
+new window area manually if you use style. Currently only has effect for
+Windows.}

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


@@ -137,15 +152,16 @@ Centres the window.
 \wxheading{Parameters}
 
 \docparam{direction}{Specifies the direction for the centering. May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL}\rtfsp
 \wxheading{Parameters}
 
 \docparam{direction}{Specifies the direction for the centering. May be {\tt wxHORIZONTAL}, {\tt wxVERTICAL}\rtfsp

-or {\tt wxBOTH}. It may also include {\tt wxCENTER\_FRAME} flag if you want to center the window
-on its parent and not on the screen (actually, this flag is added automatically for all controls
-because it makes no sense to center them on the screen)}
+or {\tt wxBOTH}. It may also include {\tt wxCENTRE\_ON\_SCREEN} flag
+if you want to center the window on the entire screen and not on its
+parent window.}
+
+The flag {\tt wxCENTRE\_FRAME} is obsolete and should not be used any longer.

 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-The actual behaviour depends on the derived window. For a frame or dialog box,
-centring is relative to the whole display. For a panel item, centring is
-relative to the panel.
+If the window is a top level one (i.e. doesn't have a parent), it will be
+centered relative to the screen anyhow.

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


@@ -771,6 +787,20 @@ Returns TRUE if the window is enabled for input, FALSE otherwise.
 
 \helpref{wxWindow::Enable}{wxwindowenable}
 
 
 \helpref{wxWindow::Enable}{wxwindowenable}
 

+\membersection{wxWindow:IsExposed}\label{wxwindowisexposed}
+
+\constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}}
+
+\constfunc{bool}{IsExposed}{\param{wxPoint }{&pt}}
+
+\constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}, \param{int }{w}, \param{int }{h}}
+
+\constfunc{bool}{IsExposed}{\param{wxRect }{&rect}}
+
+Returns TRUE if the given point or rectange area has been exposed since the
+last repaint. Call this in an paint event handler to optimize redrawing by
+only redrawing those areas, which have been exposed.
+

 \membersection{wxWindow::IsRetained}\label{wxwindowisretained}
 
 \constfunc{virtual bool}{IsRetained}{\void}
 \membersection{wxWindow::IsRetained}\label{wxwindowisretained}
 
 \constfunc{virtual bool}{IsRetained}{\void}


@@ -799,7 +829,8 @@ window).
 
 \func{void}{Layout}{\void}
 
 
 \func{void}{Layout}{\void}
 

-Invokes the constraint-based layout algorithm for this window.
+Invokes the constraint-based layout algorithm or the sizer-based algorithm
+for this window.

 
 See \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} on when
 this function gets called automatically using auto layout.
 
 See \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} on when
 this function gets called automatically using auto layout.


@@ -1523,6 +1554,14 @@ Just before the menu is popped up, \helpref{wxMenu::UpdateUI}{wxmenuupdateui} is
 to ensure that the menu items are in the correct state. The menu does not get deleted
 by the window.
 
 to ensure that the menu items are in the correct state. The menu does not get deleted
 by the window.
 

+\pythonnote{In place of a single overloaded method name, wxPython
+implements the following methods:\par
+\indented{2cm}{\begin{twocollist}
+\twocolitem{\bf{PopupMenu(menu, point)}}{Specifies position with a wxPoint}
+\twocolitem{\bf{PopupMenuXY(menu, x, y)}}{Specifies position with two integers (x, y)}
+\end{twocollist}}
+}
+

 \membersection{wxWindow::PushEventHandler}\label{wxwindowpusheventhandler}
 
 \func{void}{PushEventHandler}{\param{wxEvtHandler* }{handler}}
 \membersection{wxWindow::PushEventHandler}\label{wxwindowpusheventhandler}
 
 \func{void}{PushEventHandler}{\param{wxEvtHandler* }{handler}}


@@ -1603,7 +1642,7 @@ functions so should not be required by the application programmer.
 \func{virtual bool}{Reparent}{\param{wxWindow* }{newParent}}
 
 Reparents the window, i.e the window will be removed from its
 \func{virtual bool}{Reparent}{\param{wxWindow* }{newParent}}
 
 Reparents the window, i.e the window will be removed from its

-current parent window (e.g. a non-standard toolbar in a wxFrame) 
+current parent window (e.g. a non-standard toolbar in a wxFrame)

 and then re-inserted into another (e.g. a wxMiniFrame for a
 floating toolbar). Available on Windows and GTK+.
 
 and then re-inserted into another (e.g. a wxMiniFrame for a
 floating toolbar). Available on Windows and GTK+.
 


@@ -1669,7 +1708,9 @@ Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxa
 \func{void}{SetAutoLayout}{\param{const bool}{ autoLayout}}
 
 Determines whether the \helpref{wxWindow::Layout}{wxwindowlayout} function will
 \func{void}{SetAutoLayout}{\param{const bool}{ autoLayout}}
 
 Determines whether the \helpref{wxWindow::Layout}{wxwindowlayout} function will

-be called automatically when the window is resized.
+be called automatically when the window is resized. Use in connection with
+\helpref{wxWindow::SetSizer}{wxwindowsetsizer} and 
+\helpref{wxWindow::SetConstraints}{wxwindowsetconstraints} for layouting subwindows.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -1808,8 +1849,9 @@ constraints.}
 \wxheading{Remarks}
 
 You must call \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} to tell a window to use
 \wxheading{Remarks}
 
 You must call \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} to tell a window to use

-the constraints automatically in OnSize; otherwise, you must
-override OnSize and call Layout explicitly.
+the constraints automatically in OnSize; otherwise, you must override OnSize and call Layout() 
+explicitly. When setting both a wxLayoutConstraints and a \helpref{wxSizer}{wxsizer}, only the
+sizer will have effect.

 
 \membersection{wxWindow::SetDropTarget}\label{wxwindowsetdroptarget}
 
 
 \membersection{wxWindow::SetDropTarget}\label{wxwindowsetdroptarget}
 


@@ -2152,6 +2194,27 @@ given bounds.
 
 The resizing increments are only significant under Motif or Xt.
 
 
 The resizing increments are only significant under Motif or Xt.
 

+\membersection{wxWindow::SetSizer}\label{wxwindowsetsizer}
+
+\func{void}{SetSizer}{\param{wxSizer* }{sizer}}
+
+Sets the window to have the given layout sizer. The window
+will then own the object, and will take care of its deletion.
+If an existing layout constraints object is already owned by the
+window, it will be deleted.
+
+\wxheading{Parameters}
+
+\docparam{sizer}{The sizer to set. Pass NULL to disassociate and delete the window's
+sizer.}
+
+\wxheading{Remarks}
+
+You must call \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} to tell a window to use
+the sizer automatically in OnSize; otherwise, you must override OnSize and call Layout() 
+explicitly. When setting both a wxSizer and a \helpref{wxLayoutConstraints}{wxlayoutconstraints}, 
+only the sizer will have effect.
+

 \membersection{wxWindow::SetTitle}\label{wxwindowsettitle}
 
 \func{virtual void}{SetTitle}{\param{const wxString\& }{title}}
 \membersection{wxWindow::SetTitle}\label{wxwindowsettitle}
 
 \func{virtual void}{SetTitle}{\param{const wxString\& }{title}}