X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3ca6a5f04692678cd2d9f3ea0843fc3f5a0b254f..afbdbdb491884557f4f510f9749c0c7580b50795:/docs/latex/wx/upduievt.tex

diff --git a/docs/latex/wx/upduievt.tex b/docs/latex/wx/upduievt.tex
index 925f4b6ef0..8cb08b8aa5 100644
--- a/docs/latex/wx/upduievt.tex
+++ b/docs/latex/wx/upduievt.tex
@@ -5,6 +5,7 @@ to give an application the chance to update various user interface elements.
 
 \wxheading{Derived from}
 
+\helpref{wxCommandEvent}{wxcommandevent}\\
 \helpref{wxEvent}{wxevent}\\
 \helpref{wxObject}{wxobject}
 
@@ -45,6 +46,29 @@ These events will work for popup menus as well as menubars. Just before a menu i
 up, \helpref{wxMenu::UpdateUI}{wxmenuupdateui} is called to process any UI events for
 the window that owns the menu.
 
+If you find that the overhead of UI update processing is affecting
+your application, you can do one or both of the following:
+
+\begin{enumerate}
+\item Call \helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode} with
+a value of wxUPDATE\_UI\_PROCESS\_SPECIFIED, and set the extra style
+wxWS\_EX\_PROCESS\_UPDATE\_EVENTS for every window that should receive update events.
+No other windows will receive update events.
+\item Call \helpref{wxUpdateUIEvent::SetUpdateInterval}{wxupdateuieventsetupdateinterval} with
+a millisecond value to set the delay between updates. You may need
+to call \helpref{wxWindow::UpdateWindowUI}{wxwindowupdatewindowui} at critical
+points, for example when a dialog is about to be shown, in case the user
+sees a slight delay before windows are updated.
+\end{enumerate}
+
+Note that although events are sent in idle time, defining a wxIdleEvent
+handler for a window does not affect this because the events are sent from \helpref{wxWindow::OnInternalIdle}{wxwindowoninternalidle} 
+which is {\bf always} called in idle time.
+
+wxWindows tries to optimize update events on some platforms. On Windows
+and GTK+, events for menubar items are only sent when the menu is about
+to be shown, and not in idle time.
+
 \wxheading{See also}
 
 \helpref{Event handling overview}{eventhandlingoverview}
@@ -61,31 +85,31 @@ Constructor.
 
 \member{bool}{m\_checked}
 
-TRUE if the element should be checked, FALSE otherwise.
+true if the element should be checked, false otherwise.
 
 \membersection{wxUpdateUIEvent::m\_enabled}
 
 \member{bool}{m\_checked}
 
-TRUE if the element should be enabled, FALSE otherwise.
+true if the element should be enabled, false otherwise.
 
 \membersection{wxUpdateUIEvent::m\_setChecked}
 
 \member{bool}{m\_setChecked}
 
-TRUE if the application has set the {\bf m\_checked} member.
+true if the application has set the {\bf m\_checked} member.
 
 \membersection{wxUpdateUIEvent::m\_setEnabled}
 
 \member{bool}{m\_setEnabled}
 
-TRUE if the application has set the {\bf m\_enabled} member.
+true if the application has set the {\bf m\_enabled} member.
 
 \membersection{wxUpdateUIEvent::m\_setText}
 
 \member{bool}{m\_setText}
 
-TRUE if the application has set the {\bf m\_text} member.
+true if the application has set the {\bf m\_text} member.
 
 \membersection{wxUpdateUIEvent::m\_text}
 
@@ -94,6 +118,29 @@ TRUE if the application has set the {\bf m\_text} member.
 Holds the text with which the the application wishes to
 update the UI element.
 
+\membersection{wxUpdateUIEvent::CanUpdate}\label{wxupdateuieventcanupdate}
+
+\func{static bool}{CanUpdate}{\param{wxWindow*}{ window}}
+
+Returns {\tt true} if it is appropriate to update (send UI update events to)
+this window.
+
+This function looks at the mode used (see \helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode}),
+the wxWS\_EX\_PROCESS\_UPDATE\_EVENTS flag in {\it window},
+the time update events were last sent in idle time, and
+the update interval, to determine whether events should be sent to
+this window now. By default this will always return {\tt true} because
+the update mode is initially wxUPDATE\_UI\_PROCESS\_ALL and
+the interval is set to 0; so update events will be sent as
+often as possible. You can reduce the frequency that events
+are sent by changing the mode and/or setting an update interval.
+
+\wxheading{See also}
+
+\helpref{wxUpdateUIEvent::ResetUpdateTime}{wxupdateuieventresetupdatetime}, 
+\helpref{wxUpdateUIEvent::SetUpdateInterval}{wxupdateuieventsetupdateinterval}, 
+\helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode}
+
 \membersection{wxUpdateUIEvent::Check}\label{wxupdateuieventcheck}
 
 \func{void}{Check}{\param{bool}{ check}}
