X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/895fc9cb8bc1f47e30ddb487f36648b477a4521c..d24905b5e47a0bc6e879a55f5e0c694f82621199:/docs/latex/wx/window.tex

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 1cadad6ded..f8a0cfa39b 100644
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -1,8 +1,15 @@
 \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}
 
@@ -16,15 +23,15 @@ 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
-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
-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{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.}
@@ -38,7 +45,7 @@ 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
-wxMSW.}
+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
@@ -208,15 +215,15 @@ a screen coordinate will be passed out.}
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{ClientToScreen(point)}}{Accepts and returns a wxPoint}
-\twocolitem{\bf{ClientToScreenXY(x, y)}}{Returns a 2-tuple, (x, y)}
+\twocolitem{{\bf ClientToScreen(point)}}{Accepts and returns a wxPoint}
+\twocolitem{{\bf ClientToScreenXY(x, y)}}{Returns a 2-tuple, (x, y)}
 \end{twocollist}}
 }
 
 
 \membersection{wxWindow::Close}\label{wxwindowclose}
 
-\func{virtual bool}{Close}{\param{const bool}{ force = FALSE}}
+\func{virtual bool}{Close}{\param{bool}{ force = FALSE}}
 
 The purpose of this call is to provide a safer way of destroying a window than using
 the {\it delete} operator.
@@ -286,15 +293,15 @@ You can also use these functions programmatically. A convenience macro is define
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{ConvertDialogPointToPixels(point)}}{Accepts and returns a wxPoint}
-\twocolitem{\bf{ConvertDialogSizeToPixels(size)}}{Accepts and returns a wxSize}
+\twocolitem{{\bf ConvertDialogPointToPixels(point)}}{Accepts and returns a wxPoint}
+\twocolitem{{\bf ConvertDialogSizeToPixels(size)}}{Accepts and returns a wxSize}
 \end{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}
-\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}}
 }
@@ -327,8 +334,8 @@ Dialogs created using Dialog Editor optionally use dialog units.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{ConvertDialogPointToPixels(point)}}{Accepts and returns a wxPoint}
-\twocolitem{\bf{ConvertDialogSizeToPixels(size)}}{Accepts and returns a wxSize}
+\twocolitem{{\bf ConvertDialogPointToPixels(point)}}{Accepts and returns a wxPoint}
+\twocolitem{{\bf ConvertDialogSizeToPixels(size)}}{Accepts and returns a wxSize}
 \end{twocollist}}
 }
 
@@ -356,7 +363,7 @@ Destroys all children of a window.  Called automatically by the destructor.
 
 \membersection{wxWindow::DragAcceptFiles}\label{wxwindowdragacceptfiles}
 
-\func{virtual void}{DragAcceptFiles}{\param{const bool}{ accept}}
+\func{virtual void}{DragAcceptFiles}{\param{bool}{ accept}}
 
 Enables or disables elibility for drop file events (OnDropFiles).
 
@@ -375,7 +382,7 @@ Windows only.
 
 \membersection{wxWindow::Enable}\label{wxwindowenable}
 
-\func{virtual void}{Enable}{\param{const bool}{ enable}}
+\func{virtual void}{Enable}{\param{bool}{ enable}}
 
 Enable or disable the window for user input.
 
@@ -414,8 +421,8 @@ Find a child of this window, by name.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{FindWindowById(id)}}{Accepts an integer}
-\twocolitem{\bf{FindWindowByName(name)}}{Accepts a string}
+\twocolitem{{\bf FindWindowById(id)}}{Accepts an integer}
+\twocolitem{{\bf FindWindowByName(name)}}{Accepts a string}
 \end{twocollist}}
 }
 
@@ -423,7 +430,8 @@ implements the following methods:\par
 
 \func{virtual void}{Fit}{\void}
 
-Sizes the window so that it fits around its subwindows.
+Sizes the window so that it fits around its subwindows. This function won't do
+anything if there are no subwindows.
 
 \membersection{wxWindow::GetBackgroundColour}\label{wxwindowgetbackgroundcolour}
 
