added wxNode::IndexOf and wxList::IndexOf (patch by Frank McIngvale)

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

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 609309b05baff59a65a06a5114ac57acda71f513..65a31976593a48ef3e3b26c9c537d7db7c66eb55 100644 (file)
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -147,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 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
 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


@@ -155,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{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}}
 \membersection{wxWindow::Close}\label{wxwindowclose}
 
 \func{virtual bool}{Close}{\param{const bool}{ force = FALSE}}


@@ -185,6 +189,60 @@ Applies to managed windows (wxFrame and wxDialog classes) only.
 \helpref{wxWindow::Destroy}{wxwindowdestroy},\rtfsp
 \helpref{wxCloseEvent}{wxcloseevent}
 
 \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}
 \membersection{wxWindow::Destroy}\label{wxwindowdestroy}
 
 \func{virtual bool}{Destroy}{\void}


@@ -278,6 +336,16 @@ Note that this is a static function, so it can be called without needing a wxWin
 
 \helpref{wxWindow::SetFocus}{wxwindowsetfocus}
 
 
 \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}
 \membersection{wxWindow::Fit}\label{wxwindowfit}
 
 \func{virtual void}{Fit}{\void}


@@ -319,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 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.
 
 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.
 


@@ -463,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.
 
 
 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}
 \membersection{wxWindow::GetReturnCode}\label{wxwindowgetreturncode}
 
 \func{int}{GetReturnCode}{\void}


@@ -509,10 +585,12 @@ Returns the built-in scrollbar range.
 
 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar}
 
 
 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar}
 

-\membersection{wxWindow::GetSize}
+\membersection{wxWindow::GetSize}\label{wxwindowgetsize}

 
 \constfunc{virtual void}{GetSize}{\param{int* }{width}, \param{int* }{height}}
 
 
 \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}
 This gets the size of the entire window in pixels.
 
 \wxheading{Parameters}


@@ -556,6 +634,17 @@ Gets the window's title. Applicable only to frames and dialogs.
 
 \helpref{wxWindow::SetTitle}{wxwindowsettitle}
 
 
 \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}
 \membersection{wxWindow::GetWindowStyleFlag}
 
 \constfunc{long}{GetWindowStyleFlag}{\void}


@@ -657,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{int}{ x}, \param{int}{ y}}
 

+\func{void}{Move}{\param{const wxPoint\&}{ pt}}
+

 Moves the window to the given position.
 
 \wxheading{Parameters}
 Moves the window to the given position.
 
 \wxheading{Parameters}


@@ -665,6 +756,8 @@ Moves the window to the given position.
 
 \docparam{y}{Required y 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
 \wxheading{Remarks}
 
 Implementations of SetSize can also implicitly implement the


@@ -801,7 +894,7 @@ you may delete other windows.
 
 \wxheading{Remarks}
 
 
 \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}
 
 
 \wxheading{See also}
 


@@ -826,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.
 
 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
 \wxheading{Remarks}
 
 The \helpref{wxWindow::OnClose}{wxwindowonclose} virtual function remains


@@ -839,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{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}
 
 
 \membersection{wxWindow::OnDropFiles}\label{wxwindowondropfiles}
 


@@ -1087,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.
 
 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}
 
 {\small%
 \begin{verbatim}


@@ -1101,7 +1189,7 @@ void MyWindow::OnPaint(wxPaintEvent& event)
   ViewStart(&vbX,&vbY);
 
   int vX,vY,vW,vH;                 // Dimensions of client area in pixels
   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)
   {
 
   while (upd)
   {


@@ -1129,8 +1217,6 @@ void MyWindow::OnPaint(wxPaintEvent& event)
 \helpref{wxPaintDC}{wxpaintdc},\rtfsp
 \helpref{Event handling overview}{eventhandlingoverview}
 
 \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.
 \func{void}{OnScroll}{\param{wxScrollEvent\& }{event}}
 
 Called when a scroll event is received from one of the window's built-in scrollbars.


@@ -1327,10 +1413,12 @@ functions so should not be required by the application programmer.
 
 \docparam{child}{Child window to remove.}
 
 
 \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 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}
 Converts from screen to client window coordinates.
 
 \wxheading{Parameters}


@@ -1339,6 +1427,8 @@ Converts from screen to client window coordinates.
 
 \docparam{y}{Stores the screen x coordinate and receives the client x coordinate.}
 
 
 \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}}
 \membersection{wxWindow::ScrollWindow}\label{wxwindowscrollwindow}
 
 \func{virtual void}{ScrollWindow}{\param{int }{dx}, \param{int }{dy}, \param{const wxRect*}{ rect = NULL}}


@@ -1362,6 +1452,12 @@ Available only under Windows.
 Use this function to optimise your scrolling implementations, to minimise the area that must be
 redrawn.
 
 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}}
 \membersection{wxWindow::SetAutoLayout}\label{wxwindowsetautolayout}
 
 \func{void}{SetAutoLayout}{\param{const bool}{ autoLayout}}


@@ -1600,10 +1696,8 @@ handling of pages and ranges.
 \wxheading{See also}
 
 \helpref{wxWindow::SetScrollPos}{wxwindowsetscrollpos},\rtfsp
 \wxheading{See also}
 
 \helpref{wxWindow::SetScrollPos}{wxwindowsetscrollpos},\rtfsp

-\helpref{wxWindow::SetScrollRange}{wxwindowsetscrollpage},\rtfsp

 \helpref{wxWindow::GetScrollPos}{wxwindowsetscrollpos},\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}
 
 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
 \end{comment}
 


@@ -1630,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::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}
 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
 
 \begin{comment}


@@ -1662,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::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}
 
 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
 \end{comment}
 


@@ -1672,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{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}}
 
 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}
 Sets the size of the window in pixels.
 
 \wxheading{Parameters}


@@ -1692,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{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
 \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


@@ -1752,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{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
 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


@@ -1763,6 +1865,8 @@ around panel items, for example.
 
 \docparam{height}{The required client area height.}
 
 
 \docparam{height}{The required client area height.}
 

+\docparam{size}{The required client size.}
+

 \membersection{wxWindow::SetPalette}
 
 \func{virtual void}{SetPalette}{\param{wxPalette* }{palette}}
 \membersection{wxWindow::SetPalette}
 
 \func{virtual void}{SetPalette}{\param{wxPalette* }{palette}}