added and documented wxDEFINE_SCOPED_PTR_TYPE; improved docs a bit

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

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index be1eff42af94ac8e2304f0b1a40f1bd5eb39100f..1087970e5bc41eef00cd5fc4cb5521bd788be4f8 100644 (file)
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -35,8 +35,6 @@ for this style. }
 \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{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
 \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


@@ -48,12 +46,41 @@ new window area manually if you use this style. Currently only has an effect for
 Windows.}
 \twocolitem{\windowstyle{wxVSCROLL}}{Use this style to enable a vertical scrollbar.}
 \twocolitem{\windowstyle{wxHSCROLL}}{Use this style to enable a horizontal scrollbar.}
 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{wxALWAYS\_SHOW\_SB}}{If a window has scrollbars,
+disable them instead of hiding them when they are not needed (i.e. when the
+size of the window is big enough to not require the scrollbars to navigate it).
+This style is currently only implemented for wxMSW and wxUniversal and does
+nothing on the other platforms.}

 \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}.
 
 \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}.
 

+\wxheading{Extra window styles}
+
+The following are extra styles, set using \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle}.
+
+\twocolwidtha{5cm}%
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxWS\_EX\_VALIDATE\_RECURSIVELY}}{By default, Validate/TransferDataTo/FromWindow()
+only work on direct children of the window (compatible behaviour). Set this flag to make them recursively
+descend into all subwindows.}
+\twocolitem{\windowstyle{wxWS\_EX\_BLOCK\_EVENTS}}{wxCommandEvents and the objects of the derived classes are forwarded to the
+parent window and so on recursively by default. Using this flag for the
+given window allows to block this propagation at this window, i.e. prevent
+the events from being propagated further upwards. Dialogs have this
+flag on by default.}
+\twocolitem{\windowstyle{wxWS\_EX\_TRANSIENT}}{Don't use this window as an implicit parent for the other windows: this must
+be used with transient windows as otherwise there is the risk of creating a
+dialog/frame with this window as a parent which would lead to a crash if the
+parent is destroyed before the child.}
+\twocolitem{\windowstyle{wxWS\_EX\_PROCESS\_IDLE}}{This window should always process idle events, even
+if the mode set by \helpref{wxIdleEvent::SetMode}{wxidleeventsetmode} is wxIDLE\_PROCESS\_SPECIFIED.}
+\twocolitem{\windowstyle{wxWS\_EX\_PROCESS\_UI\_UPDATES}}{This window should always process UI update events,
+even if the mode set by \helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode} is wxUPDATE\_UI\_PROCESS\_SPECIFIED.}
+\end{twocollist}
+

 \wxheading{See also}
 
 \helpref{Event handling overview}{eventhandlingoverview}
 \wxheading{See also}
 
 \helpref{Event handling overview}{eventhandlingoverview}


@@ -218,9 +245,9 @@ or {\tt wxBOTH}.}
 
 \helpref{wxWindow::CentreOnParent}{wxwindowcenteronparent}
 
 
 \helpref{wxWindow::CentreOnParent}{wxwindowcenteronparent}
 

-\membersection{wxWindow::Clear}\label{wxwindowclear}
+\membersection{wxWindow::ClearBackground}\label{wxwindowclearbackground}

 
 

-\func{void}{Clear}{\void}
+\func{void}{ClearBackground}{\void}

 
 Clears the window by filling it with the current background colour. Does not
 cause an erase background event to be generated.
 
 Clears the window by filling it with the current background colour. Does not
 cause an erase background event to be generated.


@@ -396,7 +423,7 @@ Destroys all children of a window.  Called automatically by the destructor.
 
 \membersection{wxWindow::Disable}\label{wxwindowdisable}
 
 
 \membersection{wxWindow::Disable}\label{wxwindowdisable}
 

-\func{void}{Disable}{\void}
+\func{bool}{Disable}{\void}

 
 Disables the window, same as \helpref{Enable({\tt false})}{wxwindowenable}.
 
 
 Disables the window, same as \helpref{Enable({\tt false})}{wxwindowenable}.
 