@@ -438,6 +446,17 @@ Returns the background colour of the window.
 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp
 \helpref{wxWindow::OnEraseBackground}{wxwindowonerasebackground}
 
+\membersection{wxWindow::GetBestSize}\label{wxwindowgetbestsize}
+
+\constfunc{virtual wxSize}{GetBestSize}{\void}
+
+This functions returns the best acceptable minimal size for the window. For
+example, for a static control, it will be the minimal size such that the
+control label is not truncated. For windows containing subwindows (typically 
+\helpref{wxPanel}{wxpanel}), the size returned by this function will be the
+same as the size the window would have had after calling 
+\helpref{Fit}{wxwindowfit}.
+
 \membersection{wxWindow::GetCharHeight}
 
 \constfunc{virtual int}{GetCharHeight}{\void}
@@ -474,8 +493,8 @@ area which may be drawn on by the programmer, excluding title bar, border etc.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{wxGetClientSizeTuple()}}{Returns a 2-tuple of (width, height)}
-\twocolitem{\bf{wxGetClientSize()}}{Returns a wxSize object}
+\twocolitem{{\bf wxGetClientSizeTuple()}}{Returns a 2-tuple of (width, height)}
+\twocolitem{{\bf wxGetClientSize()}}{Returns a wxSize object}
 \end{twocollist}}
 }
 
@@ -558,6 +577,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.
 
+\pythonnote{This method will return an integer in wxPython.}
+
 \membersection{wxWindow::GetId}\label{wxwindowgetid}
 
 \constfunc{int}{GetId}{\void}
@@ -590,8 +611,8 @@ if no parent, relative to the whole display.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{GetPosition()}}{Returns a wxPoint}
-\twocolitem{\bf{GetPositionTuple()}}{Returns a tuple (x, y)}
+\twocolitem{{\bf GetPosition()}}{Returns a wxPoint}
+\twocolitem{{\bf GetPositionTuple()}}{Returns a tuple (x, y)}
 \end{twocollist}}
 }
 
@@ -684,8 +705,8 @@ This gets the size of the entire window in pixels.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{GetSize()}}{Returns a wxSize}
-\twocolitem{\bf{GetSizeTuple()}}{Returns a 2-tuple (width, height)}
+\twocolitem{{\bf GetSize()}}{Returns a wxSize}
+\twocolitem{{\bf GetSizeTuple()}}{Returns a 2-tuple (width, height)}
 \end{twocollist}}
 }
 
@@ -693,7 +714,7 @@ implements the following methods:\par
 
 \constfunc{virtual void}{GetTextExtent}{\param{const wxString\& }{string}, \param{int* }{x}, \param{int* }{y},
  \param{int* }{descent = NULL}, \param{int* }{externalLeading = NULL},
- \param{const wxFont* }{font = NULL}, \param{const bool}{ use16 = FALSE}}
+ \param{const wxFont* }{font = NULL}, \param{bool}{ use16 = FALSE}}
 
 Gets the dimensions of the string as it would be drawn on the
 window with the currently selected font.
@@ -718,8 +739,8 @@ window with the currently selected font.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{GetTextExtent(string)}}{Returns a 2-tuple,  (width, height)}
-\twocolitem{\bf{GetFullTextExtent(string, font=NULL)}}{Returns a
+\twocolitem{{\bf GetTextExtent(string)}}{Returns a 2-tuple,  (width, height)}
+\twocolitem{{\bf GetFullTextExtent(string, font=NULL)}}{Returns a
 4-tuple, (width, height, descent, externalLeading) }
 \end{twocollist}}
 }
@@ -784,15 +805,15 @@ Returns TRUE if the window is enabled for input, FALSE otherwise.
 
 \constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}}
 
