Doc updates (debug stuff); Cygwin corrections

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

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 03dc109adad58ffd2d89f5bd813809c82c79dd48..7ed5e858dc8acfd58a30f5f2a76a3bf652b59366 100644 (file)
--- 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{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}.
 \end{twocollist}
 
 See also \helpref{window styles overview}{windowstyles}.


@@ -183,6 +185,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}


@@ -276,6 +332,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}


@@ -554,6 +620,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}


@@ -799,7 +876,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}
 


@@ -824,6 +901,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


@@ -837,22 +922,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}
 


@@ -1085,7 +1157,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}


@@ -1099,7 +1171,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)
   {


@@ -1127,8 +1199,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.


@@ -1246,13 +1316,6 @@ the commandInt member of the event to check the selected menu identifier.
 
 \docparam{y}{Required y position for the menu to appear.}
 
 
 \docparam{y}{Required y position for the menu to appear.}
 

-\wxheading{Remarks}
-
-Valid only for subwindows (panels, canvases and text windows).
-
-Sometimes this function does not function correctly under Motif, in which case
-please use \helpref{wxWindow::FakePopupMenu}{wxwindowfakepopupmenu} instead.
-

 \wxheading{See also}
 
 \helpref{wxMenu}{wxmenu}, \helpref{wxWindow::FakePopupMenu}{wxwindowfakepopupmenu}
 \wxheading{See also}
 
 \helpref{wxMenu}{wxmenu}, \helpref{wxWindow::FakePopupMenu}{wxwindowfakepopupmenu}


@@ -1367,6 +1430,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}}


@@ -1425,13 +1494,6 @@ You must call \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} to tell a
 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.
 

-% TODO: double click should always be allowed.
-%\membersection{wxWindow::SetDoubleClick}\label{setdoubleclick}
-%
-%\func{void}{SetDoubleClick}{\param{bool}{ allowDoubleClick}}
-%
-%For canvases, allows double click if {\it allowDoubleClick} is TRUE. The default is FALSE.
-

 \membersection{wxWindow::SetFocus}\label{wxwindowsetfocus}
 
 \func{virtual void}{SetFocus}{\void}
 \membersection{wxWindow::SetFocus}\label{wxwindowsetfocus}
 
 \func{virtual void}{SetFocus}{\void}


@@ -1612,10 +1674,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}
 


@@ -1642,8 +1702,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}


@@ -1664,9 +1723,9 @@ Sets the range of one of the built-in scrollbars.
 \wxheading{Remarks}
 
 The range of a scrollbar is the number of steps that the thumb may travel, rather than the total
 \wxheading{Remarks}
 
 The range of a scrollbar is the number of steps that the thumb may travel, rather than the total

-object length of the scrollbar. If you are implementing a scrolling canvas, for example, you
-would adjust the scroll range when the canvas is resized, by subtracting the canvas view size from the
-total virtual canvas size. When the two sizes are the same (all the canvas is visible), the range goes to zero
+object length of the scrollbar. If you are implementing a scrolling window, for example, you
+would adjust the scroll range when the window is resized, by subtracting the window view size from the
+total virtual window size. When the two sizes are the same (all the window is visible), the range goes to zero

 and usually the scrollbar will be automatically hidden.
 
 \wxheading{See also}
 and usually the scrollbar will be automatically hidden.
 
 \wxheading{See also}


@@ -1674,8 +1733,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}