@@ -405,6 +432,31 @@ Disables the window, same as \helpref{Enable({\tt false})}{wxwindowenable}.
 Returns {\tt true} if the window has been disabled, {\tt false} if it had been
 already disabled before the call to this function.
 
 Returns {\tt true} if the window has been disabled, {\tt false} if it had been
 already disabled before the call to this function.
 

+\membersection{wxWindow::DoUpdateWindowUI}\label{wxwindowdoupdatewindowui}
+
+\func{virtual void}{DoUpdateWindowUI}{\param{wxUpdateUIEvent\&}{ event}}
+
+Does the window-specific updating after processing the update event.
+This function is called by \helpref{wxWindow::UpdateWindowUI}{wxwindowupdatewindowui} 
+in order to check return values in the \helpref{wxUpdateUIEvent}{wxupdateuievent} and
+act appropriately. For example, to allow frame and dialog title updating, wxWindows
+implements this function as follows:
+
+\begin{verbatim}
+// do the window-specific processing after processing the update event
+void wxTopLevelWindowBase::DoUpdateWindowUI(wxUpdateUIEvent& event)
+{
+    if ( event.GetSetEnabled() )
+        Enable(event.GetEnabled());
+    
+    if ( event.GetSetText() )
+    {
+        if ( event.GetText() != GetTitle() )
+            SetTitle(event.GetText());
+    }
+}
+\end{verbatim}
+

 \membersection{wxWindow::DragAcceptFiles}\label{wxwindowdragacceptfiles}
 
 \func{virtual void}{DragAcceptFiles}{\param{bool}{ accept}}
 \membersection{wxWindow::DragAcceptFiles}\label{wxwindowdragacceptfiles}
 
 \func{virtual void}{DragAcceptFiles}{\param{bool}{ accept}}


@@ -522,7 +574,16 @@ The search is recursive in both cases.
 \func{virtual void}{Fit}{\void}
 
 Sizes the window so that it fits around its subwindows. This function won't do
 \func{virtual void}{Fit}{\void}
 
 Sizes the window so that it fits around its subwindows. This function won't do

-anything if there are no subwindows.
+anything if there are no subwindows and will only really work correctly if the
+sizers are used for the subwindows layout. Also, if the window has exactly one
+subwindow it is better (faster and the result is more precise as Fit adds some
+margin to account for fuzziness of its calculations) to call
+
+\begin{verbatim}
+    window->SetClientSize(child->GetSize());
+\end{verbatim}
+
+instead of calling Fit.

 
 \membersection{wxWindow::FitInside}\label{wxwindowfitinside}
 
 
 \membersection{wxWindow::FitInside}\label{wxwindowfitinside}
 


@@ -1058,7 +1119,7 @@ Returns {\tt true} if the window is enabled for input, {\tt false} otherwise.
 
 \helpref{wxWindow::Enable}{wxwindowenable}
 
 
 \helpref{wxWindow::Enable}{wxwindowenable}
 

-\membersection{wxWindow:IsExposed}\label{wxwindowisexposed}
+\membersection{wxWindow::IsExposed}\label{wxwindowisexposed}

 
 \constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}}
 
 
 \constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}}
 


@@ -1114,6 +1175,14 @@ for this window.
 See \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout}: when auto
 layout is on, this function gets called automatically when the window is resized.
 
 See \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout}: when auto
 layout is on, this function gets called automatically when the window is resized.
 

+\membersection{wxWindow::LineDown}\label{wxwindowlinedown}
+
+This is just a wrapper for \helpref{ScrollLines()}{wxwindowscrolllines}$(1)$.
+
+\membersection{wxWindow::LineUp}\label{wxwindowlineup}
+
+This is just a wrapper for \helpref{ScrollLines()}{wxwindowscrolllines}$(-1)$.
+

 \membersection{wxWindow::Lower}\label{wxwindowlower}
 
 \func{void}{Lower}{\void}
 \membersection{wxWindow::Lower}\label{wxwindowlower}
 
 \func{void}{Lower}{\void}