-\constfunc{bool}{IsExposed}{\param{wxPoint }{&pt}}
+\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}}
+\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 area, which have been exposed.
+only redrawing those areas, which have been exposed.
 
 \membersection{wxWindow::IsRetained}\label{wxwindowisretained}
 
@@ -857,7 +878,7 @@ or frame).
 
 \membersection{wxWindow::MakeModal}\label{wxwindowmakemodal}
 
-\func{virtual void}{MakeModal}{\param{const bool }{flag}}
+\func{virtual void}{MakeModal}{\param{bool }{flag}}
 
 Disables all other windows in the application so that
 the user can only interact with this window. (This function
@@ -901,8 +922,8 @@ as the call:
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{Move(point)}}{Accepts a wxPoint}
-\twocolitem{\bf{MoveXY(x, y)}}{Accepts a pair of integers}
+\twocolitem{{\bf Move(point)}}{Accepts a wxPoint}
+\twocolitem{{\bf MoveXY(x, y)}}{Accepts a pair of integers}
 \end{twocollist}}
 }
 
@@ -1358,7 +1379,7 @@ For example:
 
 \small{%
 \begin{verbatim}
-  void MyWindow::OnPaint(wxPaintEvent& event)
+  void MyWindow::OnPaint(wxPaintEvent\& event)
   {
       wxPaintDC dc(this);
 
@@ -1378,13 +1399,13 @@ Here is an example of using the \helpref{wxRegionIterator}{wxregioniterator} cla
 {\small%
 \begin{verbatim}
 // Called when window needs to be repainted.
-void MyWindow::OnPaint(wxPaintEvent& event)
+void MyWindow::OnPaint(wxPaintEvent\& event)
 {
   wxPaintDC dc(this);
 
   // Find Out where the window is scrolled to
   int vbX,vbY;                     // Top left corner of client
-  ViewStart(&vbX,&vbY);
+  GetViewStart(&vbX,&vbY);
 
   int vX,vY,vW,vH;                 // Dimensions of client area in pixels
   wxRegionIterator upd(GetUpdateRegion()); // get the update rect list
@@ -1518,7 +1539,7 @@ default value is FALSE.}
 
 \membersection{wxWindow::PopupMenu}\label{wxwindowpopupmenu}
 
-\func{bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{const wxPoint& }{pos}}
+\func{bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{const wxPoint\& }{pos}}
 
 \func{bool}{PopupMenu}{\param{wxMenu* }{menu}, \param{int }{x}, \param{int }{y}}
 
@@ -1550,8 +1571,8 @@ 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)}
+\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}}
 }
 
@@ -1595,7 +1616,7 @@ or frame).
 
 \membersection{wxWindow::Refresh}\label{wxwindowrefresh}
 
-\func{virtual void}{Refresh}{\param{const bool}{ eraseBackground = TRUE}, \param{const wxRect* }{rect
+\func{virtual void}{Refresh}{\param{bool}{ eraseBackground = TRUE}, \param{const wxRect* }{rect
 = NULL}}
 
 Causes a message or event to be generated to repaint the
@@ -1662,8 +1683,8 @@ Converts from screen to client window coordinates.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{ScreenToClient(point)}}{Accepts and returns a wxPoint}
-\twocolitem{\bf{ScreenToClientXY(x, y)}}{Returns a 2-tuple, (x, y)}
+\twocolitem{{\bf ScreenToClient(point)}}{Accepts and returns a wxPoint}
+\twocolitem{{\bf ScreenToClientXY(x, y)}}{Returns a 2-tuple, (x, y)}
 \end{twocollist}}
 }
 
@@ -1698,11 +1719,11 @@ Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxa
 
 \membersection{wxWindow::SetAutoLayout}\label{wxwindowsetautolayout}
 
-\func{void}{SetAutoLayout}{\param{const bool}{ autoLayout}}
+\func{void}{SetAutoLayout}{\param{bool}{ autoLayout}}
 
 Determines whether the \helpref{wxWindow::Layout}{wxwindowlayout} function will
 be called automatically when the window is resized. Use in connection with
