Minor tweek for WXPM

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

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 46b27b976ba0a12dcccd01fe4b37169f5a22fa8e..9e3be209fa3f0c7a3079ccc4b9633be64962e912 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,21 +23,29 @@ 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
 \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. Windows only. }
+for this style. }

 \twocolitem{\windowstyle{wxDOUBLE\_BORDER}}{Displays a double border. Windows only.}
 \twocolitem{\windowstyle{wxSUNKEN\_BORDER}}{Displays a sunken 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{wxRAISED\_BORDER}}{Displays a raised border. GTK only. }

 \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{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{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,13 +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}.}
+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}
 


@@ -547,6 +565,8 @@ Returns the grandparent of a window, or NULL if there isn't one.
 Returns the platform-specific handle of the physical window. Cast it to an appropriate
 handle, such as {\bf HWND} for Windows, {\bf Widget} for Motif or {\bf GtkWidget} for GTK.
 
 Returns the platform-specific handle of the physical window. Cast it to an appropriate
 handle, such as {\bf HWND} for Windows, {\bf Widget} for Motif or {\bf GtkWidget} for GTK.
 

+\pythonnote{This method will return an integer in wxPython.}
+

 \membersection{wxWindow::GetId}\label{wxwindowgetid}
 
 \constfunc{int}{GetId}{\void}
 \membersection{wxWindow::GetId}\label{wxwindowgetid}
 
 \constfunc{int}{GetId}{\void}


@@ -769,6 +789,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}


@@ -797,7 +831,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.


@@ -1391,9 +1426,9 @@ void MyWindow::OnPaint(wxPaintEvent& event)
 
 \membersection{wxWindow::OnScroll}\label{wxwindowonscroll}
 
 
 \membersection{wxWindow::OnScroll}\label{wxwindowonscroll}
 

-\func{void}{OnScroll}{\param{wxScrollEvent\& }{event}}
+\func{void}{OnScroll}{\param{wxScrollWinEvent\& }{event}}

 
 

-Called when a scroll event is received from one of the window's built-in scrollbars.
+Called when a scroll window event is received from one of the window's built-in scrollbars.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -1409,7 +1444,7 @@ for horizontal events).
 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxScrollEvent}{wxscrollevent},\rtfsp
+\helpref{wxScrollWinEvent}{wxscrollwinevent},\rtfsp

 \helpref{Event handling overview}{eventhandlingoverview}
 
 \membersection{wxWindow::OnSetFocus}\label{wxwindowonsetfocus}
 \helpref{Event handling overview}{eventhandlingoverview}
 
 \membersection{wxWindow::OnSetFocus}\label{wxwindowonsetfocus}


@@ -1492,18 +1527,21 @@ default value is FALSE.}
 
 \membersection{wxWindow::PopupMenu}\label{wxwindowpopupmenu}
 
 
 \membersection{wxWindow::PopupMenu}\label{wxwindowpopupmenu}
 

-\func{virtual bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{int }{x}, \param{int }{y}}
+\func{bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{const wxPoint& }{pos}}
+
+\func{bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{int }{x}, \param{int }{y}}

 
 Pops up the given menu at the specified coordinates, relative to this
 window, and returns control when the user has dismissed the menu. If a
 
 Pops up the given menu at the specified coordinates, relative to this
 window, and returns control when the user has dismissed the menu. If a

-menu item is selected, the callback defined for the menu is called with
-wxMenu and wxCommandEvent reference arguments. The callback should access
-the commandInt member of the event to check the selected menu identifier.
+menu item is selected, the corresponding menu event is generated and will be
+processed as usually.

 
 \wxheading{Parameters}
 
 \docparam{menu}{Menu to pop up.}
 
 
 \wxheading{Parameters}
 
 \docparam{menu}{Menu to pop up.}
 

+\docparam{pos}{The position where the menu will appear.}
+

 \docparam{x}{Required x position for the menu to appear.}
 
 \docparam{y}{Required y position for the menu to appear.}
 \docparam{x}{Required x position for the menu to appear.}
 
 \docparam{y}{Required y position for the menu to appear.}


@@ -1515,7 +1553,16 @@ the commandInt member of the event to check the selected menu identifier.
 \wxheading{Remarks}
 
 Just before the menu is popped up, \helpref{wxMenu::UpdateUI}{wxmenuupdateui} is called
 \wxheading{Remarks}
 
 Just before the menu is popped up, \helpref{wxMenu::UpdateUI}{wxmenuupdateui} is called

-to ensure that the menu items are in the correct state.
+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}
 
 
 \membersection{wxWindow::PushEventHandler}\label{wxwindowpusheventhandler}
 


@@ -1592,6 +1639,19 @@ functions so should not be required by the application programmer.
 
 \docparam{child}{Child window to remove.}
 
 
 \docparam{child}{Child window to remove.}
 

+\membersection{wxWindow::Reparent}\label{wxwindowreparent}
+
+\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)
+and then re-inserted into another (e.g. a wxMiniFrame for a
+floating toolbar). Available on Windows and GTK+.
+
+\wxheading{Parameters}
+
+\docparam{newParent}{New parent.}
+

 \membersection{wxWindow::ScreenToClient}\label{wxwindowscreentoclient}
 
 \constfunc{virtual void}{ScreenToClient}{\param{int* }{x}, \param{int* }{y}}
 \membersection{wxWindow::ScreenToClient}\label{wxwindowscreentoclient}
 
 \constfunc{virtual void}{ScreenToClient}{\param{int* }{x}, \param{int* }{y}}


@@ -1650,7 +1710,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}
 


@@ -1659,8 +1721,11 @@ from within wxWindow::OnSize functions.}
 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-Note that this function is actually disabled for wxWindow and only indirectly
-takes affect for children of wxDialog, wxFrame, wxNotebook and wxSplitterWindow.
+Note that this function is actually disabled for wxWindow. It has
+effect for wxDialog, wxFrame, wxPanel and wxScrolledWindow.  Windows
+of other types that need to invoke the Layout algorithm should provide
+an EVT_SIZE handler and call
+\helpref{wxWindow::Layout}{wxwindowlayout} from within it.

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


@@ -1789,8 +1854,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}
 


@@ -2133,6 +2199,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}}