X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/fe604ccddcf5696a751892ad70dbc822be239c95..2b556e9adf01a107dbe78226c0f289f9ba24b575:/docs/latex/wx/window.tex

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 9b126650fb..65a3197659 100644
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -29,6 +29,8 @@ 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{wxCLIP\_CHILDREN}}{Use this style to eliminate flicker caused by the background being
+repainted, then children being painted over them. Windows-only.}
 \end{twocollist}
 
 See also \helpref{window styles overview}{windowstyles}.
@@ -145,6 +147,8 @@ Clears the window by filling it with the current background colour.
 
 \constfunc{virtual void}{ClientToScreen}{\param{int* }{x}, \param{int* }{y}}
 
+\constfunc{virtual wxPoint}{ClientToScreen}{\param{const wxPoint\&}{ pt}}
+
 Converts to screen coordinates from coordinates relative to this window.
 
 \docparam{x}{A pointer to a integer value for the x coordinate. Pass the client coordinate in, and
@@ -153,6 +157,8 @@ a screen coordinate will be passed out.}
 \docparam{y}{A pointer to a integer value for the y coordinate. Pass the client coordinate in, and
 a screen coordinate will be passed out.}
 
+\docparam{pt}{The client position for the second form of the function.}
+
 \membersection{wxWindow::Close}\label{wxwindowclose}
 
 \func{virtual bool}{Close}{\param{const bool}{ force = FALSE}}
@@ -183,6 +189,60 @@ Applies to managed windows (wxFrame and wxDialog classes) only.
 \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp
 \helpref{wxCloseEvent}{wxcloseevent}
 
+\membersection{wxWindow::ConvertDialogToPixels}\label{wxwindowconvertdialogtopixels}
+
+\func{wxPoint}{ConvertDialogToPixels}{\param{const wxPoint\&}{ pt}}
+
+\func{wxSize}{ConvertDialogToPixels}{\param{const wxSize\&}{ sz}}
+
+Converts a point or size from dialog units to pixels.
+
+For the x dimension, the dialog units are multiplied by the average character width
+and then divided by 4.
+
+For the y dimension, the dialog units are multiplied by the average character height
+and then divided by 8.
+
+\wxheading{Remarks}
+
+Dialog units are used for maintaining a dialog's proportions even if the font changes.
+Dialogs created using Dialog Editor optionally use dialog units.
+
+You can also use these functions programmatically. A convenience macro is defined:
+
+{\small
+\begin{verbatim}
+#define wxDLG_UNIT(parent, pt) parent->ConvertDialogToPixels(pt)
+\end{verbatim}
+}
+
+\wxheading{See also}
+
+\helpref{wxWindow::ConvertPixelsToDialog}{wxwindowconvertpixelstodialog}
+
+\membersection{wxWindow::ConvertPixelsToDialog}\label{wxwindowconvertpixelstodialog}
+
+\func{wxPoint}{ConvertPixelsToDialog}{\param{const wxPoint\&}{ pt}}
+
+\func{wxSize}{ConvertPixelsToDialog}{\param{const wxSize\&}{ sz}}
+
+Converts a point or size from pixels to dialog units.
+
+For the x dimension, the pixels are multiplied by 4 and then divided by the average
+character width.
+
+For the y dimension, the pixels are multipled by 8 and then divided by the average
+character height.
+
+\wxheading{Remarks}
+
+Dialog units are used for maintaining a dialog's proportions even if the font changes.
+Dialogs created using Dialog Editor optionally use dialog units.
+
+\wxheading{See also}
+
+\helpref{wxWindow::ConvertDialogToPixels}{wxwindowconvertdialogtopixels}
+
 \membersection{wxWindow::Destroy}\label{wxwindowdestroy}
 
 \func{virtual bool}{Destroy}{\void}
@@ -276,6 +336,16 @@ Note that this is a static function, so it can be called without needing a wxWin
 
 \helpref{wxWindow::SetFocus}{wxwindowsetfocus}
 
