X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/965b4f87d9d59c7c6d58da6567dca176d9131296..9bf58645bf1a7797f39cdf4823929ce950a06976:/docs/latex/wx/window.tex

diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex
index 44bfe0a816..fa07aa81b9 100644
--- 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{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
@@ -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.}
+\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}.
 
+\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}
@@ -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.
 
+\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}}
@@ -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
-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}
 
@@ -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.
 
+\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}
@@ -967,6 +1036,12 @@ Gets the window's title. Applicable only to frames and dialogs.
 
 \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}
@@ -1044,7 +1119,7 @@ Returns {\tt true} if the window is enabled for input, {\tt false} otherwise.
 
 \helpref{wxWindow::Enable}{wxwindowenable}
 
-\membersection{wxWindow:IsExposed}\label{wxwindowisexposed}
+\membersection{wxWindow::IsExposed}\label{wxwindowisexposed}
 
 \constfunc{bool}{IsExposed}{\param{int }{x}, \param{int }{y}}
 
@@ -1100,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.
 
+\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}
@@ -1650,6 +1733,27 @@ implements the following methods:\par
 %% \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}}}
@@ -1775,6 +1879,39 @@ repainted.
 
 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}
@@ -1929,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}.
 
+\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}}
@@ -2559,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.
 
-\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}}
@@ -2575,15 +2714,14 @@ create a new validator of this type.
 Attach a tooltip to the window.
 
 See also: \helpref{GetToolTip}{wxwindowgettooltip},
-          \helpref{wxToolTip}{wxtooltip}
-
+ \helpref{wxToolTip}{wxtooltip}
 
-\membersection{wxWindow::GetToolTip}\label{wxwindowgettooltip}
-
-\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}
 
@@ -2593,7 +2731,6 @@ Get the associated tooltip or NULL if none.
 
 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}}
@@ -2698,6 +2835,28 @@ Returns {\tt false} if a transfer failed.
 \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}
@@ -2709,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.
 
+\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}
