1\section{\class{wxUpdateUIEvent}}\label{wxupdateuievent} 2 3This class is used for pseudo-events which are called by wxWidgets 4to give an application the chance to update various user interface elements. 5 6\wxheading{Derived from} 7 8\helpref{wxCommandEvent}{wxcommandevent}\\ 9\helpref{wxEvent}{wxevent}\\ 10\helpref{wxObject}{wxobject} 11 12\wxheading{Include files} 13 14<wx/event.h> 15 16\wxheading{Event table macros} 17 18To process an update event, use these event handler macros to direct input to member 19functions that take a wxUpdateUIEvent argument. 20 21\twocolwidtha{7cm} 22\begin{twocollist}\itemsep=0pt 23\twocolitem{{\bf EVT\_UPDATE\_UI(id, func)}}{Process a wxEVT\_UPDATE\_UI event for the command with the given id.} 24\twocolitem{{\bf EVT\_UPDATE\_UI\_RANGE(id1, id2, func)}}{Process a wxEVT\_UPDATE\_UI event for any command with id included in the given range.} 25\end{twocollist} 26 27\wxheading{Remarks} 28 29Without update UI events, an application has to work hard to check/uncheck, enable/disable, 30show/hide, and set the text for elements such as menu items and toolbar buttons. 31The code for doing this has to be mixed up with the code that is invoked when 32an action is invoked for a menu item or button. 33 34With update UI events, you define an event handler to look at the state of 35the application and change UI elements accordingly. wxWidgets will call your 36member functions in idle time, so you don't have to worry where to call this code. 37In addition to being a clearer and more declarative method, it also means you 38don't have to worry whether you're updating a toolbar or menubar identifier. 39The same handler can update a menu item and toolbar button, if the identifier is the same. 40 41Instead of directly manipulating the menu or button, you call functions in the event 42object, such as \helpref{wxUpdateUIEvent::Check}{wxupdateuieventcheck}. wxWidgets 43will determine whether such a call has been made, and which UI element to update. 44 45These events will work for popup menus as well as menubars. Just before a menu is popped 46up, \helpref{wxMenu::UpdateUI}{wxmenuupdateui} is called to process any UI events for 47the window that owns the menu. 48 49If you find that the overhead of UI update processing is affecting 50your application, you can do one or both of the following: 51 52\begin{enumerate} 53\item Call \helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode} with 54a value of wxUPDATE\_UI\_PROCESS\_SPECIFIED, and set the extra style 55wxWS\_EX\_PROCESS\_UPDATE\_EVENTS for every window that should receive update events. 56No other windows will receive update events. 57\item Call \helpref{wxUpdateUIEvent::SetUpdateInterval}{wxupdateuieventsetupdateinterval} with 58a millisecond value to set the delay between updates. You may need 59to call \helpref{wxWindow::UpdateWindowUI}{wxwindowupdatewindowui} at critical 60points, for example when a dialog is about to be shown, in case the user 61sees a slight delay before windows are updated. 62\end{enumerate} 63 64Note that although events are sent in idle time, defining a wxIdleEvent 65handler for a window does not affect this because the events are sent from \helpref{wxWindow::OnInternalIdle}{wxwindowoninternalidle} 66which is {\bf always} called in idle time. 67 68wxWidgets tries to optimize update events on some platforms. On Windows 69and GTK+, events for menubar items are only sent when the menu is about 70to be shown, and not in idle time. 71 72\wxheading{See also} 73 74\helpref{Event handling overview}{eventhandlingoverview} 75 76\latexignore{\rtfignore{\wxheading{Members}}} 77 78\membersection{wxUpdateUIEvent::wxUpdateUIEvent}\label{wxupdateuieventctor} 79 80\func{}{wxUpdateUIEvent}{\param{wxWindowID }{commandId = 0}} 81 82Constructor. 83 84\membersection{wxUpdateUIEvent::CanUpdate}\label{wxupdateuieventcanupdate} 85 86\func{static bool}{CanUpdate}{\param{wxWindow*}{ window}} 87 88Returns {\tt true} if it is appropriate to update (send UI update events to) 89this window. 90 91This function looks at the mode used (see \helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode}), 92the wxWS\_EX\_PROCESS\_UPDATE\_EVENTS flag in {\it window}, 93the time update events were last sent in idle time, and 94the update interval, to determine whether events should be sent to 95this window now. By default this will always return {\tt true} because 96the update mode is initially wxUPDATE\_UI\_PROCESS\_ALL and 97the interval is set to 0; so update events will be sent as 98often as possible. You can reduce the frequency that events 99are sent by changing the mode and/or setting an update interval. 100 101\wxheading{See also} 102 103\helpref{wxUpdateUIEvent::ResetUpdateTime}{wxupdateuieventresetupdatetime}, 104\helpref{wxUpdateUIEvent::SetUpdateInterval}{wxupdateuieventsetupdateinterval}, 105\helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode} 106 107\membersection{wxUpdateUIEvent::Check}\label{wxupdateuieventcheck} 108 109\func{void}{Check}{\param{bool}{ check}} 110 111Check or uncheck the UI element. 112 113\membersection{wxUpdateUIEvent::Enable}\label{wxupdateuieventenable} 114 115\func{void}{Enable}{\param{bool}{ enable}} 116 117Enable or disable the UI element. 118 119\membersection{wxUpdateUIEvent::Show}\label{wxupdateuieventshow} 120 121\func{void}{Show}{\param{bool}{ show}} 122 123Show or hide the UI element. 124 125\membersection{wxUpdateUIEvent::GetChecked}\label{wxupdateuieventgetchecked} 126 127\constfunc{bool}{GetChecked}{\void} 128 129Returns true if the UI element should be checked. 130 131\membersection{wxUpdateUIEvent::GetEnabled}\label{wxupdateuieventgetenabled} 132 133\constfunc{bool}{GetEnabled}{\void} 134 135Returns true if the UI element should be enabled. 136 137\membersection{wxUpdateUIEvent::GetShown}\label{wxupdateuieventgetshown} 138 139\constfunc{bool}{GetShown}{\void} 140 141Returns true if the UI element should be shown. 142 143\membersection{wxUpdateUIEvent::GetSetChecked}\label{wxupdateuieventgetsetchecked} 144 145\constfunc{bool}{GetSetChecked}{\void} 146 147Returns true if the application has called \helpref{wxUpdateUIEvent::Check}{wxupdateuieventcheck}. For wxWidgets internal use only. 148 149\membersection{wxUpdateUIEvent::GetSetEnabled}\label{wxupdateuieventgetsetenabled} 150 151\constfunc{bool}{GetSetEnabled}{\void} 152 153Returns true if the application has called \helpref{wxUpdateUIEvent::Enable}{wxupdateuieventenable}. For wxWidgets internal use only. 154 155\membersection{wxUpdateUIEvent::GetSetShown}\label{wxupdateuieventgetsetshown} 156 157\constfunc{bool}{GetSetShown}{\void} 158 159Returns true if the application has called \helpref{wxUpdateUIEvent::Show}{wxupdateuieventshow}. For wxWidgets internal use only. 160 161\membersection{wxUpdateUIEvent::GetSetText}\label{wxupdateuieventgetsettext} 162 163\constfunc{bool}{GetSetText}{\void} 164 165Returns true if the application has called \helpref{wxUpdateUIEvent::SetText}{wxupdateuieventsettext}. For wxWidgets internal use only. 166 167\membersection{wxUpdateUIEvent::GetText}\label{wxupdateuieventgettext} 168 169\constfunc{wxString}{GetText}{\void} 170 171Returns the text that should be set for the UI element. 172 173\membersection{wxUpdateUIEvent::GetMode}\label{wxupdateuieventgetmode} 174 175\func{static wxUpdateUIMode}{GetMode}{\void} 176 177Static function returning a value specifying how wxWidgets 178will send update events: to all windows, or only to those which specify that they 179will process the events. 180 181See \helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode}. 182 183\membersection{wxUpdateUIEvent::GetUpdateInterval}\label{wxupdateuieventgetupdateinterval} 184 185\func{static long}{GetUpdateInterval}{\void} 186 187Returns the current interval between updates in milliseconds. 188-1 disables updates, 0 updates as frequently as possible. 189 190See \helpref{wxUpdateUIEvent::SetUpdateInterval}{wxupdateuieventsetupdateinterval}. 191 192\membersection{wxUpdateUIEvent::ResetUpdateTime}\label{wxupdateuieventresetupdatetime} 193 194\func{static void}{ResetUpdateTime}{\void} 195 196Used internally to reset the last-updated time to the 197current time. It is assumed that update events are 198normally sent in idle time, so this is called at the end of 199idle processing. 200 201\wxheading{See also} 202 203\helpref{wxUpdateUIEvent::CanUpdate}{wxupdateuieventcanupdate}, 204\helpref{wxUpdateUIEvent::SetUpdateInterval}{wxupdateuieventsetupdateinterval}, 205\helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmode} 206 207\membersection{wxUpdateUIEvent::SetMode}\label{wxupdateuieventsetmode} 208 209\func{static void}{SetMode}{\param{wxUpdateUIMode }{mode}} 210 211Specify how wxWidgets will send update events: to 212all windows, or only to those which specify that they 213will process the events. 214 215{\it mode} may be one of the following values. 216The default is wxUPDATE\_UI\_PROCESS\_ALL. 217 218\begin{verbatim} 219enum wxUpdateUIMode 220{ 221 // Send UI update events to all windows 222 wxUPDATE_UI_PROCESS_ALL, 223 224 // Send UI update events to windows that have 225 // the wxWS_EX_PROCESS_UI_UPDATES flag specified 226 wxUPDATE_UI_PROCESS_SPECIFIED 227}; 228\end{verbatim} 229 230\membersection{wxUpdateUIEvent::SetText}\label{wxupdateuieventsettext} 231 232\func{void}{SetText}{\param{const wxString\&}{ text}} 233 234Sets the text for this UI element. 235 236\membersection{wxUpdateUIEvent::SetUpdateInterval}\label{wxupdateuieventsetupdateinterval} 237 238\func{static void}{SetUpdateInterval}{\param{long }{updateInterval}} 239 240Sets the interval between updates in milliseconds. 241Set to -1 to disable updates, or to 0 to update as frequently as possible. 242The default is 0. 243 244Use this to reduce the overhead of UI update events if your application 245has a lot of windows. If you set the value to -1 or greater than 0, 246you may also need to call \helpref{wxWindow::UpdateWindowUI}{wxwindowupdatewindowui} 247at appropriate points in your application, such as when a dialog 248is about to be shown. 249 250