docs/latex/wx/upduievt.tex

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