@@ -1664,6 +1733,27 @@ implements the following methods:\par
 %% \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent},\rtfsp
 %% \helpref{Event handling overview}{eventhandlingoverview}
 
 %% \helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent},\rtfsp
 %% \helpref{Event handling overview}{eventhandlingoverview}
 

+\membersection{wxWindow::OnInternalIdle}\label{wxwindowoninternalidle}
+
+\func{virtual void}{OnInternalIdle}{\void}
+
+This virtual function is normally only used internally, but
+sometimes an application may need it to implement functionality
+that should not be disabled by an application defining an OnIdle
+handler in a derived class.
+
+This function may be used to do delayed painting, for example,
+and most implementations call \helpref{wxWindow::UpdateWindowUI}{wxwindowupdatewindowui} 
+in order to send update events to the window in idle time.
+
+\membersection{wxWindow::PageDown}\label{wxwindowpagedown}
+
+This is just a wrapper for \helpref{ScrollPages()}{wxwindowscrollpages}$(1)$.
+
+\membersection{wxWindow::PageUp}\label{wxwindowpageup}
+
+This is just a wrapper for \helpref{ScrollPages()}{wxwindowscrollpages}$(-1)$.
+

 \membersection{wxWindow::PopEventHandler}\label{wxwindowpopeventhandler}
 
 \constfunc{wxEvtHandler*}{PopEventHandler}{\param{bool }{deleteHandler = {\tt false}}}
 \membersection{wxWindow::PopEventHandler}\label{wxwindowpopeventhandler}
 
 \constfunc{wxEvtHandler*}{PopEventHandler}{\param{bool }{deleteHandler = {\tt false}}}


@@ -1789,6 +1879,39 @@ repainted.
 
 This is the same as \helpref{Refresh}{wxwindowrefresh} but has a nicer syntax.
 
 
 This is the same as \helpref{Refresh}{wxwindowrefresh} but has a nicer syntax.
 

+\membersection{wxWindow::RegisterHotKey}\label{wxwindowregisterhotkey}
+
+\func{bool}{RegisterHotKey}{\param{int}{ hotkeyId}, \param{int}{ modifiers}, \param{int}{ virtualKeyCode}}
+
+Registers a system wide hotkey. Every time the user presses the hotkey registered here, this window
+will receive a hotkey event. It will receive the event even if the application is in the background
+and does not have the input focus because the user is working with some other application.
+
+\wxheading{Parameters}
+
+\docparam{hotkeyId}{Numeric identifier of the hotkey. For applications this must be between 0 and 0xBFFF. If
+this function is called from a shared DLL, it must be a system wide unique identifier between 0xC000 and 0xFFFF.
+This is a MSW specific detail.}
+
+\docparam{modifiers}{A bitwise combination of {\tt wxMOD\_SHIFT}, {\tt wxMOD\_CONTROL}, {\tt wxMOD\_ALT}
+or {\tt wxMOD\_WIN} specifying the modifier keys that have to be pressed along with the key.}
+
+\docparam{virtualKeyCode}{The virtual key code of the hotkey.}
+
+\wxheading{Return value}
+
+{\tt true} if the hotkey was registered successfully. {\tt false} if some other application already registered a
+hotkey with this modifier/virtualKeyCode combination.
+
+\wxheading{Remarks}
+
+Use EVT\_HOTKEY(hotkeyId, fnc) in the event table to capture the event.
+This function is currently only implemented under MSW.
+
+\wxheading{See also}
+
+\helpref{wxWindow::UnregisterHotKey}{wxwindowunregisterhotkey}
+

 \membersection{wxWindow::ReleaseMouse}\label{wxwindowreleasemouse}
 
 \func{virtual void}{ReleaseMouse}{\void}
 \membersection{wxWindow::ReleaseMouse}\label{wxwindowreleasemouse}
 
 \func{virtual void}{ReleaseMouse}{\void}


