- Moved wxApp::SendIdleEvents and wxApp::ProcessIdle into common code.

- wxWindow::OnInternalIdle is now used in all ports, and ensures that user OnIdle events do not interfere with crucial internal processing. - wxWindow::UpdateWindowUI is now a documented function that sends wxUpdateUIEvents, and can be overridden. It has a helper function DoUpdateWindowUI for taking appropriate wxUpdateUIEvent action. - Added functions to wxUpdateUIEvent: Set/GetMode, Set/GetUpdateInterval, CanUpdate, to assist with optimising update event frequency. - Added functions to wxIdleEvent: Set/GetMode, CanSend, to determine whether a window should receive idle events. - Added wxWS_EX_PROCESS_IDLE, wxWS_EX_PROCESS_UI_UPDATES window styles for use with conservative idle and update event modes. - wxMSW and wxGTK now send menu update events only when a menu is about to be used. - Added WM_INITMENU processing instead of WM_ENTERMENULOOP, or accelerators don't always get called since menu items may still be disabled. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@21789 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
2003-07-09 10:15:21 +00:00
parent 50b27824da
commit e39af974ef
81 changed files with 733 additions and 959 deletions
--- a/docs/changes.txt
+++ b/docs/changes.txt
@@ -103,6 +103,20 @@ All GUI ports:
 - Added m_ prefix to wxColourData and wxFontData members
 - Added wxHtmlPrintout::AddFilter so HTML printing can be subject to
  custom filters as well as HTML viewing.
+- Moved wxApp::SendIdleEvents and wxApp::ProcessIdle into common code.
+- wxWindow::OnInternalIdle is now used in all ports, and ensures that
+  user OnIdle events do not interfere with crucial internal processing.
+- wxWindow::UpdateWindowUI is now a documented function that
+  sends wxUpdateUIEvents, and can be overridden. It has a helper function
+  DoUpdateWindowUI for taking appropriate wxUpdateUIEvent action.
+- Added functions to wxUpdateUIEvent: Set/GetMode, Set/GetUpdateInterval,
+  CanUpdate, to assist with optimising update event frequency.
+- Added functions to wxIdleEvent: Set/GetMode, CanSend, to
+  determine whether a window should receive idle events.
+- Added wxWS_EX_PROCESS_IDLE, wxWS_EX_PROCESS_UI_UPDATES window
+  styles for use with conservative idle and update event modes.
+- wxMSW and wxGTK now send menu update events only when a menu is
+  about to be used.

 Unix:

--- a/docs/latex/wx/idleevt.tex
+++ b/docs/latex/wx/idleevt.tex
@@ -2,6 +2,15 @@

 This class is used for idle events, which are generated when the system is idle.

+By default, idle events are sent to all windows. If this is causing a significant
+overhead in your application, you can call \helpref{wxIdleEvent::SetMode}{wxidleeventsetmode} with
+the value wxIDLE\_PROCESS\_SPECIFIED, and set the wxWS\_EX\_PROCESS\_IDLE extra
+window style for every window which should receive idle events.
+
+The function \helpref{wxWindow::OnInternalIdle}{wxwindowoninternalidle} is
+also provided for internal purposes, and cannot be disabled. wxUpdateUIEvents
+are sent from OnInternalIdle.
+
 \wxheading{Derived from}

 \helpref{wxEvent}{wxevent}\\
@@ -27,7 +36,8 @@ Idle events can be caught by the wxApp class, or by top-level window classes.

 \wxheading{See also}

-\helpref{Event handling overview}{eventhandlingoverview}
+\helpref{Event handling overview}{eventhandlingoverview}, \helpref{wxUpdateUIEvent}{wxupdateuievent}, 
+\helpref{wxWindow::OnInternalIdle}{wxwindowoninternalidle}

 \latexignore{\rtfignore{\wxheading{Members}}}

@@ -37,6 +47,33 @@ Idle events can be caught by the wxApp class, or by top-level window classes.

 Constructor.

+\membersection{wxIdleEvent::CanSend}\label{wxidleeventcansend}
+
+\func{static bool}{CanSend}{\param{wxWindow*}{ window}}
+
+Returns {\tt true} if it is appropriate to send idle events to
+this window.
+
+This function looks at the mode used (see \helpref{wxIdleEvent::SetMode}{wxidleeventsetmode}),
+and the wxWS\_EX\_PROCESS\_IDLE style in {\it window} to determine whether idle events should be sent to
+this window now. By default this will always return {\tt true} because
+the update mode is initially wxIDLE\_PROCESS\_ALL. You can change the mode
+to only send idle events to windows with the wxWS\_EX\_PROCESS\_IDLE extra window style set.
+
+\wxheading{See also}
+
+\helpref{wxIdleEvent::SetMode}{wxidlesetmode}
+
+\membersection{wxIdleEvent::GetMode}\label{wxidleeventgetmode}
+
+\func{static wxIdleMode}{GetMode}{\void}
+
+Static function returning a value specifying how wxWindows
+will send idle events: to all windows, or only to those which specify that they
+will process the events.
+
+See \helpref{wxIdleEvent::SetMode}{wxidleeventsetmode}.
+
 \membersection{wxIdleEvent::RequestMore}\label{wxidleeventrequestmore}

 \func{void}{RequestMore}{\param{bool}{ needMore = true}}
@@ -61,3 +98,26 @@ Returns true if the OnIdle function processing this event requested more process

 \helpref{wxIdleEvent::RequestMore}{wxidleeventrequestmore}

+\membersection{wxIdleEvent::SetMode}\label{wxidleeventsetmode}
+
+\func{static void}{SetMode}{\param{wxIdleMode }{mode}}
+
+Static function for specifying how wxWindows will send idle events: to
+all windows, or only to those which specify that they
+will process the events.
+
+{\it mode} can be one of the following values.
+The default is wxIDLE\_PROCESS\_ALL.
+
+\begin{verbatim}
+enum wxIdleMode
+{
+        // Send idle events to all windows
+    wxIDLE_PROCESS_ALL,
+
+        // Send idle events to windows that have
+        // the wxWS_EX_PROCESS_IDLE flag specified
+    wxIDLE_PROCESS_SPECIFIED
+};
+\end{verbatim}
+
--- a/docs/latex/wx/upduievt.tex
+++ b/docs/latex/wx/upduievt.tex
@@ -46,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}
@@ -95,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}}
@@ -143,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.
+
--- a/docs/latex/wx/window.tex
+++ b/docs/latex/wx/window.tex
@@ -57,6 +57,30 @@ repainted, then children being painted over them. Windows only.}

 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}
@@ -408,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}}
@@ -1684,6 +1733,19 @@ 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)$.
@@ -2751,6 +2813,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}