+\membersection{wxWindow::FindWindow}\label{wxwindowfindwindow}
+
+\func{wxWindow*}{FindWindow}{\param{long}{ id}}
+
+Find a child of this window, by identifier.
+
+\func{wxWindow*}{FindWindow}{\param{const wxString\&}{ name}}
+
+Find a child of this window, by name.
+
 \membersection{wxWindow::Fit}\label{wxwindowfit}
 
 \func{virtual void}{Fit}{\void}
@@ -317,6 +387,8 @@ Returns a pointer to the list of the window's children.
 
 \constfunc{virtual void}{GetClientSize}{\param{int* }{width}, \param{int* }{height}}
 
+\constfunc{virtual wxSize}{GetClientSize}{\void}
+
 This gets the size of the window `client area' in pixels.  The client area is the
 area which may be drawn on by the programmer, excluding title bar, border etc.
 
@@ -461,6 +533,12 @@ name in the window constructor or via \helpref{wxWindow::SetName}{wxwindowsetnam
 
 Returns the parent of the window, or NULL if there is no parent.
 
+\membersection{wxWindow::GetRect}\label{wxwindowgetrect}
+
+\constfunc{virtual wxRect}{GetRect}{\void}
+
+Returns the size and position of the window as a \helpref{wxRect}{wxrect} object.
+
 \membersection{wxWindow::GetReturnCode}\label{wxwindowgetreturncode}
 
 \func{int}{GetReturnCode}{\void}
@@ -507,10 +585,12 @@ Returns the built-in scrollbar range.
 
 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar}
 
-\membersection{wxWindow::GetSize}
+\membersection{wxWindow::GetSize}\label{wxwindowgetsize}
 
 \constfunc{virtual void}{GetSize}{\param{int* }{width}, \param{int* }{height}}
 
+\constfunc{virtual wxSize}{GetSize}{\void}
+
 This gets the size of the entire window in pixels.
 
 \wxheading{Parameters}
@@ -554,6 +634,17 @@ Gets the window's title. Applicable only to frames and dialogs.
 
 \helpref{wxWindow::SetTitle}{wxwindowsettitle}
 
+\membersection{wxWindow::GetUpdateRegion}\label{wxwindowgetupdateregion}
+
+\constfunc{virtual wxRegion}{GetUpdateRegion}{\void}
+
+Returns the region specifying which parts of the window have been damaged. Should
+only be called within an \helpref{OnPaint}{wxwindowonpaint} event handler.
+
+\wxheading{See also}
+
+\helpref{wxRegion}{wxregion}, \helpref{wxRegionIterator}{wxregioniterator}, \helpref{wxWindow::OnPaint}{wxwindowonpaint}
+
 \membersection{wxWindow::GetWindowStyleFlag}
 
 \constfunc{long}{GetWindowStyleFlag}{\void}
@@ -655,6 +746,8 @@ the user can only interact with this window. If FALSE, the effect is reversed.}
 
 \func{void}{Move}{\param{int}{ x}, \param{int}{ y}}
 
+\func{void}{Move}{\param{const wxPoint\&}{ pt}}
+
 Moves the window to the given position.
 
 \wxheading{Parameters}
@@ -663,6 +756,8 @@ Moves the window to the given position.
 
 \docparam{y}{Required y position.}
 
+\docparam{pt}{\helpref{wxPoint}{wxpoint} object representing the position.}
+
 \wxheading{Remarks}
 
 Implementations of SetSize can also implicitly implement the
@@ -799,7 +894,7 @@ you may delete other windows.
 
 \wxheading{Remarks}
 
-Derive your own class to handle this message. The default handler returns FALSE.
+Derive your own class to handle this message. The default handler returns TRUE.
 
 \wxheading{See also}
 
@@ -824,6 +919,14 @@ using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is TRUE,
 destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
 If not, it is up to you whether you respond by destroying the window.
 
+(Note: GetForce is now superceded by CanVeto. So to test whether forced destruction of
+the window is required, test for the negative of CanVeto. If CanVeto returns FALSE,
+it is not possible to skip window deletion.)
+
+If you don't destroy the window, you should call \helpref{wxCloseEvent::Veto}{wxcloseeventveto} to
+let the calling code know that you did not destroy the window. This allows the \helpref{wxWindow::Close}{wxwindowclose} function
+to return TRUE or FALSE depending on whether the close instruction was honoured or not.
+
 \wxheading{Remarks}
 
 The \helpref{wxWindow::OnClose}{wxwindowonclose} virtual function remains
@@ -837,22 +940,9 @@ destroying the window if it returns TRUE or if the close is being forced.
 \helpref{wxWindow::Close}{wxwindowclose},\rtfsp
 \helpref{wxWindow::OnClose}{wxwindowonclose},\rtfsp
 \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp
-\helpref{wxCloseEvent}{wxcloseevent}
-
-\membersection{wxWindow::OnDefaultAction}\label{wxwindowondefaultaction}
-
-\func{virtual void}{OnDefaultAction}{\param{wxControl* }{control}}
-
-Called when the user initiates the default action for a panel or
-dialog box, for example by double clicking on a listbox.
-
-\wxheading{Parameters}
-
-\docparam{control}{The control which caused the default action.}
-
-\wxheading{Remarks}
-
-TODO: eliminate this?? Or keep it for backward compatibility?
+\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
+\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession},\rtfsp
+\helpref{wxApp::OnEndSession}{wxapponendsession}
 
 \membersection{wxWindow::OnDropFiles}\label{wxwindowondropfiles}
 
@@ -1085,7 +1175,7 @@ terms of the client area, and are unscrolled, so you will need to do
 some calculations using the current view position to obtain logical,
 scrolled units.
 
-Here is an example of using the \helpref{wxUpdateIterator}{wxupdateiterator} class:
+Here is an example of using the \helpref{wxRegionIterator}{wxregioniterator} class:
 
 {\small%
 \begin{verbatim}
@@ -1099,7 +1189,7 @@ void MyWindow::OnPaint(wxPaintEvent& event)
   ViewStart(&vbX,&vbY);
 
   int vX,vY,vW,vH;                 // Dimensions of client area in pixels
-  wxUpdateIterator upd(this); // get the update rect list
+  wxRegionIterator upd(GetUpdateRegion()); // get the update rect list
 
   while (upd)
   {
@@ -1127,8 +1217,6 @@ void MyWindow::OnPaint(wxPaintEvent& event)
 \helpref{wxPaintDC}{wxpaintdc},\rtfsp
 \helpref{Event handling overview}{eventhandlingoverview}
 
-\membersection{wxWindow::OnScroll}\label{wxwindowonscroll}
-
 \func{void}{OnScroll}{\param{wxScrollEvent\& }{event}}
 
 Called when a scroll event is received from one of the window's built-in scrollbars.
@@ -1325,10 +1413,12 @@ functions so should not be required by the application programmer.
 
 \docparam{child}{Child window to remove.}
 
-\membersection{wxWindow::ScreenToClient}
+\membersection{wxWindow::ScreenToClient}\label{wxwindowscreentoclient}
 
 \constfunc{virtual void}{ScreenToClient}{\param{int* }{x}, \param{int* }{y}}
 
+\constfunc{virtual wxPoint}{ScreenToClient}{\param{const wxPoint\& }{pt}}
+
 Converts from screen to client window coordinates.
 
 \wxheading{Parameters}
@@ -1337,6 +1427,8 @@ Converts from screen to client window coordinates.
 
 \docparam{y}{Stores the screen x coordinate and receives the client x coordinate.}
 
+\docparam{pt}{The screen position for the second form of the function.}
+
 \membersection{wxWindow::ScrollWindow}\label{wxwindowscrollwindow}
 
 \func{virtual void}{ScrollWindow}{\param{int }{dx}, \param{int }{dy}, \param{const wxRect*}{ rect = NULL}}
@@ -1360,6 +1452,12 @@ Available only under Windows.
 Use this function to optimise your scrolling implementations, to minimise the area that must be
 redrawn.
 
+\membersection{wxWindow::SetAcceleratorTable}\label{wxwindowsetacceleratortable}
+
+\func{virtual void}{SetAcceleratorTable}{\param{const wxAcceleratorTable\&}{ accel}}
+
+Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxacceleratortable}.
+
 \membersection{wxWindow::SetAutoLayout}\label{wxwindowsetautolayout}
 
 \func{void}{SetAutoLayout}{\param{const bool}{ autoLayout}}
@@ -1598,10 +1696,8 @@ handling of pages and ranges.
 \wxheading{See also}
 
 \helpref{wxWindow::SetScrollPos}{wxwindowsetscrollpos},\rtfsp
-\helpref{wxWindow::SetScrollRange}{wxwindowsetscrollpage},\rtfsp
 \helpref{wxWindow::GetScrollPos}{wxwindowsetscrollpos},\rtfsp
-\helpref{wxWindow::GetScrollRange}{wxwindowsetscrollrange},\rtfsp
-\helpref{wxWindow::GetScrollPage}{wxwindowsetscrollrange},\rtfsp
+\helpref{wxWindow::GetScrollPage}{wxwindowsetscrollpage},\rtfsp
 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
 \end{comment}
 
@@ -1628,8 +1724,7 @@ application to take note of scrollbar attributes and redraw contents accordingly
 
 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar},\rtfsp
 \helpref{wxWindow::GetScrollPos}{wxwindowsetscrollpos},\rtfsp
-\helpref{wxWindow::GetScrollRange}{wxwindowsetscrollrange},\rtfsp
-\helpref{wxWindow::GetScrollThumb}{wxwindowsetscrollthumb},\rtfsp
+\helpref{wxWindow::GetScrollThumb}{wxwindowgetscrollthumb},\rtfsp
 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
 
 \begin{comment}
@@ -1660,8 +1755,7 @@ and usually the scrollbar will be automatically hidden.
 \helpref{wxWindow::SetScrollPos}{wxwindowsetscrollpos},\rtfsp
 \helpref{wxWindow::SetScrollPage}{wxwindowsetscrollpage},\rtfsp
 \helpref{wxWindow::GetScrollPos}{wxwindowsetscrollpos},\rtfsp
-\helpref{wxWindow::GetScrollRange}{wxwindowsetscrollrange},\rtfsp
-\helpref{wxWindow::GetScrollPage}{wxwindowsetscrollrange},\rtfsp
+\helpref{wxWindow::GetScrollPage}{wxwindowsetscrollpage},\rtfsp
 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
 \end{comment}
 
@@ -1670,10 +1764,14 @@ and usually the scrollbar will be automatically hidden.
 \func{virtual void}{SetSize}{\param{int}{ x}, \param{int}{ y}, \param{int}{ width}, \param{int}{ height},
  \param{int}{ sizeFlags = wxSIZE\_AUTO}}
 
+\func{virtual void}{SetSize}{\param{const wxRect\&}{ rect}}
+
 Sets the size and position of the window in pixels.
 
 \func{virtual void}{SetSize}{\param{int}{ width}, \param{int}{ height}}
 
+\func{virtual void}{SetSize}{\param{const wxSize\&}{ size}}
+
 Sets the size of the window in pixels.
 
 \wxheading{Parameters}
@@ -1690,6 +1788,10 @@ value should be used.}
 \docparam{height}{Required height position in pixels, or -1 to indicate that the existing
 value should be used.}
 
+\docparam{size}{\helpref{wxSize}{wxsize} object for setting the size.}
+
+\docparam{rect}{\helpref{wxRect}{wxrect} object for setting the position and size.}
+
 \docparam{sizeFlags}{Indicates the interpretation of other parameters. It is a bit list of the following:
 
 {\bf wxSIZE\_AUTO\_WIDTH}: a -1 width value is taken to indicate
@@ -1750,6 +1852,8 @@ The resizing increments are only significant under Motif or Xt.
 
 \func{virtual void}{SetClientSize}{\param{int}{ width}, \param{int}{ height}}
 
+\func{virtual void}{SetClientSize}{\param{const wxSize\&}{ size}}
+
 This sets the size of the window client area in pixels. Using this function to size a window
 tends to be more device-independent than \helpref{wxWindow::SetSize}{wxwindowsetsize}, since the application need not
 worry about what dimensions the border or title bar have when trying to fit the window
@@ -1761,6 +1865,8 @@ around panel items, for example.
 
 \docparam{height}{The required client area height.}
 
+\docparam{size}{The required client size.}
+
 \membersection{wxWindow::SetPalette}
 
 \func{virtual void}{SetPalette}{\param{wxPalette* }{palette}}