@@ -1989,11 +2112,11 @@ The background colour is usually painted by the default\rtfsp
 under Windows and automatically under GTK.
 
 Note that setting the background colour does not cause an immediate refresh, so you
 under Windows and automatically under GTK.
 
 Note that setting the background colour does not cause an immediate refresh, so you

-may wish to call \helpref{wxWindow::Clear}{wxwindowclear} or \helpref{wxWindow::Refresh}{wxwindowrefresh} after
+may wish to call \helpref{wxWindow::ClearBackground}{wxwindowclearbackground} or \helpref{wxWindow::Refresh}{wxwindowrefresh} after

 calling this function.
 
 calling this function.
 

-Use this function with care under GTK as the new appearance of the window might
-not look equally well when used with "Themes", i.e GTK's ability to change its
+Use this function with care under GTK+ as the new appearance of the window might
+not look equally well when used with "Themes", i.e GTK+'s ability to change its

 look as the user wishes with run-time loadable modules.
 
 \wxheading{See also}
 look as the user wishes with run-time loadable modules.
 
 \wxheading{See also}


@@ -2001,7 +2124,7 @@ look as the user wishes with run-time loadable modules.
 \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour},\rtfsp
 \helpref{wxWindow::SetForegroundColour}{wxwindowsetforegroundcolour},\rtfsp
 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp
 \helpref{wxWindow::GetBackgroundColour}{wxwindowgetbackgroundcolour},\rtfsp
 \helpref{wxWindow::SetForegroundColour}{wxwindowsetforegroundcolour},\rtfsp
 \helpref{wxWindow::GetForegroundColour}{wxwindowgetforegroundcolour},\rtfsp

-\helpref{wxWindow::Clear}{wxwindowclear},\rtfsp
+\helpref{wxWindow::ClearBackground}{wxwindowclearbackground},\rtfsp

 \helpref{wxWindow::Refresh}{wxwindowrefresh},\rtfsp
 \helpref{wxEraseEvent}{wxeraseevent}
 
 \helpref{wxWindow::Refresh}{wxwindowrefresh},\rtfsp
 \helpref{wxEraseEvent}{wxeraseevent}
 


@@ -2582,13 +2705,6 @@ defined by a user's selected theme.
 Dialogs, notebook pages and the status bar have this flag set to true
 by default so that the default look and feel is simulated best.
 
 Dialogs, notebook pages and the status bar have this flag set to true
 by default so that the default look and feel is simulated best.
 

-\membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator}
-
-\func{virtual void}{SetValidator}{\param{const wxValidator\&}{ validator}}
-
-Deletes the current validator (if any) and sets the window validator, having called wxValidator::Clone to
-create a new validator of this type.
-

 \membersection{wxWindow::SetToolTip}\label{wxwindowsettooltip}
 
 \func{void}{SetToolTip}{\param{const wxString\& }{tip}}
 \membersection{wxWindow::SetToolTip}\label{wxwindowsettooltip}
 
 \func{void}{SetToolTip}{\param{const wxString\& }{tip}}


@@ -2600,6 +2716,13 @@ Attach a tooltip to the window.
 See also: \helpref{GetToolTip}{wxwindowgettooltip},
  \helpref{wxToolTip}{wxtooltip}
 
 See also: \helpref{GetToolTip}{wxwindowgettooltip},
  \helpref{wxToolTip}{wxtooltip}
 

+\membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator}
+
+\func{virtual void}{SetValidator}{\param{const wxValidator\&}{ validator}}
+
+Deletes the current validator (if any) and sets the window validator, having called wxValidator::Clone to
+create a new validator of this type.
+

 \membersection{wxWindow::SetVirtualSize}\label{wxwindowsetvirtualsize}
 
 \func{void}{SetVirtualSize}{\param{int}{ width}, \param{int}{ height}}
 \membersection{wxWindow::SetVirtualSize}\label{wxwindowsetvirtualsize}
 
 \func{void}{SetVirtualSize}{\param{int}{ width}, \param{int}{ height}}