@@ -110,31 +157,31 @@ Enable or disable the UI element.
 
 \constfunc{bool}{GetChecked}{\void}
 
-Returns TRUE if the UI element should be checked.
+Returns true if the UI element should be checked.
 
 \membersection{wxUpdateUIEvent::GetEnabled}\label{wxupdateuieventgetenabled}
 
 \constfunc{bool}{GetEnabled}{\void}
 
-Returns TRUE if the UI element should be enabled.
+Returns true if the UI element should be enabled.
 
 \membersection{wxUpdateUIEvent::GetSetChecked}\label{wxupdateuieventgetsetchecked}
 
 \constfunc{bool}{GetSetChecked}{\void}
 
-Returns TRUE if the application has called {\bf SetChecked}. For wxWindows internal use only.
+Returns true if the application has called {\bf SetChecked}. For wxWindows internal use only.
 
 \membersection{wxUpdateUIEvent::GetSetEnabled}\label{wxupdateuieventgetsetenabled}
 
 \constfunc{bool}{GetSetEnabled}{\void}
 
-Returns TRUE if the application has called {\bf SetEnabled}. For wxWindows internal use only.
+Returns true if the application has called {\bf SetEnabled}. For wxWindows internal use only.
 
 \membersection{wxUpdateUIEvent::GetSetText}\label{wxupdateuieventgetsettext}
 
 \constfunc{bool}{GetSetText}{\void}
 
-Returns TRUE if the application has called {\bf SetText}. For wxWindows internal use only.
+Returns true if the application has called {\bf SetText}. For wxWindows internal use only.
 
 \membersection{wxUpdateUIEvent::GetText}\label{wxupdateuieventgettext}
 
@@ -142,9 +189,80 @@ Returns TRUE if the application has called {\bf SetText}. For wxWindows internal
 
 Returns the text that should be set for the UI element.
 
+\membersection{wxUpdateUIEvent::GetMode}\label{wxupdateuieventgetmode}
+
+\func{static wxUpdateUIMode}{GetMode}{\void}
+
+Static function returning a value specifying how wxWindows
+will send update events: to all windows, or only to those which specify that they
+will process the events.
+
+See \helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode}.
+
+\membersection{wxUpdateUIEvent::GetUpdateInterval}\label{wxupdateuieventgetupdateinterval}
+
+\func{static long}{GetUpdateInterval}{\void}
+
+Returns the current interval between updates in milliseconds.
+-1 disables updates, 0 updates as frequently as possible.
+
+See \helpref{wxUpdateUIEvent::SetUpdateInterval}{wxupdateuieventsetupdateinterval}.
+
+\membersection{wxUpdateUIEvent::ResetUpdateTime}\label{wxupdateuieventresetupdatetime}
+
+\func{static void}{ResetUpdateTime}{\void}
+
+Used internally to reset the last-updated time to the
+current time. It is assumed that update events are
+normally sent in idle time, so this is called at the end of
+idle processing.
+
+\wxheading{See also}
+
+\helpref{wxUpdateUIEvent::CanUpdate}{wxupdateuieventcanupdate}, 
+\helpref{wxUpdateUIEvent::SetUpdateInterval}{wxupdateuieventsetupdateinterval}, 
+\helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode}
+
+\membersection{wxUpdateUIEvent::SetMode}\label{wxupdateuieventsetmode}
+
+\func{static void}{SetMode}{\param{wxIdleMode }{mode}}
+
+Specify how wxWindows will send update events: to
+all windows, or only to those which specify that they
+will process the events.
+
+{\it mode} may be one of the following values.
+The default is wxUPDATE\_UI\_PROCESS\_ALL.
+
+\begin{verbatim}
+enum wxUpdateUIMode
+{
+        // Send UI update events to all windows
+    wxUPDATE_UI_PROCESS_ALL,
+
+        // Send UI update events to windows that have
+        // the wxWS_EX_PROCESS_UI_UPDATES flag specified
+    wxUPDATE_UI_PROCESS_SPECIFIED
+};
+\end{verbatim}
+
 \membersection{wxUpdateUIEvent::SetText}\label{wxupdateuieventsettext}
 
 \func{void}{SetText}{\param{const wxString\&}{ text}}
 
 Sets the text for this UI element.
 
+\membersection{wxUpdateUIEvent::SetUpdateInterval}\label{wxupdateuieventsetupdateinterval}
+
+\func{static void}{SetUpdateInterval}{\param{long }{updateInterval}}
+
+Sets the interval between updates in milliseconds.
+Set to -1 to disable updates, or to 0 to update as frequently as possible.
+The default is 0.
+
+Use this to reduce the overhead of UI update events if your application
+has a lot of windows. If you set the value to -1 or greater than 0,
+you may also need to call \helpref{wxWindow::UpdateWindowUI}{wxwindowupdatewindowui} 
+at appropriate points in your application, such as when a dialog
+is about to be shown.
+