-\helpref{wxWindow::SetSizer}{wxwindowsetsizer} and 
+\helpref{wxWindow::SetSizer}{wxwindowsetsizer} and
 \helpref{wxWindow::SetConstraints}{wxwindowsetconstraints} for layouting subwindows.
 
 \wxheading{Parameters}
@@ -1712,8 +1733,11 @@ 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.
+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}
 
@@ -1774,8 +1798,8 @@ around panel items, for example.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{SetClientSize(size)}}{Accepts a wxSize}
-\twocolitem{\bf{SetClientSizeWH(width, height)}}{}
+\twocolitem{{\bf SetClientSize(size)}}{Accepts a wxSize}
+\twocolitem{{\bf SetClientSizeWH(width, height)}}{}
 \end{twocollist}}
 }
 
@@ -1842,7 +1866,7 @@ constraints.}
 \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() 
+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.
 
@@ -1946,7 +1970,7 @@ Obsolete - use \helpref{wxDC::SetPalette}{wxdcsetpalette} instead.
 
 \func{virtual void}{SetScrollbar}{\param{int }{orientation}, \param{int }{position},\rtfsp
 \param{int }{thumbSize}, \param{int }{range},\rtfsp
-\param{const bool }{refresh = TRUE}}
+\param{bool }{refresh = TRUE}}
 
 Sets the scrollbar properties of a built-in scrollbar.
 
@@ -1995,7 +2019,7 @@ from your \helpref{wxWindow::OnSize}{wxwindowonsize} event handler function.
 \begin{comment}
 \membersection{wxWindow::SetScrollPage}\label{wxwindowsetscrollpage}
 
-\func{virtual void}{SetScrollPage}{\param{int }{orientation}, \param{int }{pageSize}, \param{const bool }{refresh = TRUE}}
+\func{virtual void}{SetScrollPage}{\param{int }{orientation}, \param{int }{pageSize}, \param{bool }{refresh = TRUE}}
 
 Sets the page size of one of the built-in scrollbars.
 
@@ -2033,7 +2057,7 @@ handling of pages and ranges.
 
 \membersection{wxWindow::SetScrollPos}\label{wxwindowsetscrollpos}
 
-\func{virtual void}{SetScrollPos}{\param{int }{orientation}, \param{int }{pos}, \param{const bool }{refresh = TRUE}}
+\func{virtual void}{SetScrollPos}{\param{int }{orientation}, \param{int }{pos}, \param{bool }{refresh = TRUE}}
 
 Sets the position of one of the built-in scrollbars.
 
@@ -2060,7 +2084,7 @@ application to take note of scrollbar attributes and redraw contents accordingly
 \begin{comment}
 \membersection{wxWindow::SetScrollRange}\label{wxwindowsetscrollrange}
 
-\func{virtual void}{SetScrollRange}{\param{int }{orientation}, \param{int }{range}, \param{const bool }{refresh = TRUE}}
+\func{virtual void}{SetScrollRange}{\param{int }{orientation}, \param{int }{range}, \param{bool }{refresh = TRUE}}
 
 Sets the range of one of the built-in scrollbars.
 
@@ -2152,9 +2176,9 @@ by wxWindows, or that the current value of the dimension should be used.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
-\twocolitem{\bf{SetDimensions(x, y, width, height, sizeFlags=wxSIZE_AUTO)}}{}
-\twocolitem{\bf{SetSize(size)}}{}
-\twocolitem{\bf{SetPosition(point)}}{}
+\twocolitem{{\bf SetDimensions(x, y, width, height, sizeFlags=wxSIZE\_AUTO)}}{}
+\twocolitem{{\bf SetSize(size)}}{}
+\twocolitem{{\bf SetPosition(point)}}{}
 \end{twocollist}}
 }
 
@@ -2204,8 +2228,8 @@ 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}, 
+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}
@@ -2231,7 +2255,7 @@ 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{bool}{ show}}
 
 Shows or hides the window.