@@ -2712,6 +2835,28 @@ Returns {\tt false} if a transfer failed.
 \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow},\rtfsp
 \helpref{wxValidator}{wxvalidator}, \helpref{wxWindow::Validate}{wxwindowvalidate}
 
 \helpref{wxWindow::TransferDataFromWindow}{wxwindowtransferdatafromwindow},\rtfsp
 \helpref{wxValidator}{wxvalidator}, \helpref{wxWindow::Validate}{wxwindowvalidate}
 

+\membersection{wxWindow::UnregisterHotKey}\label{wxwindowunregisterhotkey}
+
+\func{bool}{UnregisterHotKey}{\param{int}{ hotkeyId}}
+
+Unregisters a system wide hotkey.
+
+\wxheading{Parameters}
+
+\docparam{hotkeyId}{Numeric identifier of the hotkey. Must be the same id that was passed to RegisterHotKey.}
+
+\wxheading{Return value}
+
+{\tt true} if the hotkey was unregistered successfully, {\tt false} if the id was invalid.
+
+\wxheading{Remarks}
+
+This function is currently only implemented under MSW.
+
+\wxheading{See also}
+
+\helpref{wxWindow::RegisterHotKey}{wxwindowregisterhotkey}
+

 \membersection{wxWindow::Update}\label{wxwindowupdate}
 
 \func{virtual void}{Update}{\void}
 \membersection{wxWindow::Update}\label{wxwindowupdate}
 
 \func{virtual void}{Update}{\void}


@@ -2723,6 +2868,54 @@ nothing if the window hadn't been already repainted. Use
 \helpref{Refresh}{wxwindowrefresh} first if you want to immediately redraw the
 window unconditionally.
 
 \helpref{Refresh}{wxwindowrefresh} first if you want to immediately redraw the
 window unconditionally.
 

+\membersection{wxWindow::UpdateWindowUI}\label{wxwindowupdatewindowui}
+
+\func{virtual void}{UpdateWindowUI}{\param{long}{ flags = wxUPDATE_UI_NONE}}
+
+This function sends \helpref{wxUpdateUIEvents}{wxupdateuievent} to
+the window. The particular implementation depends on the window; for
+example a wxToolBar will send an update UI event for each toolbar button,
+and a wxFrame will send an update UI event for each menubar menu item.
+You can call this function from your application to ensure that your
+UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers
+are concerned). This may be necessary if you have called 
+\helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode} or 
+\helpref{wxUpdateUIEvent::SetUpdateInterval}{wxupdateuieventsetupdateinterval} to
+limit the overhead that wxWindows incurs by sending update UI events in idle time.
+
+{\it flags} should be a bitlist of one or more of the following values.
+
+\begin{verbatim}
+enum wxUpdateUI
+{
+    wxUPDATE_UI_NONE          = 0x0000, // No particular value
+    wxUPDATE_UI_RECURSE       = 0x0001, // Call the function for descendants
+    wxUPDATE_UI_FROMIDLE      = 0x0002  // Invoked from On(Internal)Idle
+};
+\end{verbatim}
+
+If you are calling this function from an OnInternalIdle or OnIdle
+function, make sure you pass the wxUPDATE\_UI\_FROMIDLE flag, since
+this tells the window to only update the UI elements that need
+to be updated in idle time. Some windows update their elements
+only when necessary, for example when a menu is about to be shown.
+The following is an example of how to call UpdateWindowUI from
+an idle function.
+
+\begin{verbatim}
+void MyWindow::OnInternalIdle()
+{
+    if (wxUpdateUIEvent::CanUpdate(this))
+        UpdateWindowUI(wxUPDATE_UI_FROMIDLE);
+}
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxUpdateUIEvent}{wxupdateuievent}, 
+\helpref{wxWindow::DoUpdateWindowUI}{wxwindowdoupdatewindowui}, 
+\helpref{wxWindow::OnInternalIdle}{wxwindowoninternalidle}
+

 \membersection{wxWindow::Validate}\label{wxwindowvalidate}
 
 \func{virtual bool}{Validate}{\void}
 \membersection{wxWindow::Validate}\label{wxwindowvalidate}
 
 \func{virtual bool}{Validate}{\void}