don't include MDI headers if !wxUSE_MDI

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

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 2df7a84065d030a618f898dffb580be85ca4918e..fa07aa81b99d12592f143db24a076e389511cb2b 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}


@@ -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}
 


@@ -548,6 +609,14 @@ wxTextCtrl under wxGTK) but is not implemented on all platforms nor for all
 controls so it is mostly just a hint to wxWindows and not a mandatory
 directive.
 
 controls so it is mostly just a hint to wxWindows and not a mandatory
 directive.
 

+\membersection{wxWindow::GetAccessible}\label{wxwindowgetaccessible}
+
+\func{wxAccessibile*}{GetAccessible}{\void}
+
+Returns the accessible object for this window, if any.
+
+See also \helpref{wxAccessible}{wxaccessible}.
+

 \membersection{wxWindow::GetAdjustedBestSize}\label{wxwindowgetadjustedbestsize}
 
 \constfunc{wxSize}{GetAdjustedBestSize}{\void}
 \membersection{wxWindow::GetAdjustedBestSize}\label{wxwindowgetadjustedbestsize}
 
 \constfunc{wxSize}{GetAdjustedBestSize}{\void}


@@ -967,6 +1036,12 @@ Gets the window's title. Applicable only to frames and dialogs.
 
 \helpref{wxWindow::SetTitle}{wxwindowsettitle}
 
 
 \helpref{wxWindow::SetTitle}{wxwindowsettitle}
 

+\membersection{wxWindow::GetToolTip}\label{wxwindowgettooltip}
+
+\constfunc{wxToolTip*}{GetToolTip}{\void}
+
+Get the associated tooltip or NULL if none.
+

 \membersection{wxWindow::GetUpdateRegion}\label{wxwindowgetupdateregion}
 
 \constfunc{virtual wxRegion}{GetUpdateRegion}{\void}
 \membersection{wxWindow::GetUpdateRegion}\label{wxwindowgetupdateregion}
 
 \constfunc{virtual wxRegion}{GetUpdateRegion}{\void}


@@ -1044,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}}
 


@@ -1100,25 +1175,13 @@ 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::LoadFromResource}\label{wxwindowloadfromresource}
+\membersection{wxWindow::LineDown}\label{wxwindowlinedown}

 
 

-\func{virtual bool}{LoadFromResource}{\param{wxWindow* }{parent},\rtfsp
-\param{const wxString\& }{resourceName}, \param{const wxResourceTable* }{resourceTable = NULL}}
+This is just a wrapper for \helpref{ScrollLines()}{wxwindowscrolllines}$(1)$.

 
 

-Loads a panel or dialog from a resource file.
+\membersection{wxWindow::LineUp}\label{wxwindowlineup}

 
 

-\wxheading{Parameters}
-
-\docparam{parent}{Parent window.}
-
-\docparam{resourceName}{The name of the resource to load.}
-
-\docparam{resourceTable}{The resource table to load it from. If this is NULL, the
-default resource table will be used.}
-
-\wxheading{Return value}
-
-{\tt true} if the operation succeeded, otherwise {\tt false}.
+This is just a wrapper for \helpref{ScrollLines()}{wxwindowscrolllines}$(-1)$.

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


@@ -1670,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}}}


@@ -1795,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}


@@ -1949,6 +2066,15 @@ redrawn. Note that it is rarely required to call this function from a user progr
 
 Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxacceleratortable}.
 
 
 Sets the accelerator table for this window. See \helpref{wxAcceleratorTable}{wxacceleratortable}.
 

+\membersection{wxWindow::SetAccessible}\label{wxwindowsetaccessible}
+
+\func{void}{SetAccessible}{\param{wxAccessibile*}{ accessible}}
+
+Sets the accessible for this window. Any existing accessible for this window
+will be deleted first, if not identical to {\it accessible}.
+
+See also \helpref{wxAccessible}{wxaccessible}.
+

 \membersection{wxWindow::SetAutoLayout}\label{wxwindowsetautolayout}
 
 \func{void}{SetAutoLayout}{\param{bool}{ autoLayout}}
 \membersection{wxWindow::SetAutoLayout}\label{wxwindowsetautolayout}
 
 \func{void}{SetAutoLayout}{\param{bool}{ autoLayout}}


@@ -2579,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}}


@@ -2595,15 +2714,14 @@ create a new validator of this type.
 Attach a tooltip to the window.
 
 See also: \helpref{GetToolTip}{wxwindowgettooltip},
 Attach a tooltip to the window.
 
 See also: \helpref{GetToolTip}{wxwindowgettooltip},

-          \helpref{wxToolTip}{wxtooltip}
-
-
-\membersection{wxWindow::GetToolTip}\label{wxwindowgettooltip}
+ \helpref{wxToolTip}{wxtooltip}

 
 

-\constfunc{wxToolTip*}{GetToolTip}{\void}
+\membersection{wxWindow::SetValidator}\label{wxwindowsetvalidator}

 
 

-Get the associated tooltip or NULL if none.
+\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}
 
 
 \membersection{wxWindow::SetVirtualSize}\label{wxwindowsetvirtualsize}
 


@@ -2613,7 +2731,6 @@ Get the associated tooltip or NULL if none.
 
 Sets the virtual size of the window in pixels.
 
 
 Sets the virtual size of the window in pixels.
 

-

 \membersection{wxWindow::SetVirtualSizeHints}\label{wxwindowsetvirtualsizehints}
 
 \func{virtual void}{SetVirtualSizeHints}{\param{int}{ minW},\param{int}{ minH}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1}}
 \membersection{wxWindow::SetVirtualSizeHints}\label{wxwindowsetvirtualsizehints}
 
 \func{virtual void}{SetVirtualSizeHints}{\param{int}{ minW},\param{int}{ minH}, \param{int}{ maxW=-1}, \param{int}{ maxH=-1}}


@@ -2718,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}


@@ -2729,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}