Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: event.h | |
6496345c | 3 | // Purpose: interface of wxEvtHandler, wxEventBlocker and many |
42013f4c | 4 | // wxEvent-derived classes |
23324ae1 FM |
5 | // Author: wxWidgets team |
6 | // RCS-ID: $Id$ | |
526954c5 | 7 | // Licence: wxWindows licence |
23324ae1 FM |
8 | ///////////////////////////////////////////////////////////////////////////// |
9 | ||
d48b06bd FM |
10 | /** |
11 | The predefined constants for the number of times we propagate event | |
12 | upwards window child-parent chain. | |
13 | */ | |
14 | enum wxEventPropagation | |
15 | { | |
16 | /// don't propagate it at all | |
17 | wxEVENT_PROPAGATE_NONE = 0, | |
18 | ||
19 | /// propagate it until it is processed | |
20 | wxEVENT_PROPAGATE_MAX = INT_MAX | |
21 | }; | |
22 | ||
23 | /** | |
24 | The different categories for a wxEvent; see wxEvent::GetEventCategory. | |
25 | ||
dde19c21 | 26 | @note They are used as OR-combinable flags by wxEventLoopBase::YieldFor. |
d48b06bd FM |
27 | */ |
28 | enum wxEventCategory | |
29 | { | |
30 | /** | |
31 | This is the category for those events which are generated to update | |
32 | the appearance of the GUI but which (usually) do not comport data | |
33 | processing, i.e. which do not provide input or output data | |
34 | (e.g. size events, scroll events, etc). | |
35 | They are events NOT directly generated by the user's input devices. | |
36 | */ | |
37 | wxEVT_CATEGORY_UI = 1, | |
38 | ||
39 | /** | |
40 | This category groups those events which are generated directly from the | |
41 | user through input devices like mouse and keyboard and usually result in | |
42 | data to be processed from the application | |
43 | (e.g. mouse clicks, key presses, etc). | |
44 | */ | |
45 | wxEVT_CATEGORY_USER_INPUT = 2, | |
46 | ||
47 | /// This category is for wxSocketEvent | |
48 | wxEVT_CATEGORY_SOCKET = 4, | |
49 | ||
50 | /// This category is for wxTimerEvent | |
51 | wxEVT_CATEGORY_TIMER = 8, | |
52 | ||
53 | /** | |
54 | This category is for any event used to send notifications from the | |
55 | secondary threads to the main one or in general for notifications among | |
56 | different threads (which may or may not be user-generated). | |
22d17afa | 57 | See e.g. wxThreadEvent. |
d48b06bd FM |
58 | */ |
59 | wxEVT_CATEGORY_THREAD = 16, | |
60 | ||
61 | /** | |
dde19c21 FM |
62 | This mask is used in wxEventLoopBase::YieldFor to specify that all event |
63 | categories should be processed. | |
d48b06bd FM |
64 | */ |
65 | wxEVT_CATEGORY_ALL = | |
66 | wxEVT_CATEGORY_UI|wxEVT_CATEGORY_USER_INPUT|wxEVT_CATEGORY_SOCKET| \ | |
67 | wxEVT_CATEGORY_TIMER|wxEVT_CATEGORY_THREAD | |
68 | }; | |
7c913512 | 69 | |
42013f4c FM |
70 | /** |
71 | @class wxEvent | |
7c913512 | 72 | |
42013f4c FM |
73 | An event is a structure holding information about an event passed to a |
74 | callback or member function. | |
1f1d2182 | 75 | |
42013f4c FM |
76 | wxEvent used to be a multipurpose event object, and is an abstract base class |
77 | for other event classes (see below). | |
1f1d2182 | 78 | |
3e083d65 | 79 | For more information about events, see the @ref overview_events overview. |
1f1d2182 | 80 | |
42013f4c FM |
81 | @beginWxPerlOnly |
82 | In wxPerl custom event classes should be derived from | |
83 | @c Wx::PlEvent and @c Wx::PlCommandEvent. | |
84 | @endWxPerlOnly | |
1f1d2182 | 85 | |
42013f4c | 86 | @library{wxbase} |
23324ae1 | 87 | @category{events} |
42013f4c FM |
88 | |
89 | @see wxCommandEvent, wxMouseEvent | |
23324ae1 | 90 | */ |
42013f4c | 91 | class wxEvent : public wxObject |
23324ae1 FM |
92 | { |
93 | public: | |
94 | /** | |
707aaf17 VZ |
95 | Constructor. |
96 | ||
97 | Notice that events are usually created by wxWidgets itself and creating | |
98 | e.g. a wxPaintEvent in your code and sending it to e.g. a wxTextCtrl | |
99 | will not usually affect it at all as native controls have no specific | |
100 | knowledge about wxWidgets events. However you may construct objects of | |
101 | specific types and pass them to wxEvtHandler::ProcessEvent() if you | |
102 | want to create your own custom control and want to process its events | |
103 | in the same manner as the standard ones. | |
104 | ||
105 | Also please notice that the order of parameters in this constructor is | |
106 | different from almost all the derived classes which specify the event | |
107 | type as the first argument. | |
108 | ||
109 | @param id | |
110 | The identifier of the object (window, timer, ...) which generated | |
111 | this event. | |
112 | @param eventType | |
3a194bda SL |
113 | The unique type of event, e.g. @c wxEVT_PAINT, @c wxEVT_SIZE or |
114 | @c wxEVT_COMMAND_BUTTON_CLICKED. | |
23324ae1 | 115 | */ |
42013f4c | 116 | wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL); |
23324ae1 FM |
117 | |
118 | /** | |
42013f4c | 119 | Returns a copy of the event. |
1f1d2182 | 120 | |
c3f94162 | 121 | Any event that is posted to the wxWidgets event system for later action |
cf2918d4 FM |
122 | (via wxEvtHandler::AddPendingEvent, wxEvtHandler::QueueEvent or wxPostEvent()) |
123 | must implement this method. | |
42013f4c FM |
124 | |
125 | All wxWidgets events fully implement this method, but any derived events | |
126 | implemented by the user should also implement this method just in case they | |
127 | (or some event derived from them) are ever posted. | |
128 | ||
129 | All wxWidgets events implement a copy constructor, so the easiest way of | |
130 | implementing the Clone function is to implement a copy constructor for | |
131 | a new event (call it MyEvent) and then define the Clone function like this: | |
132 | ||
133 | @code | |
134 | wxEvent *Clone() const { return new MyEvent(*this); } | |
135 | @endcode | |
23324ae1 | 136 | */ |
42013f4c | 137 | virtual wxEvent* Clone() const = 0; |
23324ae1 FM |
138 | |
139 | /** | |
42013f4c | 140 | Returns the object (usually a window) associated with the event, if any. |
23324ae1 | 141 | */ |
42013f4c | 142 | wxObject* GetEventObject() const; |
23324ae1 FM |
143 | |
144 | /** | |
42013f4c | 145 | Returns the identifier of the given event type, such as @c wxEVT_COMMAND_BUTTON_CLICKED. |
23324ae1 | 146 | */ |
42013f4c | 147 | wxEventType GetEventType() const; |
23324ae1 | 148 | |
d48b06bd FM |
149 | /** |
150 | Returns a generic category for this event. | |
3a567740 | 151 | wxEvent implementation returns @c wxEVT_CATEGORY_UI by default. |
d48b06bd | 152 | |
dde19c21 | 153 | This function is used to selectively process events in wxEventLoopBase::YieldFor. |
d48b06bd FM |
154 | */ |
155 | virtual wxEventCategory GetEventCategory() const; | |
156 | ||
23324ae1 | 157 | /** |
42013f4c | 158 | Returns the identifier associated with this event, such as a button command id. |
23324ae1 | 159 | */ |
42013f4c | 160 | int GetId() const; |
23324ae1 FM |
161 | |
162 | /** | |
42013f4c | 163 | Returns @true if the event handler should be skipped, @false otherwise. |
23324ae1 | 164 | */ |
42013f4c | 165 | bool GetSkipped() const; |
23324ae1 | 166 | |
23324ae1 | 167 | /** |
42013f4c FM |
168 | Gets the timestamp for the event. The timestamp is the time in milliseconds |
169 | since some fixed moment (not necessarily the standard Unix Epoch, so only | |
170 | differences between the timestamps and not their absolute values usually make sense). | |
3c52ef94 FM |
171 | |
172 | @warning | |
173 | wxWidgets returns a non-NULL timestamp only for mouse and key events | |
174 | (see wxMouseEvent and wxKeyEvent). | |
23324ae1 | 175 | */ |
42013f4c | 176 | long GetTimestamp() const; |
23324ae1 FM |
177 | |
178 | /** | |
42013f4c | 179 | Returns @true if the event is or is derived from wxCommandEvent else it returns @false. |
1f1d2182 | 180 | |
42013f4c | 181 | @note exists only for optimization purposes. |
23324ae1 | 182 | */ |
42013f4c | 183 | bool IsCommandEvent() const; |
23324ae1 FM |
184 | |
185 | /** | |
42013f4c FM |
186 | Sets the propagation level to the given value (for example returned from an |
187 | earlier call to wxEvent::StopPropagation). | |
188 | */ | |
189 | void ResumePropagation(int propagationLevel); | |
1f1d2182 | 190 | |
42013f4c FM |
191 | /** |
192 | Sets the originating object. | |
23324ae1 | 193 | */ |
42013f4c | 194 | void SetEventObject(wxObject* object); |
23324ae1 FM |
195 | |
196 | /** | |
42013f4c FM |
197 | Sets the event type. |
198 | */ | |
199 | void SetEventType(wxEventType type); | |
1f1d2182 | 200 | |
42013f4c FM |
201 | /** |
202 | Sets the identifier associated with this event, such as a button command id. | |
23324ae1 | 203 | */ |
42013f4c | 204 | void SetId(int id); |
23324ae1 FM |
205 | |
206 | /** | |
42013f4c | 207 | Sets the timestamp for the event. |
23324ae1 | 208 | */ |
3c52ef94 | 209 | void SetTimestamp(long timeStamp = 0); |
23324ae1 FM |
210 | |
211 | /** | |
42013f4c FM |
212 | Test if this event should be propagated or not, i.e. if the propagation level |
213 | is currently greater than 0. | |
23324ae1 | 214 | */ |
42013f4c | 215 | bool ShouldPropagate() const; |
23324ae1 FM |
216 | |
217 | /** | |
42013f4c FM |
218 | This method can be used inside an event handler to control whether further |
219 | event handlers bound to this event will be called after the current one returns. | |
1f1d2182 | 220 | |
42013f4c FM |
221 | Without Skip() (or equivalently if Skip(@false) is used), the event will not |
222 | be processed any more. If Skip(@true) is called, the event processing system | |
223 | continues searching for a further handler function for this event, even though | |
224 | it has been processed already in the current handler. | |
225 | ||
226 | In general, it is recommended to skip all non-command events to allow the | |
227 | default handling to take place. The command events are, however, normally not | |
228 | skipped as usually a single command such as a button click or menu item | |
229 | selection must only be processed by one handler. | |
23324ae1 | 230 | */ |
42013f4c | 231 | void Skip(bool skip = true); |
23324ae1 FM |
232 | |
233 | /** | |
42013f4c | 234 | Stop the event from propagating to its parent window. |
1f1d2182 | 235 | |
42013f4c FM |
236 | Returns the old propagation level value which may be later passed to |
237 | ResumePropagation() to allow propagating the event again. | |
23324ae1 | 238 | */ |
42013f4c | 239 | int StopPropagation(); |
23324ae1 | 240 | |
42013f4c | 241 | protected: |
23324ae1 | 242 | /** |
42013f4c | 243 | Indicates how many levels the event can propagate. |
23324ae1 | 244 | |
42013f4c FM |
245 | This member is protected and should typically only be set in the constructors |
246 | of the derived classes. It may be temporarily changed by StopPropagation() | |
247 | and ResumePropagation() and tested with ShouldPropagate(). | |
23324ae1 | 248 | |
42013f4c FM |
249 | The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by default) |
250 | meaning that the event shouldn't be propagated at all or to | |
251 | @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be | |
252 | propagated as much as necessary. | |
23324ae1 | 253 | |
42013f4c FM |
254 | Any positive number means that the event should be propagated but no more than |
255 | the given number of times. E.g. the propagation level may be set to 1 to | |
256 | propagate the event to its parent only, but not to its grandparent. | |
257 | */ | |
258 | int m_propagationLevel; | |
259 | }; | |
e54c96f1 | 260 | |
23324ae1 | 261 | /** |
42013f4c | 262 | @class wxEventBlocker |
7c913512 | 263 | |
42013f4c FM |
264 | This class is a special event handler which allows to discard |
265 | any event (or a set of event types) directed to a specific window. | |
7c913512 | 266 | |
42013f4c FM |
267 | Example: |
268 | ||
269 | @code | |
270 | void MyWindow::DoSomething() | |
271 | { | |
272 | { | |
273 | // block all events directed to this window while | |
274 | // we do the 1000 FunctionWhichSendsEvents() calls | |
275 | wxEventBlocker blocker(this); | |
276 | ||
277 | for ( int i = 0; i 1000; i++ ) | |
278 | FunctionWhichSendsEvents(i); | |
279 | ||
280 | } // ~wxEventBlocker called, old event handler is restored | |
281 | ||
282 | // the event generated by this call will be processed: | |
283 | FunctionWhichSendsEvents(0) | |
284 | } | |
285 | @endcode | |
1f1d2182 | 286 | |
23324ae1 FM |
287 | @library{wxcore} |
288 | @category{events} | |
7c913512 | 289 | |
3e083d65 | 290 | @see @ref overview_events_processing, wxEvtHandler |
23324ae1 | 291 | */ |
42013f4c | 292 | class wxEventBlocker : public wxEvtHandler |
23324ae1 FM |
293 | { |
294 | public: | |
295 | /** | |
42013f4c | 296 | Constructs the blocker for the given window and for the given event type. |
23324ae1 | 297 | |
42013f4c FM |
298 | If @a type is @c wxEVT_ANY, then all events for that window are blocked. |
299 | You can call Block() after creation to add other event types to the list | |
300 | of events to block. | |
3c4f71cc | 301 | |
42013f4c FM |
302 | Note that the @a win window @b must remain alive until the |
303 | wxEventBlocker object destruction. | |
23324ae1 | 304 | */ |
5e6e278d | 305 | wxEventBlocker(wxWindow* win, wxEventType type = -1); |
23324ae1 FM |
306 | |
307 | /** | |
42013f4c FM |
308 | Destructor. The blocker will remove itself from the chain of event handlers for |
309 | the window provided in the constructor, thus restoring normal processing of events. | |
23324ae1 | 310 | */ |
42013f4c | 311 | virtual ~wxEventBlocker(); |
23324ae1 FM |
312 | |
313 | /** | |
42013f4c | 314 | Adds to the list of event types which should be blocked the given @a eventType. |
23324ae1 | 315 | */ |
42013f4c FM |
316 | void Block(wxEventType eventType); |
317 | }; | |
23324ae1 | 318 | |
1f1d2182 | 319 | |
42013f4c | 320 | |
d775ec48 RD |
321 | /** |
322 | Helper class to temporarily change an event to not propagate. | |
323 | */ | |
324 | class wxPropagationDisabler | |
325 | { | |
326 | public: | |
327 | wxPropagationDisabler(wxEvent& event); | |
328 | ~wxPropagationDisabler(); | |
329 | }; | |
330 | ||
331 | ||
332 | /** | |
333 | Helper class to temporarily lower propagation level. | |
334 | */ | |
335 | class wxPropagateOnce | |
336 | { | |
337 | public: | |
338 | wxPropagateOnce(wxEvent& event); | |
339 | ~wxPropagateOnce(); | |
340 | }; | |
341 | ||
342 | ||
343 | ||
42013f4c FM |
344 | /** |
345 | @class wxEvtHandler | |
42013f4c FM |
346 | |
347 | A class that can handle events from the windowing system. | |
6496345c | 348 | wxWindow is (and therefore all window classes are) derived from this class. |
42013f4c FM |
349 | |
350 | When events are received, wxEvtHandler invokes the method listed in the | |
7f853dd0 | 351 | event table using itself as the object. When using multiple inheritance |
6496345c FM |
352 | <b>it is imperative that the wxEvtHandler(-derived) class is the first |
353 | class inherited</b> such that the @c this pointer for the overall object | |
354 | will be identical to the @c this pointer of the wxEvtHandler portion. | |
42013f4c FM |
355 | |
356 | @library{wxbase} | |
357 | @category{events} | |
358 | ||
8e40ed85 | 359 | @see @ref overview_events_processing, wxEventBlocker, wxEventLoopBase |
42013f4c | 360 | */ |
9de71074 | 361 | class wxEvtHandler : public wxObject, public wxTrackable |
42013f4c FM |
362 | { |
363 | public: | |
364 | /** | |
365 | Constructor. | |
23324ae1 | 366 | */ |
42013f4c | 367 | wxEvtHandler(); |
23324ae1 FM |
368 | |
369 | /** | |
42013f4c | 370 | Destructor. |
1f1d2182 | 371 | |
7f853dd0 FM |
372 | If the handler is part of a chain, the destructor will unlink itself |
373 | (see Unlink()). | |
23324ae1 | 374 | */ |
42013f4c | 375 | virtual ~wxEvtHandler(); |
23324ae1 | 376 | |
db82d78b FM |
377 | |
378 | /** | |
379 | @name Event queuing and processing | |
380 | */ | |
381 | //@{ | |
382 | ||
23324ae1 | 383 | /** |
c3f94162 VZ |
384 | Queue event for a later processing. |
385 | ||
386 | This method is similar to ProcessEvent() but while the latter is | |
387 | synchronous, i.e. the event is processed immediately, before the | |
388 | function returns, this one is asynchronous and returns immediately | |
389 | while the event will be processed at some later time (usually during | |
390 | the next event loop iteration). | |
391 | ||
392 | Another important difference is that this method takes ownership of the | |
393 | @a event parameter, i.e. it will delete it itself. This implies that | |
394 | the event should be allocated on the heap and that the pointer can't be | |
395 | used any more after the function returns (as it can be deleted at any | |
396 | moment). | |
397 | ||
398 | QueueEvent() can be used for inter-thread communication from the worker | |
399 | threads to the main thread, it is safe in the sense that it uses | |
400 | locking internally and avoids the problem mentioned in AddPendingEvent() | |
401 | documentation by ensuring that the @a event object is not used by the | |
402 | calling thread any more. Care should still be taken to avoid that some | |
403 | fields of this object are used by it, notably any wxString members of | |
404 | the event object must not be shallow copies of another wxString object | |
405 | as this would result in them still using the same string buffer behind | |
22d17afa | 406 | the scenes. For example: |
c3f94162 VZ |
407 | @code |
408 | void FunctionInAWorkerThread(const wxString& str) | |
409 | { | |
36a2d2c4 | 410 | wxCommandEvent* evt = new wxCommandEvent; |
42013f4c | 411 | |
36a2d2c4 RR |
412 | // NOT evt->SetString(str) as this would be a shallow copy |
413 | evt->SetString(str.c_str()); // make a deep copy | |
42013f4c | 414 | |
36a2d2c4 | 415 | wxTheApp->QueueEvent( evt ); |
c3f94162 VZ |
416 | } |
417 | @endcode | |
42013f4c | 418 | |
22d17afa FM |
419 | Note that you can use wxThreadEvent instead of wxCommandEvent |
420 | to avoid this problem: | |
421 | @code | |
422 | void FunctionInAWorkerThread(const wxString& str) | |
423 | { | |
424 | wxThreadEvent evt; | |
425 | evt->SetString(str); | |
426 | ||
427 | // wxThreadEvent::Clone() makes sure that the internal wxString | |
428 | // member is not shared by other wxString instances: | |
429 | wxTheApp->QueueEvent( evt.Clone() ); | |
430 | } | |
431 | @endcode | |
432 | ||
c3f94162 VZ |
433 | Finally notice that this method automatically wakes up the event loop |
434 | if it is currently idle by calling ::wxWakeUpIdle() so there is no need | |
435 | to do it manually when using it. | |
42013f4c | 436 | |
c3f94162 | 437 | @since 2.9.0 |
42013f4c FM |
438 | |
439 | @param event | |
c3f94162 VZ |
440 | A heap-allocated event to be queued, QueueEvent() takes ownership |
441 | of it. This parameter shouldn't be @c NULL. | |
442 | */ | |
443 | virtual void QueueEvent(wxEvent *event); | |
444 | ||
445 | /** | |
446 | Post an event to be processed later. | |
447 | ||
448 | This function is similar to QueueEvent() but can't be used to post | |
449 | events from worker threads for the event objects with wxString fields | |
450 | (i.e. in practice most of them) because of an unsafe use of the same | |
451 | wxString object which happens because the wxString field in the | |
452 | original @a event object and its copy made internally by this function | |
453 | share the same string buffer internally. Use QueueEvent() to avoid | |
f1d5aa12 | 454 | this. |
c3f94162 | 455 | |
bb69632a | 456 | A copy of @a event is made by the function, so the original can be deleted |
c3f94162 VZ |
457 | as soon as function returns (it is common that the original is created |
458 | on the stack). This requires that the wxEvent::Clone() method be | |
459 | implemented by event so that it can be duplicated and stored until it | |
460 | gets processed. | |
461 | ||
462 | @param event | |
463 | Event to add to the pending events queue. | |
23324ae1 | 464 | */ |
42013f4c | 465 | virtual void AddPendingEvent(const wxEvent& event); |
23324ae1 | 466 | |
db82d78b FM |
467 | /** |
468 | Processes an event, searching event tables and calling zero or more suitable | |
469 | event handler function(s). | |
470 | ||
471 | Normally, your application would not call this function: it is called in the | |
472 | wxWidgets implementation to dispatch incoming user interface events to the | |
473 | framework (and application). | |
474 | ||
475 | However, you might need to call it if implementing new functionality | |
476 | (such as a new control) where you define new event types, as opposed to | |
477 | allowing the user to override virtual functions. | |
478 | ||
8cc208e3 VZ |
479 | Notice that you don't usually need to override ProcessEvent() to |
480 | customize the event handling, overriding the specially provided | |
481 | TryBefore() and TryAfter() functions is usually enough. For example, | |
482 | wxMDIParentFrame may override TryBefore() to ensure that the menu | |
483 | events are processed in the active child frame before being processed | |
484 | in the parent frame itself. | |
db82d78b FM |
485 | |
486 | The normal order of event table searching is as follows: | |
8cc208e3 VZ |
487 | -# wxApp::FilterEvent() is called. If it returns anything but @c -1 |
488 | (default) the processing stops here. | |
8cc208e3 VZ |
489 | -# TryBefore() is called (this is where wxValidator are taken into |
490 | account for wxWindow objects). If this returns @true, the function exits. | |
255ea4a7 VZ |
491 | -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled) |
492 | the function skips to step (7). | |
fde702ea | 493 | -# Dynamic event table of the handlers bound using Bind<>() is |
8cc208e3 VZ |
494 | searched. If a handler is found, it is executed and the function |
495 | returns @true unless the handler used wxEvent::Skip() to indicate | |
496 | that it didn't handle the event in which case the search continues. | |
fde702ea | 497 | -# Static events table of the handlers bound using event table |
8cc208e3 | 498 | macros is searched for this event handler. If this fails, the base |
57ab6f23 | 499 | class event table is tried, and so on until no more tables |
8cc208e3 VZ |
500 | exist or an appropriate function was found. If a handler is found, |
501 | the same logic as in the previous step applies. | |
db82d78b | 502 | -# The search is applied down the entire chain of event handlers (usually the |
7f853dd0 | 503 | chain has a length of one). This chain can be formed using wxEvtHandler::SetNextHandler(): |
830b7aa7 | 504 | @image html overview_events_chain.png |
7f853dd0 FM |
505 | (referring to the image, if @c A->ProcessEvent is called and it doesn't handle |
506 | the event, @c B->ProcessEvent will be called and so on...). | |
507 | Note that in the case of wxWindow you can build a stack of event handlers | |
508 | (see wxWindow::PushEventHandler() for more info). | |
509 | If any of the handlers of the chain return @true, the function exits. | |
8cc208e3 VZ |
510 | -# TryAfter() is called: for the wxWindow object this may propagate the |
511 | event to the window parent (recursively). If the event is still not | |
512 | processed, ProcessEvent() on wxTheApp object is called as the last | |
513 | step. | |
514 | ||
3cbb9df8 VZ |
515 | Notice that steps (2)-(6) are performed in ProcessEventLocally() |
516 | which is called by this function. | |
db82d78b FM |
517 | |
518 | @param event | |
519 | Event to process. | |
8cc208e3 VZ |
520 | @return |
521 | @true if a suitable event handler function was found and executed, | |
522 | and the function did not call wxEvent::Skip. | |
db82d78b FM |
523 | |
524 | @see SearchEventTable() | |
525 | */ | |
526 | virtual bool ProcessEvent(wxEvent& event); | |
527 | ||
3cbb9df8 VZ |
528 | /** |
529 | Try to process the event in this handler and all those chained to it. | |
530 | ||
531 | As explained in ProcessEvent() documentation, the event handlers may be | |
532 | chained in a doubly-linked list. This function tries to process the | |
533 | event in this handler (including performing any pre-processing done in | |
534 | TryBefore(), e.g. applying validators) and all those following it in | |
535 | the chain until the event is processed or the chain is exhausted. | |
536 | ||
537 | This function is called from ProcessEvent() and, in turn, calls | |
a0bf1b58 | 538 | TryBefore() and TryAfter(). It is not virtual and so cannot be |
512220b6 VZ |
539 | overridden but can, and should, be called to forward an event to |
540 | another handler instead of ProcessEvent() which would result in a | |
3cbb9df8 VZ |
541 | duplicate call to TryAfter(), e.g. resulting in all unprocessed events |
542 | being sent to the application object multiple times. | |
543 | ||
544 | @since 2.9.1 | |
545 | ||
546 | @param event | |
547 | Event to process. | |
548 | @return | |
549 | @true if this handler of one of those chained to it processed the | |
550 | event. | |
551 | */ | |
552 | bool ProcessEventLocally(wxEvent& event); | |
553 | ||
db82d78b FM |
554 | /** |
555 | Processes an event by calling ProcessEvent() and handles any exceptions | |
556 | that occur in the process. | |
557 | If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called. | |
558 | ||
559 | @param event | |
560 | Event to process. | |
561 | ||
562 | @return @true if the event was processed, @false if no handler was found | |
563 | or an exception was thrown. | |
564 | ||
565 | @see wxWindow::HandleWindowEvent | |
566 | */ | |
567 | bool SafelyProcessEvent(wxEvent& event); | |
04a7eed1 | 568 | |
cae9e7b1 | 569 | /** |
04a7eed1 | 570 | Processes the pending events previously queued using QueueEvent() or |
cae9e7b1 FM |
571 | AddPendingEvent(); you must call this function only if you are sure |
572 | there are pending events for this handler, otherwise a @c wxCHECK | |
573 | will fail. | |
04a7eed1 | 574 | |
cae9e7b1 FM |
575 | The real processing still happens in ProcessEvent() which is called by this |
576 | function. | |
04a7eed1 VZ |
577 | |
578 | Note that this function needs a valid application object (see | |
cae9e7b1 FM |
579 | wxAppConsole::GetInstance()) because wxApp holds the list of the event |
580 | handlers with pending events and this function manipulates that list. | |
581 | */ | |
582 | void ProcessPendingEvents(); | |
db82d78b | 583 | |
cae9e7b1 FM |
584 | /** |
585 | Deletes all events queued on this event handler using QueueEvent() or | |
586 | AddPendingEvent(). | |
04a7eed1 | 587 | |
cae9e7b1 FM |
588 | Use with care because the events which are deleted are (obviously) not |
589 | processed and this may have unwanted consequences (e.g. user actions events | |
590 | will be lost). | |
591 | */ | |
592 | void DeletePendingEvents(); | |
04a7eed1 | 593 | |
db82d78b FM |
594 | /** |
595 | Searches the event table, executing an event handler function if an appropriate | |
596 | one is found. | |
597 | ||
598 | @param table | |
599 | Event table to be searched. | |
600 | @param event | |
601 | Event to be matched against an event table entry. | |
602 | ||
603 | @return @true if a suitable event handler function was found and | |
604 | executed, and the function did not call wxEvent::Skip. | |
605 | ||
606 | @remarks This function looks through the object's event table and tries | |
607 | to find an entry that will match the event. | |
608 | An entry will match if: | |
609 | @li The event type matches, and | |
610 | @li the identifier or identifier range matches, or the event table | |
611 | entry's identifier is zero. | |
612 | ||
613 | If a suitable function is called but calls wxEvent::Skip, this | |
614 | function will fail, and searching will continue. | |
04a7eed1 | 615 | |
cae9e7b1 FM |
616 | @todo this function in the header is listed as an "implementation only" function; |
617 | are we sure we want to document it? | |
db82d78b FM |
618 | |
619 | @see ProcessEvent() | |
620 | */ | |
621 | virtual bool SearchEventTable(wxEventTable& table, | |
622 | wxEvent& event); | |
623 | ||
624 | //@} | |
625 | ||
626 | ||
627 | /** | |
628 | @name Connecting and disconnecting | |
629 | */ | |
630 | //@{ | |
631 | ||
23324ae1 | 632 | /** |
6c5e1aa7 VZ |
633 | Connects the given function dynamically with the event handler, id and |
634 | event type. | |
42013f4c | 635 | |
04a7eed1 VZ |
636 | Notice that Bind() provides a more flexible and safer way to do the |
637 | same thing as Connect(), please use it in any new code -- while | |
638 | Connect() is not formally deprecated due to its existing widespread | |
639 | usage, it has no advantages compared to Bind(). | |
640 | ||
6c5e1aa7 VZ |
641 | This is an alternative to the use of static event tables. It is more |
642 | flexible as it allows to connect events generated by some object to an | |
643 | event handler defined in a different object of a different class (which | |
644 | is impossible to do directly with the event tables -- the events can be | |
645 | only handled in another object if they are propagated upwards to it). | |
646 | Do make sure to specify the correct @a eventSink when connecting to an | |
647 | event of a different object. | |
648 | ||
04a7eed1 | 649 | See @ref overview_events_bind for more detailed explanation |
6c5e1aa7 VZ |
650 | of this function and the @ref page_samples_event sample for usage |
651 | examples. | |
42013f4c FM |
652 | |
653 | This specific overload allows you to connect an event handler to a @e range | |
654 | of @e source IDs. | |
655 | Do not confuse @e source IDs with event @e types: source IDs identify the | |
656 | event generator objects (typically wxMenuItem or wxWindow objects) while the | |
657 | event @e type identify which type of events should be handled by the | |
658 | given @e function (an event generator object may generate many different | |
659 | types of events!). | |
660 | ||
661 | @param id | |
662 | The first ID of the identifier range to be associated with the event | |
663 | handler function. | |
664 | @param lastId | |
665 | The last ID of the identifier range to be associated with the event | |
666 | handler function. | |
667 | @param eventType | |
668 | The event type to be associated with this event handler. | |
669 | @param function | |
670 | The event handler function. Note that this function should | |
671 | be explicitly converted to the correct type which can be done using a macro | |
672 | called @c wxFooEventHandler for the handler for any @c wxFooEvent. | |
673 | @param userData | |
674 | Data to be associated with the event table entry. | |
675 | @param eventSink | |
6c5e1aa7 VZ |
676 | Object whose member function should be called. It must be specified |
677 | when connecting an event generated by one object to a member | |
678 | function of a different object. If it is omitted, @c this is used. | |
04a7eed1 | 679 | |
1058f652 MB |
680 | @beginWxPerlOnly |
681 | In wxPerl this function takes 4 arguments: @a id, @a lastid, | |
682 | @a type, @a method; if @a method is undef, the handler is | |
683 | disconnected.} | |
684 | @endWxPerlOnly | |
685 | ||
04a7eed1 | 686 | @see Bind<>() |
23324ae1 | 687 | */ |
42013f4c FM |
688 | void Connect(int id, int lastId, wxEventType eventType, |
689 | wxObjectEventFunction function, | |
690 | wxObject* userData = NULL, | |
691 | wxEvtHandler* eventSink = NULL); | |
23324ae1 FM |
692 | |
693 | /** | |
42013f4c FM |
694 | See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) |
695 | overload for more info. | |
696 | ||
697 | This overload can be used to attach an event handler to a single source ID: | |
698 | ||
699 | Example: | |
700 | @code | |
701 | frame->Connect( wxID_EXIT, | |
702 | wxEVT_COMMAND_MENU_SELECTED, | |
703 | wxCommandEventHandler(MyFrame::OnQuit) ); | |
704 | @endcode | |
1058f652 MB |
705 | |
706 | @beginWxPerlOnly | |
707 | Not supported by wxPerl. | |
708 | @endWxPerlOnly | |
23324ae1 | 709 | */ |
42013f4c FM |
710 | void Connect(int id, wxEventType eventType, |
711 | wxObjectEventFunction function, | |
712 | wxObject* userData = NULL, | |
713 | wxEvtHandler* eventSink = NULL); | |
23324ae1 FM |
714 | |
715 | /** | |
42013f4c FM |
716 | See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) |
717 | overload for more info. | |
718 | ||
719 | This overload will connect the given event handler so that regardless of the | |
720 | ID of the event source, the handler will be called. | |
1058f652 MB |
721 | |
722 | @beginWxPerlOnly | |
723 | Not supported by wxPerl. | |
724 | @endWxPerlOnly | |
23324ae1 | 725 | */ |
42013f4c FM |
726 | void Connect(wxEventType eventType, |
727 | wxObjectEventFunction function, | |
728 | wxObject* userData = NULL, | |
729 | wxEvtHandler* eventSink = NULL); | |
23324ae1 FM |
730 | |
731 | /** | |
42013f4c FM |
732 | Disconnects the given function dynamically from the event handler, using the |
733 | specified parameters as search criteria and returning @true if a matching | |
734 | function has been found and removed. | |
735 | ||
736 | This method can only disconnect functions which have been added using the | |
737 | Connect() method. There is no way to disconnect functions connected using | |
738 | the (static) event tables. | |
739 | ||
740 | @param eventType | |
741 | The event type associated with this event handler. | |
742 | @param function | |
743 | The event handler function. | |
744 | @param userData | |
745 | Data associated with the event table entry. | |
746 | @param eventSink | |
747 | Object whose member function should be called. | |
1058f652 MB |
748 | |
749 | @beginWxPerlOnly | |
750 | Not supported by wxPerl. | |
751 | @endWxPerlOnly | |
23324ae1 | 752 | */ |
a44f3b5a FM |
753 | bool Disconnect(wxEventType eventType, |
754 | wxObjectEventFunction function, | |
42013f4c FM |
755 | wxObject* userData = NULL, |
756 | wxEvtHandler* eventSink = NULL); | |
23324ae1 FM |
757 | |
758 | /** | |
42013f4c FM |
759 | See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) |
760 | overload for more info. | |
23324ae1 | 761 | |
42013f4c | 762 | This overload takes the additional @a id parameter. |
1058f652 MB |
763 | |
764 | @beginWxPerlOnly | |
765 | Not supported by wxPerl. | |
766 | @endWxPerlOnly | |
42013f4c FM |
767 | */ |
768 | bool Disconnect(int id = wxID_ANY, | |
769 | wxEventType eventType = wxEVT_NULL, | |
770 | wxObjectEventFunction function = NULL, | |
771 | wxObject* userData = NULL, | |
772 | wxEvtHandler* eventSink = NULL); | |
23324ae1 | 773 | |
42013f4c FM |
774 | /** |
775 | See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) | |
776 | overload for more info. | |
e54c96f1 | 777 | |
42013f4c | 778 | This overload takes an additional range of source IDs. |
1058f652 MB |
779 | |
780 | @beginWxPerlOnly | |
781 | In wxPerl this function takes 3 arguments: @a id, | |
782 | @a lastid, @a type. | |
783 | @endWxPerlOnly | |
42013f4c | 784 | */ |
a44f3b5a FM |
785 | bool Disconnect(int id, int lastId, |
786 | wxEventType eventType, | |
42013f4c FM |
787 | wxObjectEventFunction function = NULL, |
788 | wxObject* userData = NULL, | |
789 | wxEvtHandler* eventSink = NULL); | |
db82d78b FM |
790 | //@} |
791 | ||
792 | ||
04a7eed1 VZ |
793 | /** |
794 | @name Binding and Unbinding | |
795 | */ | |
796 | //@{ | |
797 | ||
798 | /** | |
799 | Binds the given function, functor or method dynamically with the event. | |
800 | ||
801 | This offers basically the same functionality as Connect(), but it is | |
802 | more flexible as it also allows you to use ordinary functions and | |
803 | arbitrary functors as event handlers. It is also less restrictive then | |
804 | Connect() because you can use an arbitrary method as an event handler, | |
57ab6f23 | 805 | whereas Connect() requires a wxEvtHandler derived handler. |
04a7eed1 VZ |
806 | |
807 | See @ref overview_events_bind for more detailed explanation | |
808 | of this function and the @ref page_samples_event sample for usage | |
809 | examples. | |
810 | ||
811 | @param eventType | |
812 | The event type to be associated with this event handler. | |
813 | @param functor | |
814 | The event handler functor. This can be an ordinary function but also | |
815 | an arbitrary functor like boost::function<>. | |
816 | @param id | |
817 | The first ID of the identifier range to be associated with the event | |
818 | handler. | |
819 | @param lastId | |
820 | The last ID of the identifier range to be associated with the event | |
821 | handler. | |
822 | @param userData | |
823 | Data to be associated with the event table entry. | |
824 | ||
eb23d11e JS |
825 | @see @ref overview_cpp_rtti_disabled |
826 | ||
04a7eed1 VZ |
827 | @since 2.9.0 |
828 | */ | |
829 | template <typename EventTag, typename Functor> | |
830 | void Bind(const EventTag& eventType, | |
831 | Functor functor, | |
832 | int id = wxID_ANY, | |
833 | int lastId = wxID_ANY, | |
834 | wxObject *userData = NULL); | |
835 | ||
836 | /** | |
837 | See the Bind<>(const EventTag&, Functor, int, int, wxObject*) overload for | |
838 | more info. | |
839 | ||
840 | This overload will bind the given method as the event handler. | |
841 | ||
842 | @param eventType | |
843 | The event type to be associated with this event handler. | |
844 | @param method | |
845 | The event handler method. This can be an arbitrary method (doesn't need | |
846 | to be from a wxEvtHandler derived class). | |
847 | @param handler | |
848 | Object whose method should be called. It must always be specified | |
849 | so it can be checked at compile time whether the given method is an | |
850 | actual member of the given handler. | |
851 | @param id | |
852 | The first ID of the identifier range to be associated with the event | |
853 | handler. | |
854 | @param lastId | |
855 | The last ID of the identifier range to be associated with the event | |
856 | handler. | |
857 | @param userData | |
858 | Data to be associated with the event table entry. | |
859 | ||
eb23d11e JS |
860 | @see @ref overview_cpp_rtti_disabled |
861 | ||
04a7eed1 VZ |
862 | @since 2.9.0 |
863 | */ | |
864 | template <typename EventTag, typename Class, typename EventArg, typename EventHandler> | |
865 | void Bind(const EventTag &eventType, | |
866 | void (Class::*method)(EventArg &), | |
867 | EventHandler *handler, | |
868 | int id = wxID_ANY, | |
869 | int lastId = wxID_ANY, | |
870 | wxObject *userData = NULL); | |
871 | /** | |
872 | Unbinds the given function, functor or method dynamically from the | |
873 | event handler, using the specified parameters as search criteria and | |
874 | returning @true if a matching function has been found and removed. | |
875 | ||
876 | This method can only unbind functions, functors or methods which have | |
877 | been added using the Bind<>() method. There is no way to unbind | |
fde702ea | 878 | functions bound using the (static) event tables. |
04a7eed1 VZ |
879 | |
880 | @param eventType | |
881 | The event type associated with this event handler. | |
882 | @param functor | |
883 | The event handler functor. This can be an ordinary function but also | |
884 | an arbitrary functor like boost::function<>. | |
885 | @param id | |
886 | The first ID of the identifier range associated with the event | |
887 | handler. | |
888 | @param lastId | |
889 | The last ID of the identifier range associated with the event | |
890 | handler. | |
891 | @param userData | |
892 | Data associated with the event table entry. | |
893 | ||
eb23d11e JS |
894 | @see @ref overview_cpp_rtti_disabled |
895 | ||
04a7eed1 VZ |
896 | @since 2.9.0 |
897 | */ | |
898 | template <typename EventTag, typename Functor> | |
899 | bool Unbind(const EventTag& eventType, | |
900 | Functor functor, | |
901 | int id = wxID_ANY, | |
902 | int lastId = wxID_ANY, | |
903 | wxObject *userData = NULL); | |
904 | ||
905 | /** | |
906 | See the Unbind<>(const EventTag&, Functor, int, int, wxObject*) | |
907 | overload for more info. | |
908 | ||
909 | This overload unbinds the given method from the event.. | |
910 | ||
911 | @param eventType | |
912 | The event type associated with this event handler. | |
913 | @param method | |
914 | The event handler method associated with this event. | |
915 | @param handler | |
916 | Object whose method was called. | |
917 | @param id | |
918 | The first ID of the identifier range associated with the event | |
919 | handler. | |
920 | @param lastId | |
921 | The last ID of the identifier range associated with the event | |
922 | handler. | |
923 | @param userData | |
924 | Data associated with the event table entry. | |
925 | ||
eb23d11e JS |
926 | @see @ref overview_cpp_rtti_disabled |
927 | ||
04a7eed1 VZ |
928 | @since 2.9.0 |
929 | */ | |
930 | template <typename EventTag, typename Class, typename EventArg, typename EventHandler> | |
931 | bool Unbind(const EventTag &eventType, | |
932 | void (Class::*method)(EventArg&), | |
933 | EventHandler *handler, | |
934 | int id = wxID_ANY, | |
935 | int lastId = wxID_ANY, | |
936 | wxObject *userData = NULL ); | |
937 | //@} | |
db82d78b FM |
938 | /** |
939 | @name User-supplied data | |
940 | */ | |
941 | //@{ | |
7c913512 | 942 | |
42013f4c FM |
943 | /** |
944 | Returns user-supplied client data. | |
7c913512 | 945 | |
42013f4c FM |
946 | @remarks Normally, any extra data the programmer wishes to associate with |
947 | the object should be made available by deriving a new class with | |
948 | new data members. | |
1f1d2182 | 949 | |
42013f4c FM |
950 | @see SetClientData() |
951 | */ | |
952 | void* GetClientData() const; | |
1f1d2182 | 953 | |
42013f4c FM |
954 | /** |
955 | Returns a pointer to the user-supplied client data object. | |
1f1d2182 | 956 | |
42013f4c FM |
957 | @see SetClientObject(), wxClientData |
958 | */ | |
959 | wxClientData* GetClientObject() const; | |
7c913512 | 960 | |
23324ae1 | 961 | /** |
db82d78b | 962 | Sets user-supplied client data. |
42013f4c | 963 | |
db82d78b FM |
964 | @param data |
965 | Data to be associated with the event handler. | |
23324ae1 | 966 | |
db82d78b FM |
967 | @remarks Normally, any extra data the programmer wishes to associate |
968 | with the object should be made available by deriving a new | |
969 | class with new data members. You must not call this method | |
970 | and SetClientObject on the same class - only one of them. | |
1f1d2182 | 971 | |
db82d78b | 972 | @see GetClientData() |
23324ae1 | 973 | */ |
db82d78b | 974 | void SetClientData(void* data); |
23324ae1 FM |
975 | |
976 | /** | |
db82d78b | 977 | Set the client data object. Any previous object will be deleted. |
1f1d2182 | 978 | |
db82d78b | 979 | @see GetClientObject(), wxClientData |
23324ae1 | 980 | */ |
db82d78b | 981 | void SetClientObject(wxClientData* data); |
7c913512 | 982 | |
db82d78b | 983 | //@} |
7c913512 | 984 | |
1f1d2182 | 985 | |
42013f4c | 986 | /** |
7f853dd0 FM |
987 | @name Event handler chaining |
988 | ||
989 | wxEvtHandler can be arranged in a double-linked list of handlers | |
990 | which is automatically iterated by ProcessEvent() if needed. | |
23324ae1 | 991 | */ |
db82d78b | 992 | //@{ |
23324ae1 | 993 | |
42013f4c | 994 | /** |
db82d78b | 995 | Returns @true if the event handler is enabled, @false otherwise. |
1f1d2182 | 996 | |
db82d78b | 997 | @see SetEvtHandlerEnabled() |
42013f4c | 998 | */ |
db82d78b | 999 | bool GetEvtHandlerEnabled() const; |
7c913512 | 1000 | |
42013f4c | 1001 | /** |
db82d78b | 1002 | Returns the pointer to the next handler in the chain. |
42013f4c | 1003 | |
db82d78b FM |
1004 | @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(), |
1005 | wxWindow::PushEventHandler, wxWindow::PopEventHandler | |
42013f4c | 1006 | */ |
db82d78b | 1007 | wxEvtHandler* GetNextHandler() const; |
7c913512 | 1008 | |
23324ae1 | 1009 | /** |
db82d78b | 1010 | Returns the pointer to the previous handler in the chain. |
42013f4c | 1011 | |
db82d78b FM |
1012 | @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(), |
1013 | wxWindow::PushEventHandler, wxWindow::PopEventHandler | |
23324ae1 | 1014 | */ |
db82d78b | 1015 | wxEvtHandler* GetPreviousHandler() const; |
42013f4c FM |
1016 | |
1017 | /** | |
1018 | Enables or disables the event handler. | |
1019 | ||
1020 | @param enabled | |
1021 | @true if the event handler is to be enabled, @false if it is to be disabled. | |
1022 | ||
1023 | @remarks You can use this function to avoid having to remove the event | |
1024 | handler from the chain, for example when implementing a | |
1025 | dialog editor and changing from edit to test mode. | |
1026 | ||
1027 | @see GetEvtHandlerEnabled() | |
1028 | */ | |
1029 | void SetEvtHandlerEnabled(bool enabled); | |
23324ae1 | 1030 | |
42013f4c FM |
1031 | /** |
1032 | Sets the pointer to the next handler. | |
1033 | ||
7f853dd0 FM |
1034 | @remarks |
1035 | See ProcessEvent() for more info about how the chains of event handlers | |
1036 | are internally used. | |
1037 | Also remember that wxEvtHandler uses double-linked lists and thus if you | |
1038 | use this function, you should also call SetPreviousHandler() on the | |
1039 | argument passed to this function: | |
1040 | @code | |
1041 | handlerA->SetNextHandler(handlerB); | |
1042 | handlerB->SetPreviousHandler(handlerA); | |
1043 | @endcode | |
1044 | ||
42013f4c | 1045 | @param handler |
7f853dd0 FM |
1046 | The event handler to be set as the next handler. |
1047 | Cannot be @NULL. | |
42013f4c | 1048 | |
3e083d65 | 1049 | @see @ref overview_events_processing |
42013f4c | 1050 | */ |
7f853dd0 | 1051 | virtual void SetNextHandler(wxEvtHandler* handler); |
42013f4c FM |
1052 | |
1053 | /** | |
1054 | Sets the pointer to the previous handler. | |
7f853dd0 | 1055 | All remarks about SetNextHandler() apply to this function as well. |
42013f4c FM |
1056 | |
1057 | @param handler | |
7f853dd0 FM |
1058 | The event handler to be set as the previous handler. |
1059 | Cannot be @NULL. | |
1060 | ||
3e083d65 | 1061 | @see @ref overview_events_processing |
7f853dd0 FM |
1062 | */ |
1063 | virtual void SetPreviousHandler(wxEvtHandler* handler); | |
1064 | ||
1065 | /** | |
1066 | Unlinks this event handler from the chain it's part of (if any); | |
1067 | then links the "previous" event handler to the "next" one | |
1068 | (so that the chain won't be interrupted). | |
1069 | ||
1070 | E.g. if before calling Unlink() you have the following chain: | |
1071 | @image html evthandler_unlink_before.png | |
1072 | then after calling @c B->Unlink() you'll have: | |
1073 | @image html evthandler_unlink_after.png | |
1074 | ||
1075 | @since 2.9.0 | |
1076 | */ | |
1077 | void Unlink(); | |
1078 | ||
1079 | /** | |
1080 | Returns @true if the next and the previous handler pointers of this | |
1081 | event handler instance are @NULL. | |
1082 | ||
1083 | @since 2.9.0 | |
1084 | ||
1085 | @see SetPreviousHandler(), SetNextHandler() | |
42013f4c | 1086 | */ |
7f853dd0 | 1087 | bool IsUnlinked() const; |
db82d78b FM |
1088 | |
1089 | //@} | |
8cc208e3 | 1090 | |
58cc1587 VZ |
1091 | /** |
1092 | @name Global event filters. | |
1093 | ||
1094 | Methods for working with the global list of event filters. | |
1095 | ||
1096 | Event filters can be defined to pre-process all the events that happen | |
1097 | in an application, see wxEventFilter documentation for more information. | |
1098 | */ | |
1099 | //@{ | |
1100 | ||
1101 | /** | |
1102 | Add an event filter whose FilterEvent() method will be called for each | |
1103 | and every event processed by wxWidgets. | |
1104 | ||
1105 | The filters are called in LIFO order and wxApp is registered as an | |
1106 | event filter by default. The pointer must remain valid until it's | |
1107 | removed with RemoveFilter() and is not deleted by wxEvtHandler. | |
1108 | ||
1109 | @since 2.9.3 | |
1110 | */ | |
1111 | static void AddFilter(wxEventFilter* filter); | |
1112 | ||
1113 | /** | |
1114 | Remove a filter previously installed with AddFilter(). | |
1115 | ||
1116 | It's an error to remove a filter that hadn't been previously added or | |
1117 | was already removed. | |
1118 | ||
1119 | @since 2.9.3 | |
1120 | */ | |
1121 | static void RemoveFilter(wxEventFilter* filter); | |
1122 | ||
1123 | //@} | |
1124 | ||
8cc208e3 VZ |
1125 | protected: |
1126 | /** | |
1127 | Method called by ProcessEvent() before examining this object event | |
1128 | tables. | |
1129 | ||
1130 | This method can be overridden to hook into the event processing logic | |
1131 | as early as possible. You should usually call the base class version | |
1132 | when overriding this method, even if wxEvtHandler itself does nothing | |
1133 | here, some derived classes do use this method, e.g. wxWindow implements | |
1134 | support for wxValidator in it. | |
1135 | ||
1136 | Example: | |
1137 | @code | |
1138 | class MyClass : public BaseClass // inheriting from wxEvtHandler | |
1139 | { | |
1140 | ... | |
1141 | protected: | |
1142 | virtual bool TryBefore(wxEvent& event) | |
1143 | { | |
1144 | if ( MyPreProcess(event) ) | |
1145 | return true; | |
1146 | ||
1147 | return BaseClass::TryBefore(event); | |
1148 | } | |
1149 | }; | |
1150 | @endcode | |
1151 | ||
512220b6 | 1152 | @see ProcessEvent() |
8cc208e3 VZ |
1153 | */ |
1154 | virtual bool TryBefore(wxEvent& event); | |
1155 | ||
1156 | /** | |
1157 | Method called by ProcessEvent() as last resort. | |
1158 | ||
1159 | This method can be overridden to implement post-processing for the | |
1160 | events which were not processed anywhere else. | |
1161 | ||
1162 | The base class version handles forwarding the unprocessed events to | |
1163 | wxApp at wxEvtHandler level and propagating them upwards the window | |
1164 | child-parent chain at wxWindow level and so should usually be called | |
1165 | when overriding this method: | |
1166 | @code | |
1167 | class MyClass : public BaseClass // inheriting from wxEvtHandler | |
1168 | { | |
1169 | ... | |
1170 | protected: | |
1171 | virtual bool TryAfter(wxEvent& event) | |
1172 | { | |
1173 | if ( BaseClass::TryAfter(event) ) | |
1174 | return true; | |
1175 | ||
1176 | return MyPostProcess(event); | |
1177 | } | |
1178 | }; | |
1179 | @endcode | |
1180 | ||
512220b6 | 1181 | @see ProcessEvent() |
8cc208e3 VZ |
1182 | */ |
1183 | virtual bool TryAfter(wxEvent& event); | |
42013f4c | 1184 | }; |
23324ae1 | 1185 | |
e54c96f1 | 1186 | |
7a34307e VZ |
1187 | /** |
1188 | Flags for categories of keys. | |
1189 | ||
1190 | These values are used by wxKeyEvent::IsKeyInCategory(). They may be | |
1191 | combined via the bitwise operators |, &, and ~. | |
1192 | ||
1193 | @since 2.9.1 | |
1194 | */ | |
1195 | enum wxKeyCategoryFlags | |
1196 | { | |
1197 | /// arrow keys, on and off numeric keypads | |
1198 | WXK_CATEGORY_ARROW, | |
1199 | ||
1200 | /// page up and page down keys, on and off numeric keypads | |
1201 | WXK_CATEGORY_PAGING, | |
1202 | ||
1203 | /// home and end keys, on and off numeric keypads | |
1204 | WXK_CATEGORY_JUMP, | |
1205 | ||
4f742042 | 1206 | /// tab key, on and off numeric keypads |
7a34307e VZ |
1207 | WXK_CATEGORY_TAB, |
1208 | ||
1209 | /// backspace and delete keys, on and off numeric keypads | |
1210 | WXK_CATEGORY_CUT, | |
1211 | ||
1212 | /// union of WXK_CATEGORY_ARROW, WXK_CATEGORY_PAGING, and WXK_CATEGORY_JUMP categories | |
1213 | WXK_CATEGORY_NAVIGATION | |
1214 | }; | |
1215 | ||
1216 | ||
23324ae1 | 1217 | /** |
42013f4c | 1218 | @class wxKeyEvent |
7c913512 | 1219 | |
0d2f3b9d | 1220 | This event class contains information about key press and release events. |
7c913512 | 1221 | |
7333c0ef VZ |
1222 | The main information carried by this event is the key being pressed or |
1223 | released. It can be accessed using either GetKeyCode() function or | |
1224 | GetUnicodeKey(). For the printable characters, the latter should be used as | |
1225 | it works for any keys, including non-Latin-1 characters that can be entered | |
1226 | when using national keyboard layouts. GetKeyCode() should be used to handle | |
1227 | special characters (such as cursor arrows keys or @c HOME or @c INS and so | |
1228 | on) which correspond to ::wxKeyCode enum elements above the @c WXK_START | |
1229 | constant. While GetKeyCode() also returns the character code for Latin-1 | |
1230 | keys for compatibility, it doesn't work for Unicode characters in general | |
1231 | and will return @c WXK_NONE for any non-Latin-1 ones. For this reason, it's | |
1232 | recommended to always use GetUnicodeKey() and only fall back to GetKeyCode() | |
1233 | if GetUnicodeKey() returned @c WXK_NONE meaning that the event corresponds | |
1234 | to a non-printable special keys. | |
1235 | ||
1236 | While both of these functions can be used with the events of @c | |
1237 | wxEVT_KEY_DOWN, @c wxEVT_KEY_UP and @c wxEVT_CHAR types, the values | |
1238 | returned by them are different for the first two events and the last one. | |
1239 | For the latter, the key returned corresponds to the character that would | |
1240 | appear in e.g. a text zone if the user pressed the key in it. As such, its | |
1241 | value depends on the current state of the Shift key and, for the letters, | |
1242 | on the state of Caps Lock modifier. For example, if @c A key is pressed | |
1243 | without Shift being held down, wxKeyEvent of type @c wxEVT_CHAR generated | |
1244 | for this key press will return (from either GetKeyCode() or GetUnicodeKey() | |
1245 | as their meanings coincide for ASCII characters) key code of 97 | |
1246 | corresponding the ASCII value of @c a. And if the same key is pressed but | |
1247 | with Shift being held (or Caps Lock being active), then the key could would | |
1248 | be 65, i.e. ASCII value of capital @c A. | |
1249 | ||
1250 | However for the key down and up events the returned key code will instead | |
1251 | be @c A independently of the state of the modifier keys i.e. it depends | |
1252 | only on physical key being pressed and is not translated to its logical | |
1253 | representation using the current keyboard state. Such untranslated key | |
1254 | codes are defined as follows: | |
1255 | - For the letters they correspond to the @e upper case value of the | |
1256 | letter. | |
1257 | - For the other alphanumeric keys (e.g. @c 7 or @c +), the untranslated | |
1258 | key code corresponds to the character produced by the key when it is | |
1259 | pressed without Shift. E.g. in standard US keyboard layout the | |
1260 | untranslated key code for the key @c =/+ in the upper right corner of | |
1261 | the keyboard is 61 which is the ASCII value of @c =. | |
1262 | - For the rest of the keys (i.e. special non-printable keys) it is the | |
1263 | same as the normal key code as no translation is used anyhow. | |
1264 | ||
1265 | Notice that the first rule applies to all Unicode letters, not just the | |
1266 | usual Latin-1 ones. However for non-Latin-1 letters only GetUnicodeKey() | |
1267 | can be used to retrieve the key code as GetKeyCode() just returns @c | |
1268 | WXK_NONE in this case. | |
1269 | ||
1270 | To summarize: you should handle @c wxEVT_CHAR if you need the translated | |
1271 | key and @c wxEVT_KEY_DOWN if you only need the value of the key itself, | |
1272 | independent of the current keyboard state. | |
1273 | ||
1274 | @note Not all key down events may be generated by the user. As an example, | |
1275 | @c wxEVT_KEY_DOWN with @c = key code can be generated using the | |
1276 | standard US keyboard layout but not using the German one because the @c | |
1277 | = key corresponds to Shift-0 key combination in this layout and the key | |
1278 | code for it is @c 0, not @c =. Because of this you should avoid | |
1279 | requiring your users to type key events that might be impossible to | |
1280 | enter on their keyboard. | |
1281 | ||
1282 | ||
1283 | Another difference between key and char events is that another kind of | |
1284 | translation is done for the latter ones when the Control key is pressed: | |
1285 | char events for ASCII letters in this case carry codes corresponding to the | |
1286 | ASCII value of Ctrl-Latter, i.e. 1 for Ctrl-A, 2 for Ctrl-B and so on until | |
1287 | 26 for Ctrl-Z. This is convenient for terminal-like applications and can be | |
1288 | completely ignored by all the other ones (if you need to handle Ctrl-A it | |
1289 | is probably a better idea to use the key event rather than the char one). | |
1290 | Notice that currently no translation is done for the presses of @c [, @c | |
1291 | \\, @c ], @c ^ and @c _ keys which might be mapped to ASCII values from 27 | |
1292 | to 31. | |
09bdb1cb VZ |
1293 | Since version 2.9.2, the enum values @c WXK_CONTROL_A - @c WXK_CONTROL_Z |
1294 | can be used instead of the non-descriptive constant values 1-26. | |
7333c0ef VZ |
1295 | |
1296 | Finally, modifier keys only generate key events but no char events at all. | |
1297 | The modifiers keys are @c WXK_SHIFT, @c WXK_CONTROL, @c WXK_ALT and various | |
1298 | @c WXK_WINDOWS_XXX from ::wxKeyCode enum. | |
0d2f3b9d | 1299 | |
d0fb62a6 VZ |
1300 | Modifier keys events are special in one additional aspect: usually the |
1301 | keyboard state associated with a key press is well defined, e.g. | |
1302 | wxKeyboardState::ShiftDown() returns @c true only if the Shift key was held | |
1303 | pressed when the key that generated this event itself was pressed. There is | |
1304 | an ambiguity for the key press events for Shift key itself however. By | |
1305 | convention, it is considered to be already pressed when it is pressed and | |
1306 | already released when it is released. In other words, @c wxEVT_KEY_DOWN | |
1307 | event for the Shift key itself will have @c wxMOD_SHIFT in GetModifiers() | |
1308 | and ShiftDown() will return true while the @c wxEVT_KEY_UP event for Shift | |
1309 | itself will not have @c wxMOD_SHIFT in its modifiers and ShiftDown() will | |
1310 | return false. | |
1311 | ||
1312 | ||
1313 | @b Tip: You may discover the key codes and modifiers generated by all the | |
1314 | keys on your system interactively by running the @ref | |
1315 | page_samples_keyboard wxWidgets sample and pressing some keys in it. | |
1f1d2182 | 1316 | |
42013f4c FM |
1317 | @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler |
1318 | does not call @c event.Skip() then the corresponding char event | |
d0fb62a6 VZ |
1319 | (@c EVT_CHAR) will not happen. This is by design and enables the |
1320 | programs that handle both types of events to avoid processing the | |
1321 | same key twice. As a consequence, if you do not want to suppress the | |
1322 | @c wxEVT_CHAR events for the keys you handle, always call @c | |
1323 | event.Skip() in your @c wxEVT_KEY_DOWN handler. Not doing may also | |
1324 | prevent accelerators defined using this key from working. | |
1f1d2182 | 1325 | |
5effc1cf VZ |
1326 | @note If a key is maintained in a pressed state, you will typically get a |
1327 | lot of (automatically generated) key down events but only one key up | |
1328 | one at the end when the key is released so it is wrong to assume that | |
1329 | there is one up event corresponding to each down one. | |
1330 | ||
42013f4c FM |
1331 | @note For Windows programmers: The key and char events in wxWidgets are |
1332 | similar to but slightly different from Windows @c WM_KEYDOWN and | |
1333 | @c WM_CHAR events. In particular, Alt-x combination will generate a | |
0d2f3b9d VZ |
1334 | char event in wxWidgets (unless it is used as an accelerator) and |
1335 | almost all keys, including ones without ASCII equivalents, generate | |
1336 | char events too. | |
1f1d2182 FM |
1337 | |
1338 | ||
42013f4c | 1339 | @beginEventTable{wxKeyEvent} |
8c6791e4 | 1340 | @event{EVT_KEY_DOWN(func)} |
f47a3591 VZ |
1341 | Process a @c wxEVT_KEY_DOWN event (any key has been pressed). If this |
1342 | event is handled and not skipped, @c wxEVT_CHAR will not be generated | |
1343 | at all for this key press (but @c wxEVT_KEY_UP will be). | |
8c6791e4 | 1344 | @event{EVT_KEY_UP(func)} |
3051a44a | 1345 | Process a @c wxEVT_KEY_UP event (any key has been released). |
8c6791e4 | 1346 | @event{EVT_CHAR(func)} |
3051a44a | 1347 | Process a @c wxEVT_CHAR event. |
ff450486 | 1348 | @event{EVT_CHAR_HOOK(func)} |
3a95f73c VZ |
1349 | Process a @c wxEVT_CHAR_HOOK event. Unlike all the other key events, |
1350 | this event is propagated upwards the window hierarchy which allows | |
1351 | intercepting it in the parent window of the focused window to which it | |
1352 | is sent initially (if there is no focused window, this event is sent to | |
1353 | the wxApp global object). It is also generated before any other key | |
1354 | events and so gives the parent window an opportunity to modify the | |
1355 | keyboard handling of its children, e.g. it is used internally by | |
1356 | wxWidgets in some ports to intercept pressing Esc key in any child of a | |
4cf1a9bf VZ |
1357 | dialog to close the dialog itself when it's pressed. By default, if |
1358 | this event is handled, i.e. the handler doesn't call wxEvent::Skip(), | |
1359 | neither @c wxEVT_KEY_DOWN nor @c wxEVT_CHAR events will be generated | |
1360 | (although @c wxEVT_KEY_UP still will be), i.e. it replaces the normal | |
1361 | key events. However by calling the special DoAllowNextEvent() method | |
1362 | you can handle @c wxEVT_CHAR_HOOK and still allow normal events | |
1363 | generation. This is something that is rarely useful but can be required | |
1364 | if you need to prevent a parent @c wxEVT_CHAR_HOOK handler from running | |
1365 | without suppressing the normal key events. Finally notice that this | |
1366 | event is not generated when the mouse is captured as it is considered | |
1367 | that the window which has the capture should receive all the keyboard | |
1368 | events too without allowing its parent wxTopLevelWindow to interfere | |
1369 | with their processing. | |
1f1d2182 | 1370 | @endEventTable |
7c913512 | 1371 | |
0e097789 VZ |
1372 | @see wxKeyboardState |
1373 | ||
23324ae1 FM |
1374 | @library{wxcore} |
1375 | @category{events} | |
23324ae1 | 1376 | */ |
0e097789 VZ |
1377 | class wxKeyEvent : public wxEvent, |
1378 | public wxKeyboardState | |
23324ae1 FM |
1379 | { |
1380 | public: | |
1381 | /** | |
1382 | Constructor. | |
42013f4c | 1383 | Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK. |
23324ae1 | 1384 | */ |
42013f4c | 1385 | wxKeyEvent(wxEventType keyEventType = wxEVT_NULL); |
23324ae1 | 1386 | |
42013f4c | 1387 | /** |
b6885972 VZ |
1388 | Returns the key code of the key that generated this event. |
1389 | ||
1390 | ASCII symbols return normal ASCII values, while events from special | |
1391 | keys such as "left cursor arrow" (@c WXK_LEFT) return values outside of | |
1392 | the ASCII range. See ::wxKeyCode for a full list of the virtual key | |
1393 | codes. | |
1394 | ||
1395 | Note that this method returns a meaningful value only for special | |
1396 | non-alphanumeric keys or if the user entered a character that can be | |
1397 | represented in current locale's default charset. Otherwise, e.g. if the | |
1398 | user enters a Japanese character in a program not using Japanese | |
1399 | locale, this method returns @c WXK_NONE and GetUnicodeKey() should be | |
1400 | used to obtain the corresponding Unicode character. | |
1401 | ||
1402 | Using GetUnicodeKey() is in general the right thing to do if you are | |
1403 | interested in the characters typed by the user, GetKeyCode() should be | |
1404 | only used for special keys (for which GetUnicodeKey() returns @c | |
1405 | WXK_NONE). To handle both kinds of keys you might write: | |
1406 | @code | |
1407 | void MyHandler::OnChar(wxKeyEvent& event) | |
1408 | { | |
1409 | if ( event.GetUnicodeKey() != WXK_NONE ) | |
1410 | { | |
1411 | // It's a printable character | |
1412 | wxLogMessage("You pressed '%c'", event.GetUnicodeKey()); | |
1413 | } | |
1414 | else | |
1415 | { | |
1416 | // It's a special key, deal with all the known ones: | |
95aced61 | 1417 | switch ( GetKeyCode() ) |
b6885972 VZ |
1418 | { |
1419 | case WXK_LEFT: | |
1420 | case WXK_RIGHT: | |
1421 | ... move cursor ... | |
1422 | break; | |
1423 | ||
1424 | case WXK_F1: | |
1425 | ... give help ... | |
1426 | break; | |
1427 | } | |
1428 | } | |
1429 | } | |
1430 | @endcode | |
42013f4c FM |
1431 | */ |
1432 | int GetKeyCode() const; | |
1433 | ||
7a34307e VZ |
1434 | /** |
1435 | Returns true if the key is in the given key category. | |
1436 | ||
1437 | @param category | |
1438 | A bitwise combination of named ::wxKeyCategoryFlags constants. | |
1439 | ||
1440 | @since 2.9.1 | |
1441 | */ | |
1442 | bool IsKeyInCategory(int category) const; | |
1443 | ||
42013f4c FM |
1444 | //@{ |
1445 | /** | |
1446 | Obtains the position (in client coordinates) at which the key was pressed. | |
1447 | */ | |
1448 | wxPoint GetPosition() const; | |
1449 | void GetPosition(long* x, long* y) const; | |
1450 | //@} | |
1451 | ||
1452 | /** | |
5995a84f VZ |
1453 | Returns the raw key code for this event. |
1454 | ||
1455 | The flags are platform-dependent and should only be used if the | |
1456 | functionality provided by other wxKeyEvent methods is insufficient. | |
1457 | ||
1458 | Under MSW, the raw key code is the value of @c wParam parameter of the | |
1459 | corresponding message. | |
1460 | ||
1461 | Under GTK, the raw key code is the @c keyval field of the corresponding | |
1462 | GDK event. | |
1463 | ||
1464 | Under OS X, the raw key code is the @c keyCode field of the | |
1465 | corresponding NSEvent. | |
42013f4c FM |
1466 | |
1467 | @note Currently the raw key codes are not supported by all ports, use | |
1468 | @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. | |
1469 | */ | |
1470 | wxUint32 GetRawKeyCode() const; | |
1471 | ||
1472 | /** | |
5995a84f VZ |
1473 | Returns the low level key flags for this event. |
1474 | ||
1475 | The flags are platform-dependent and should only be used if the | |
1476 | functionality provided by other wxKeyEvent methods is insufficient. | |
1477 | ||
1478 | Under MSW, the raw flags are just the value of @c lParam parameter of | |
1479 | the corresponding message. | |
1480 | ||
1481 | Under GTK, the raw flags contain the @c hardware_keycode field of the | |
1482 | corresponding GDK event. | |
1483 | ||
1484 | Under OS X, the raw flags contain the modifiers state. | |
42013f4c FM |
1485 | |
1486 | @note Currently the raw key flags are not supported by all ports, use | |
1487 | @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. | |
1488 | */ | |
1489 | wxUint32 GetRawKeyFlags() const; | |
1490 | ||
1491 | /** | |
1492 | Returns the Unicode character corresponding to this key event. | |
1493 | ||
0d2f3b9d | 1494 | If the key pressed doesn't have any character value (e.g. a cursor key) |
86408a03 VZ |
1495 | this method will return @c WXK_NONE. In this case you should use |
1496 | GetKeyCode() to retrieve the value of the key. | |
0d2f3b9d | 1497 | |
42013f4c FM |
1498 | This function is only available in Unicode build, i.e. when |
1499 | @c wxUSE_UNICODE is 1. | |
1500 | */ | |
1501 | wxChar GetUnicodeKey() const; | |
1502 | ||
1503 | /** | |
1504 | Returns the X position (in client coordinates) of the event. | |
1505 | */ | |
1506 | wxCoord GetX() const; | |
1507 | ||
1508 | /** | |
1509 | Returns the Y position (in client coordinates) of the event. | |
1510 | */ | |
1511 | wxCoord GetY() const; | |
4cf1a9bf VZ |
1512 | |
1513 | /** | |
1514 | Allow normal key events generation. | |
1515 | ||
1516 | Can be called from @c wxEVT_CHAR_HOOK handler to indicate that the | |
1517 | generation of normal events should @em not be suppressed, as it happens | |
1518 | by default when this event is handled. | |
1519 | ||
1520 | The intended use of this method is to allow some window object to | |
1521 | prevent @c wxEVT_CHAR_HOOK handler in its parent window from running by | |
1522 | defining its own handler for this event. Without calling this method, | |
1523 | this would result in not generating @c wxEVT_KEY_DOWN nor @c wxEVT_CHAR | |
1524 | events at all but by calling it you can ensure that these events would | |
1525 | still be generated, even if @c wxEVT_CHAR_HOOK event was handled. | |
1526 | ||
1527 | @since 2.9.3 | |
1528 | */ | |
1529 | void DoAllowNextEvent(); | |
1530 | ||
1531 | /** | |
1532 | Returns @true if DoAllowNextEvent() had been called, @false by default. | |
1533 | ||
1534 | This method is used by wxWidgets itself to determine whether the normal | |
1535 | key events should be generated after @c wxEVT_CHAR_HOOK processing. | |
1536 | ||
1537 | @since 2.9.3 | |
1538 | */ | |
1539 | bool IsNextEventAllowed() const; | |
23324ae1 FM |
1540 | }; |
1541 | ||
1542 | ||
e54c96f1 | 1543 | |
50e55c13 RD |
1544 | enum |
1545 | { | |
1546 | wxJOYSTICK1, | |
1547 | wxJOYSTICK2 | |
1548 | }; | |
1549 | ||
1550 | // Which button is down? | |
1551 | enum | |
1552 | { | |
1553 | wxJOY_BUTTON_ANY = -1, | |
1554 | wxJOY_BUTTON1 = 1, | |
1555 | wxJOY_BUTTON2 = 2, | |
1556 | wxJOY_BUTTON3 = 4, | |
1557 | wxJOY_BUTTON4 = 8 | |
1558 | }; | |
1559 | ||
1560 | ||
23324ae1 | 1561 | /** |
42013f4c | 1562 | @class wxJoystickEvent |
7c913512 | 1563 | |
42013f4c FM |
1564 | This event class contains information about joystick events, particularly |
1565 | events received by windows. | |
1f1d2182 | 1566 | |
42013f4c | 1567 | @beginEventTable{wxJoystickEvent} |
3051a44a FM |
1568 | @event{EVT_JOY_BUTTON_DOWN(func)} |
1569 | Process a @c wxEVT_JOY_BUTTON_DOWN event. | |
1570 | @event{EVT_JOY_BUTTON_UP(func)} | |
1571 | Process a @c wxEVT_JOY_BUTTON_UP event. | |
1572 | @event{EVT_JOY_MOVE(func)} | |
1573 | Process a @c wxEVT_JOY_MOVE event. | |
1574 | @event{EVT_JOY_ZMOVE(func)} | |
1575 | Process a @c wxEVT_JOY_ZMOVE event. | |
1576 | @event{EVT_JOYSTICK_EVENTS(func)} | |
42013f4c | 1577 | Processes all joystick events. |
1f1d2182 FM |
1578 | @endEventTable |
1579 | ||
23324ae1 FM |
1580 | @library{wxcore} |
1581 | @category{events} | |
7c913512 | 1582 | |
42013f4c | 1583 | @see wxJoystick |
23324ae1 | 1584 | */ |
42013f4c | 1585 | class wxJoystickEvent : public wxEvent |
23324ae1 FM |
1586 | { |
1587 | public: | |
1588 | /** | |
1589 | Constructor. | |
1590 | */ | |
42013f4c FM |
1591 | wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0, |
1592 | int joystick = wxJOYSTICK1, | |
1593 | int change = 0); | |
23324ae1 FM |
1594 | |
1595 | /** | |
42013f4c FM |
1596 | Returns @true if the event was a down event from the specified button |
1597 | (or any button). | |
23324ae1 | 1598 | |
42013f4c FM |
1599 | @param button |
1600 | Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to | |
1601 | indicate any button down event. | |
23324ae1 | 1602 | */ |
42013f4c | 1603 | bool ButtonDown(int button = wxJOY_BUTTON_ANY) const; |
23324ae1 FM |
1604 | |
1605 | /** | |
42013f4c | 1606 | Returns @true if the specified button (or any button) was in a down state. |
23324ae1 | 1607 | |
42013f4c FM |
1608 | @param button |
1609 | Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to | |
1610 | indicate any button down event. | |
23324ae1 | 1611 | */ |
42013f4c | 1612 | bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const; |
23324ae1 FM |
1613 | |
1614 | /** | |
42013f4c FM |
1615 | Returns @true if the event was an up event from the specified button |
1616 | (or any button). | |
1617 | ||
1618 | @param button | |
1619 | Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to | |
1620 | indicate any button down event. | |
23324ae1 | 1621 | */ |
42013f4c | 1622 | bool ButtonUp(int button = wxJOY_BUTTON_ANY) const; |
23324ae1 FM |
1623 | |
1624 | /** | |
42013f4c FM |
1625 | Returns the identifier of the button changing state. |
1626 | ||
1627 | This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. | |
23324ae1 | 1628 | */ |
42013f4c | 1629 | int GetButtonChange() const; |
23324ae1 FM |
1630 | |
1631 | /** | |
42013f4c FM |
1632 | Returns the down state of the buttons. |
1633 | ||
1634 | This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. | |
23324ae1 | 1635 | */ |
42013f4c | 1636 | int GetButtonState() const; |
23324ae1 FM |
1637 | |
1638 | /** | |
42013f4c FM |
1639 | Returns the identifier of the joystick generating the event - one of |
1640 | wxJOYSTICK1 and wxJOYSTICK2. | |
23324ae1 | 1641 | */ |
42013f4c | 1642 | int GetJoystick() const; |
23324ae1 FM |
1643 | |
1644 | /** | |
42013f4c | 1645 | Returns the x, y position of the joystick event. |
3b2f80c2 VZ |
1646 | |
1647 | These coordinates are valid for all the events except wxEVT_JOY_ZMOVE. | |
23324ae1 | 1648 | */ |
42013f4c | 1649 | wxPoint GetPosition() const; |
23324ae1 FM |
1650 | |
1651 | /** | |
42013f4c | 1652 | Returns the z position of the joystick event. |
3b2f80c2 VZ |
1653 | |
1654 | This method can only be used for wxEVT_JOY_ZMOVE events. | |
23324ae1 | 1655 | */ |
42013f4c | 1656 | int GetZPosition() const; |
23324ae1 FM |
1657 | |
1658 | /** | |
42013f4c FM |
1659 | Returns @true if this was a button up or down event |
1660 | (@e not 'is any button down?'). | |
23324ae1 | 1661 | */ |
42013f4c | 1662 | bool IsButton() const; |
23324ae1 FM |
1663 | |
1664 | /** | |
42013f4c | 1665 | Returns @true if this was an x, y move event. |
23324ae1 | 1666 | */ |
42013f4c | 1667 | bool IsMove() const; |
23324ae1 FM |
1668 | |
1669 | /** | |
42013f4c | 1670 | Returns @true if this was a z move event. |
23324ae1 | 1671 | */ |
42013f4c FM |
1672 | bool IsZMove() const; |
1673 | }; | |
23324ae1 | 1674 | |
3c4f71cc | 1675 | |
23324ae1 | 1676 | |
42013f4c FM |
1677 | /** |
1678 | @class wxScrollWinEvent | |
42013f4c FM |
1679 | |
1680 | A scroll event holds information about events sent from scrolling windows. | |
1681 | ||
3051a44a FM |
1682 | Note that you can use the EVT_SCROLLWIN* macros for intercepting scroll window events |
1683 | from the receiving window. | |
23324ae1 | 1684 | |
42013f4c | 1685 | @beginEventTable{wxScrollWinEvent} |
8c6791e4 | 1686 | @event{EVT_SCROLLWIN(func)} |
42013f4c | 1687 | Process all scroll events. |
8c6791e4 | 1688 | @event{EVT_SCROLLWIN_TOP(func)} |
3a194bda | 1689 | Process @c wxEVT_SCROLLWIN_TOP scroll-to-top events. |
8c6791e4 | 1690 | @event{EVT_SCROLLWIN_BOTTOM(func)} |
3a194bda | 1691 | Process @c wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events. |
8c6791e4 | 1692 | @event{EVT_SCROLLWIN_LINEUP(func)} |
3a194bda | 1693 | Process @c wxEVT_SCROLLWIN_LINEUP line up events. |
8c6791e4 | 1694 | @event{EVT_SCROLLWIN_LINEDOWN(func)} |
3a194bda | 1695 | Process @c wxEVT_SCROLLWIN_LINEDOWN line down events. |
8c6791e4 | 1696 | @event{EVT_SCROLLWIN_PAGEUP(func)} |
3a194bda | 1697 | Process @c wxEVT_SCROLLWIN_PAGEUP page up events. |
8c6791e4 | 1698 | @event{EVT_SCROLLWIN_PAGEDOWN(func)} |
3a194bda | 1699 | Process @c wxEVT_SCROLLWIN_PAGEDOWN page down events. |
8c6791e4 | 1700 | @event{EVT_SCROLLWIN_THUMBTRACK(func)} |
3a194bda | 1701 | Process @c wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events |
42013f4c | 1702 | (frequent events sent as the user drags the thumbtrack). |
8c6791e4 | 1703 | @event{EVT_SCROLLWIN_THUMBRELEASE(func)} |
3a194bda | 1704 | Process @c wxEVT_SCROLLWIN_THUMBRELEASE thumb release events. |
42013f4c FM |
1705 | @endEventTable |
1706 | ||
1707 | ||
1708 | @library{wxcore} | |
1709 | @category{events} | |
1710 | ||
3e083d65 | 1711 | @see wxScrollEvent, @ref overview_events |
42013f4c FM |
1712 | */ |
1713 | class wxScrollWinEvent : public wxEvent | |
1714 | { | |
1715 | public: | |
23324ae1 | 1716 | /** |
42013f4c | 1717 | Constructor. |
23324ae1 | 1718 | */ |
42013f4c FM |
1719 | wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0, |
1720 | int orientation = 0); | |
23324ae1 FM |
1721 | |
1722 | /** | |
42013f4c FM |
1723 | Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the |
1724 | scrollbar. | |
1725 | ||
1726 | @todo wxHORIZONTAL and wxVERTICAL should go in their own enum | |
23324ae1 | 1727 | */ |
42013f4c | 1728 | int GetOrientation() const; |
23324ae1 FM |
1729 | |
1730 | /** | |
42013f4c FM |
1731 | Returns the position of the scrollbar for the thumb track and release events. |
1732 | ||
1733 | Note that this field can't be used for the other events, you need to query | |
1734 | the window itself for the current position in that case. | |
23324ae1 | 1735 | */ |
42013f4c | 1736 | int GetPosition() const; |
a90e69f7 RD |
1737 | |
1738 | void SetOrientation(int orient); | |
1739 | void SetPosition(int pos); | |
23324ae1 FM |
1740 | }; |
1741 | ||
1742 | ||
e54c96f1 | 1743 | |
23324ae1 | 1744 | /** |
42013f4c | 1745 | @class wxSysColourChangedEvent |
7c913512 | 1746 | |
42013f4c FM |
1747 | This class is used for system colour change events, which are generated |
1748 | when the user changes the colour settings using the control panel. | |
1749 | This is only appropriate under Windows. | |
7c913512 | 1750 | |
42013f4c FM |
1751 | @remarks |
1752 | The default event handler for this event propagates the event to child windows, | |
1753 | since Windows only sends the events to top-level windows. | |
1754 | If intercepting this event for a top-level window, remember to call the base | |
1755 | class handler, or to pass the event on to the window's children explicitly. | |
3d6c68c1 | 1756 | |
42013f4c | 1757 | @beginEventTable{wxSysColourChangedEvent} |
8c6791e4 | 1758 | @event{EVT_SYS_COLOUR_CHANGED(func)} |
3051a44a | 1759 | Process a @c wxEVT_SYS_COLOUR_CHANGED event. |
3d6c68c1 VS |
1760 | @endEventTable |
1761 | ||
23324ae1 FM |
1762 | @library{wxcore} |
1763 | @category{events} | |
7c913512 | 1764 | |
3e083d65 | 1765 | @see @ref overview_events |
23324ae1 | 1766 | */ |
42013f4c | 1767 | class wxSysColourChangedEvent : public wxEvent |
23324ae1 FM |
1768 | { |
1769 | public: | |
1770 | /** | |
3d6c68c1 | 1771 | Constructor. |
23324ae1 | 1772 | */ |
42013f4c | 1773 | wxSysColourChangedEvent(); |
23324ae1 FM |
1774 | }; |
1775 | ||
1776 | ||
e54c96f1 | 1777 | |
23324ae1 | 1778 | /** |
42013f4c | 1779 | @class wxWindowCreateEvent |
7c913512 | 1780 | |
42013f4c FM |
1781 | This event is sent just after the actual window associated with a wxWindow |
1782 | object has been created. | |
7c913512 | 1783 | |
42013f4c FM |
1784 | Since it is derived from wxCommandEvent, the event propagates up |
1785 | the window hierarchy. | |
7c913512 | 1786 | |
42013f4c | 1787 | @beginEventTable{wxWindowCreateEvent} |
8c6791e4 | 1788 | @event{EVT_WINDOW_CREATE(func)} |
3051a44a | 1789 | Process a @c wxEVT_CREATE event. |
42013f4c | 1790 | @endEventTable |
7c913512 | 1791 | |
23324ae1 FM |
1792 | @library{wxcore} |
1793 | @category{events} | |
7c913512 | 1794 | |
3e083d65 | 1795 | @see @ref overview_events, wxWindowDestroyEvent |
23324ae1 | 1796 | */ |
42013f4c | 1797 | class wxWindowCreateEvent : public wxCommandEvent |
23324ae1 FM |
1798 | { |
1799 | public: | |
1800 | /** | |
42013f4c FM |
1801 | Constructor. |
1802 | */ | |
1803 | wxWindowCreateEvent(wxWindow* win = NULL); | |
a79a6671 | 1804 | |
57ab6f23 | 1805 | /// Return the window being created. |
a79a6671 | 1806 | wxWindow *GetWindow() const; |
42013f4c | 1807 | }; |
3c4f71cc | 1808 | |
23324ae1 | 1809 | |
23324ae1 | 1810 | |
42013f4c FM |
1811 | /** |
1812 | @class wxPaintEvent | |
23324ae1 | 1813 | |
42013f4c | 1814 | A paint event is sent when a window's contents needs to be repainted. |
23324ae1 | 1815 | |
7ca106e8 VZ |
1816 | The handler of this event must create a wxPaintDC object and use it for |
1817 | painting the window contents. For example: | |
42013f4c FM |
1818 | @code |
1819 | void MyWindow::OnPaint(wxPaintEvent& event) | |
1820 | { | |
1821 | wxPaintDC dc(this); | |
23324ae1 | 1822 | |
42013f4c FM |
1823 | DrawMyDocument(dc); |
1824 | } | |
1825 | @endcode | |
7ca106e8 VZ |
1826 | |
1827 | Notice that you must @e not create other kinds of wxDC (e.g. wxClientDC or | |
1828 | wxWindowDC) in EVT_PAINT handlers and also don't create wxPaintDC outside | |
1829 | of this event handlers. | |
1830 | ||
1831 | ||
42013f4c FM |
1832 | You can optimize painting by retrieving the rectangles that have been damaged |
1833 | and only repainting these. The rectangles are in terms of the client area, | |
1834 | and are unscrolled, so you will need to do some calculations using the current | |
1835 | view position to obtain logical, scrolled units. | |
1836 | Here is an example of using the wxRegionIterator class: | |
1837 | @code | |
1838 | // Called when window needs to be repainted. | |
1839 | void MyWindow::OnPaint(wxPaintEvent& event) | |
1840 | { | |
1841 | wxPaintDC dc(this); | |
23324ae1 | 1842 | |
42013f4c FM |
1843 | // Find Out where the window is scrolled to |
1844 | int vbX,vbY; // Top left corner of client | |
1845 | GetViewStart(&vbX,&vbY); | |
23324ae1 | 1846 | |
42013f4c FM |
1847 | int vX,vY,vW,vH; // Dimensions of client area in pixels |
1848 | wxRegionIterator upd(GetUpdateRegion()); // get the update rect list | |
23324ae1 | 1849 | |
42013f4c FM |
1850 | while (upd) |
1851 | { | |
1852 | vX = upd.GetX(); | |
1853 | vY = upd.GetY(); | |
1854 | vW = upd.GetW(); | |
1855 | vH = upd.GetH(); | |
23324ae1 | 1856 | |
42013f4c FM |
1857 | // Alternatively we can do this: |
1858 | // wxRect rect(upd.GetRect()); | |
3c4f71cc | 1859 | |
42013f4c FM |
1860 | // Repaint this rectangle |
1861 | ...some code... | |
3c4f71cc | 1862 | |
42013f4c FM |
1863 | upd ++ ; |
1864 | } | |
1865 | } | |
1866 | @endcode | |
3c4f71cc | 1867 | |
7ca106e8 VZ |
1868 | @remarks |
1869 | Please notice that in general it is impossible to change the drawing of a | |
1870 | standard control (such as wxButton) and so you shouldn't attempt to handle | |
1871 | paint events for them as even if it might work on some platforms, this is | |
1872 | inherently not portable and won't work everywhere. | |
1873 | ||
3c4f71cc | 1874 | |
42013f4c | 1875 | @beginEventTable{wxPaintEvent} |
8c6791e4 | 1876 | @event{EVT_PAINT(func)} |
3051a44a | 1877 | Process a @c wxEVT_PAINT event. |
42013f4c | 1878 | @endEventTable |
3c4f71cc | 1879 | |
42013f4c FM |
1880 | @library{wxcore} |
1881 | @category{events} | |
3c4f71cc | 1882 | |
3e083d65 | 1883 | @see @ref overview_events |
42013f4c FM |
1884 | */ |
1885 | class wxPaintEvent : public wxEvent | |
1886 | { | |
1887 | public: | |
1888 | /** | |
1889 | Constructor. | |
1890 | */ | |
1891 | wxPaintEvent(int id = 0); | |
1892 | }; | |
3c4f71cc | 1893 | |
3c4f71cc | 1894 | |
3c4f71cc | 1895 | |
42013f4c FM |
1896 | /** |
1897 | @class wxMaximizeEvent | |
3c4f71cc | 1898 | |
42013f4c FM |
1899 | An event being sent when a top level window is maximized. Notice that it is |
1900 | not sent when the window is restored to its original size after it had been | |
1901 | maximized, only a normal wxSizeEvent is generated in this case. | |
3c4f71cc | 1902 | |
89c6e024 | 1903 | Currently this event is only generated in wxMSW, wxGTK, wxOSX/Cocoa and wxOS2 |
e22e5ee4 VZ |
1904 | ports so portable programs should only rely on receiving @c wxEVT_SIZE and |
1905 | not necessarily this event when the window is maximized. | |
1906 | ||
42013f4c | 1907 | @beginEventTable{wxMaximizeEvent} |
8c6791e4 | 1908 | @event{EVT_MAXIMIZE(func)} |
3051a44a | 1909 | Process a @c wxEVT_MAXIMIZE event. |
42013f4c | 1910 | @endEventTable |
3c4f71cc | 1911 | |
42013f4c FM |
1912 | @library{wxcore} |
1913 | @category{events} | |
23324ae1 | 1914 | |
3e083d65 | 1915 | @see @ref overview_events, wxTopLevelWindow::Maximize, |
42013f4c FM |
1916 | wxTopLevelWindow::IsMaximized |
1917 | */ | |
1918 | class wxMaximizeEvent : public wxEvent | |
1919 | { | |
1920 | public: | |
23324ae1 | 1921 | /** |
42013f4c | 1922 | Constructor. Only used by wxWidgets internally. |
23324ae1 | 1923 | */ |
42013f4c FM |
1924 | wxMaximizeEvent(int id = 0); |
1925 | }; | |
23324ae1 | 1926 | |
42013f4c FM |
1927 | /** |
1928 | The possibles modes to pass to wxUpdateUIEvent::SetMode(). | |
1929 | */ | |
1930 | enum wxUpdateUIMode | |
1931 | { | |
1932 | /** Send UI update events to all windows. */ | |
1933 | wxUPDATE_UI_PROCESS_ALL, | |
23324ae1 | 1934 | |
42013f4c FM |
1935 | /** Send UI update events to windows that have |
1936 | the wxWS_EX_PROCESS_UI_UPDATES flag specified. */ | |
1937 | wxUPDATE_UI_PROCESS_SPECIFIED | |
1938 | }; | |
23324ae1 | 1939 | |
3c4f71cc | 1940 | |
42013f4c FM |
1941 | /** |
1942 | @class wxUpdateUIEvent | |
23324ae1 | 1943 | |
42013f4c FM |
1944 | This class is used for pseudo-events which are called by wxWidgets |
1945 | to give an application the chance to update various user interface elements. | |
23324ae1 | 1946 | |
42013f4c FM |
1947 | Without update UI events, an application has to work hard to check/uncheck, |
1948 | enable/disable, show/hide, and set the text for elements such as menu items | |
1949 | and toolbar buttons. The code for doing this has to be mixed up with the code | |
1950 | that is invoked when an action is invoked for a menu item or button. | |
3c4f71cc | 1951 | |
42013f4c FM |
1952 | With update UI events, you define an event handler to look at the state of the |
1953 | application and change UI elements accordingly. wxWidgets will call your member | |
1954 | functions in idle time, so you don't have to worry where to call this code. | |
23324ae1 | 1955 | |
42013f4c FM |
1956 | In addition to being a clearer and more declarative method, it also means you don't |
1957 | have to worry whether you're updating a toolbar or menubar identifier. The same | |
1958 | handler can update a menu item and toolbar button, if the identifier is the same. | |
1959 | Instead of directly manipulating the menu or button, you call functions in the event | |
1960 | object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a | |
1961 | call has been made, and which UI element to update. | |
23324ae1 | 1962 | |
42013f4c FM |
1963 | These events will work for popup menus as well as menubars. Just before a menu is |
1964 | popped up, wxMenu::UpdateUI is called to process any UI events for the window that | |
1965 | owns the menu. | |
23324ae1 | 1966 | |
42013f4c FM |
1967 | If you find that the overhead of UI update processing is affecting your application, |
1968 | you can do one or both of the following: | |
1969 | @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED, | |
1970 | and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should | |
1971 | receive update events. No other windows will receive update events. | |
1972 | @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay | |
1973 | between updates. You may need to call wxWindow::UpdateWindowUI at critical points, | |
1974 | for example when a dialog is about to be shown, in case the user sees a slight | |
1975 | delay before windows are updated. | |
3c4f71cc | 1976 | |
42013f4c FM |
1977 | Note that although events are sent in idle time, defining a wxIdleEvent handler |
1978 | for a window does not affect this because the events are sent from wxWindow::OnInternalIdle | |
1979 | which is always called in idle time. | |
23324ae1 | 1980 | |
42013f4c FM |
1981 | wxWidgets tries to optimize update events on some platforms. |
1982 | On Windows and GTK+, events for menubar items are only sent when the menu is about | |
1983 | to be shown, and not in idle time. | |
23324ae1 | 1984 | |
23324ae1 | 1985 | |
42013f4c | 1986 | @beginEventTable{wxUpdateUIEvent} |
8c6791e4 | 1987 | @event{EVT_UPDATE_UI(id, func)} |
3051a44a | 1988 | Process a @c wxEVT_UPDATE_UI event for the command with the given id. |
8c6791e4 | 1989 | @event{EVT_UPDATE_UI_RANGE(id1, id2, func)} |
3051a44a | 1990 | Process a @c wxEVT_UPDATE_UI event for any command with id included in the given range. |
42013f4c | 1991 | @endEventTable |
23324ae1 | 1992 | |
42013f4c FM |
1993 | @library{wxcore} |
1994 | @category{events} | |
23324ae1 | 1995 | |
3e083d65 | 1996 | @see @ref overview_events |
42013f4c FM |
1997 | */ |
1998 | class wxUpdateUIEvent : public wxCommandEvent | |
1999 | { | |
2000 | public: | |
23324ae1 | 2001 | /** |
42013f4c | 2002 | Constructor. |
23324ae1 | 2003 | */ |
42013f4c | 2004 | wxUpdateUIEvent(wxWindowID commandId = 0); |
23324ae1 FM |
2005 | |
2006 | /** | |
42013f4c FM |
2007 | Returns @true if it is appropriate to update (send UI update events to) |
2008 | this window. | |
23324ae1 | 2009 | |
42013f4c FM |
2010 | This function looks at the mode used (see wxUpdateUIEvent::SetMode), |
2011 | the wxWS_EX_PROCESS_UI_UPDATES flag in @a window, the time update events | |
2012 | were last sent in idle time, and the update interval, to determine whether | |
2013 | events should be sent to this window now. By default this will always | |
2014 | return @true because the update mode is initially wxUPDATE_UI_PROCESS_ALL | |
2015 | and the interval is set to 0; so update events will be sent as often as | |
2016 | possible. You can reduce the frequency that events are sent by changing the | |
2017 | mode and/or setting an update interval. | |
23324ae1 | 2018 | |
42013f4c | 2019 | @see ResetUpdateTime(), SetUpdateInterval(), SetMode() |
23324ae1 | 2020 | */ |
42013f4c | 2021 | static bool CanUpdate(wxWindow* window); |
23324ae1 FM |
2022 | |
2023 | /** | |
42013f4c | 2024 | Check or uncheck the UI element. |
23324ae1 | 2025 | */ |
42013f4c | 2026 | void Check(bool check); |
23324ae1 FM |
2027 | |
2028 | /** | |
42013f4c | 2029 | Enable or disable the UI element. |
23324ae1 | 2030 | */ |
42013f4c | 2031 | void Enable(bool enable); |
23324ae1 FM |
2032 | |
2033 | /** | |
42013f4c | 2034 | Returns @true if the UI element should be checked. |
23324ae1 | 2035 | */ |
42013f4c | 2036 | bool GetChecked() const; |
23324ae1 FM |
2037 | |
2038 | /** | |
42013f4c | 2039 | Returns @true if the UI element should be enabled. |
23324ae1 | 2040 | */ |
42013f4c | 2041 | bool GetEnabled() const; |
23324ae1 FM |
2042 | |
2043 | /** | |
42013f4c FM |
2044 | Static function returning a value specifying how wxWidgets will send update |
2045 | events: to all windows, or only to those which specify that they will process | |
2046 | the events. | |
23324ae1 | 2047 | |
42013f4c | 2048 | @see SetMode() |
23324ae1 | 2049 | */ |
42013f4c | 2050 | static wxUpdateUIMode GetMode(); |
23324ae1 FM |
2051 | |
2052 | /** | |
42013f4c FM |
2053 | Returns @true if the application has called Check(). |
2054 | For wxWidgets internal use only. | |
23324ae1 | 2055 | */ |
42013f4c | 2056 | bool GetSetChecked() const; |
23324ae1 FM |
2057 | |
2058 | /** | |
42013f4c FM |
2059 | Returns @true if the application has called Enable(). |
2060 | For wxWidgets internal use only. | |
23324ae1 | 2061 | */ |
42013f4c | 2062 | bool GetSetEnabled() const; |
23324ae1 FM |
2063 | |
2064 | /** | |
42013f4c FM |
2065 | Returns @true if the application has called Show(). |
2066 | For wxWidgets internal use only. | |
23324ae1 | 2067 | */ |
42013f4c | 2068 | bool GetSetShown() const; |
23324ae1 FM |
2069 | |
2070 | /** | |
42013f4c FM |
2071 | Returns @true if the application has called SetText(). |
2072 | For wxWidgets internal use only. | |
23324ae1 | 2073 | */ |
42013f4c | 2074 | bool GetSetText() const; |
23324ae1 FM |
2075 | |
2076 | /** | |
42013f4c | 2077 | Returns @true if the UI element should be shown. |
23324ae1 | 2078 | */ |
42013f4c | 2079 | bool GetShown() const; |
23324ae1 FM |
2080 | |
2081 | /** | |
42013f4c | 2082 | Returns the text that should be set for the UI element. |
23324ae1 | 2083 | */ |
42013f4c | 2084 | wxString GetText() const; |
23324ae1 FM |
2085 | |
2086 | /** | |
42013f4c FM |
2087 | Returns the current interval between updates in milliseconds. |
2088 | The value -1 disables updates, 0 updates as frequently as possible. | |
23324ae1 | 2089 | |
42013f4c | 2090 | @see SetUpdateInterval(). |
23324ae1 | 2091 | */ |
42013f4c | 2092 | static long GetUpdateInterval(); |
23324ae1 FM |
2093 | |
2094 | /** | |
42013f4c | 2095 | Used internally to reset the last-updated time to the current time. |
23324ae1 | 2096 | |
42013f4c FM |
2097 | It is assumed that update events are normally sent in idle time, so this |
2098 | is called at the end of idle processing. | |
23324ae1 | 2099 | |
42013f4c | 2100 | @see CanUpdate(), SetUpdateInterval(), SetMode() |
23324ae1 | 2101 | */ |
42013f4c | 2102 | static void ResetUpdateTime(); |
23324ae1 FM |
2103 | |
2104 | /** | |
42013f4c FM |
2105 | Specify how wxWidgets will send update events: to all windows, or only to |
2106 | those which specify that they will process the events. | |
23324ae1 | 2107 | |
42013f4c FM |
2108 | @param mode |
2109 | this parameter may be one of the ::wxUpdateUIMode enumeration values. | |
2110 | The default mode is wxUPDATE_UI_PROCESS_ALL. | |
23324ae1 | 2111 | */ |
42013f4c | 2112 | static void SetMode(wxUpdateUIMode mode); |
23324ae1 FM |
2113 | |
2114 | /** | |
42013f4c | 2115 | Sets the text for this UI element. |
23324ae1 | 2116 | */ |
42013f4c | 2117 | void SetText(const wxString& text); |
23324ae1 FM |
2118 | |
2119 | /** | |
42013f4c | 2120 | Sets the interval between updates in milliseconds. |
23324ae1 | 2121 | |
42013f4c FM |
2122 | Set to -1 to disable updates, or to 0 to update as frequently as possible. |
2123 | The default is 0. | |
23324ae1 | 2124 | |
42013f4c FM |
2125 | Use this to reduce the overhead of UI update events if your application |
2126 | has a lot of windows. If you set the value to -1 or greater than 0, | |
2127 | you may also need to call wxWindow::UpdateWindowUI at appropriate points | |
2128 | in your application, such as when a dialog is about to be shown. | |
23324ae1 | 2129 | */ |
42013f4c | 2130 | static void SetUpdateInterval(long updateInterval); |
23324ae1 FM |
2131 | |
2132 | /** | |
42013f4c | 2133 | Show or hide the UI element. |
23324ae1 | 2134 | */ |
42013f4c FM |
2135 | void Show(bool show); |
2136 | }; | |
23324ae1 FM |
2137 | |
2138 | ||
23324ae1 | 2139 | |
42013f4c FM |
2140 | /** |
2141 | @class wxClipboardTextEvent | |
23324ae1 | 2142 | |
42013f4c FM |
2143 | This class represents the events generated by a control (typically a |
2144 | wxTextCtrl but other windows can generate these events as well) when its | |
2145 | content gets copied or cut to, or pasted from the clipboard. | |
23324ae1 | 2146 | |
3a194bda SL |
2147 | There are three types of corresponding events @c wxEVT_COMMAND_TEXT_COPY, |
2148 | @c wxEVT_COMMAND_TEXT_CUT and @c wxEVT_COMMAND_TEXT_PASTE. | |
23324ae1 | 2149 | |
42013f4c FM |
2150 | If any of these events is processed (without being skipped) by an event |
2151 | handler, the corresponding operation doesn't take place which allows to | |
2152 | prevent the text from being copied from or pasted to a control. It is also | |
2153 | possible to examine the clipboard contents in the PASTE event handler and | |
2154 | transform it in some way before inserting in a control -- for example, | |
2155 | changing its case or removing invalid characters. | |
23324ae1 | 2156 | |
42013f4c FM |
2157 | Finally notice that a CUT event is always preceded by the COPY event which |
2158 | makes it possible to only process the latter if it doesn't matter if the | |
2159 | text was copied or cut. | |
23324ae1 | 2160 | |
42013f4c | 2161 | @note |
75aaa4c5 VZ |
2162 | These events are currently only generated by wxTextCtrl in wxGTK and wxOSX |
2163 | but are also generated by wxComboBox without wxCB_READONLY style in wxMSW. | |
23324ae1 | 2164 | |
42013f4c | 2165 | @beginEventTable{wxClipboardTextEvent} |
8c6791e4 | 2166 | @event{EVT_TEXT_COPY(id, func)} |
42013f4c | 2167 | Some or all of the controls content was copied to the clipboard. |
8c6791e4 | 2168 | @event{EVT_TEXT_CUT(id, func)} |
42013f4c FM |
2169 | Some or all of the controls content was cut (i.e. copied and |
2170 | deleted). | |
8c6791e4 | 2171 | @event{EVT_TEXT_PASTE(id, func)} |
42013f4c FM |
2172 | Clipboard content was pasted into the control. |
2173 | @endEventTable | |
23324ae1 | 2174 | |
23324ae1 | 2175 | |
42013f4c FM |
2176 | @library{wxcore} |
2177 | @category{events} | |
23324ae1 | 2178 | |
42013f4c FM |
2179 | @see wxClipboard |
2180 | */ | |
2181 | class wxClipboardTextEvent : public wxCommandEvent | |
2182 | { | |
2183 | public: | |
23324ae1 | 2184 | /** |
42013f4c | 2185 | Constructor. |
23324ae1 | 2186 | */ |
42013f4c | 2187 | wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
2188 | }; |
2189 | ||
41469c9e VZ |
2190 | /** |
2191 | Possible axis values for mouse wheel scroll events. | |
2192 | ||
2193 | @since 2.9.4 | |
2194 | */ | |
2195 | enum wxMouseWheelAxis | |
2196 | { | |
2197 | wxMOUSE_WHEEL_VERTICAL, ///< Vertical scroll event. | |
2198 | wxMOUSE_WHEEL_HORIZONTAL ///< Horizontal scroll event. | |
2199 | }; | |
23324ae1 | 2200 | |
e54c96f1 | 2201 | |
23324ae1 | 2202 | /** |
42013f4c | 2203 | @class wxMouseEvent |
7c913512 | 2204 | |
42013f4c FM |
2205 | This event class contains information about the events generated by the mouse: |
2206 | they include mouse buttons press and release events and mouse move events. | |
7c913512 | 2207 | |
42013f4c FM |
2208 | All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the |
2209 | left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and | |
2210 | @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more | |
2211 | buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events | |
2212 | can also be generated. Note that not all mice have even a middle button so a | |
2213 | portable application should avoid relying on the events from it (but the right | |
2214 | button click can be emulated using the left mouse button with the control key | |
2215 | under Mac platforms with a single button mouse). | |
2216 | ||
2217 | For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events | |
2218 | purposes, the mouse is considered to be inside the window if it is in the | |
2219 | window client area and not inside one of its children. In other words, the | |
2220 | parent window receives @c wxEVT_LEAVE_WINDOW event not only when the | |
2221 | mouse leaves the window entirely but also when it enters one of its children. | |
2222 | ||
92dbce73 VZ |
2223 | The position associated with a mouse event is expressed in the window |
2224 | coordinates of the window which generated the event, you can use | |
2225 | wxWindow::ClientToScreen() to convert it to screen coordinates and possibly | |
2226 | call wxWindow::ScreenToClient() next to convert it to window coordinates of | |
2227 | another window. | |
2228 | ||
42013f4c FM |
2229 | @note Note that under Windows CE mouse enter and leave events are not natively |
2230 | supported by the system but are generated by wxWidgets itself. This has several | |
2231 | drawbacks: the LEAVE_WINDOW event might be received some time after the mouse | |
2232 | left the window and the state variables for it may have changed during this time. | |
2233 | ||
2234 | @note Note the difference between methods like wxMouseEvent::LeftDown and | |
ab826fd8 VZ |
2235 | the inherited wxMouseState::LeftIsDown: the former returns @true when |
2236 | the event corresponds to the left mouse button click while the latter | |
2237 | returns @true if the left mouse button is currently being pressed. | |
2238 | For example, when the user is dragging the mouse you can use | |
2239 | wxMouseEvent::LeftIsDown to test whether the left mouse button is | |
2240 | (still) depressed. Also, by convention, if wxMouseEvent::LeftDown | |
2241 | returns @true, wxMouseEvent::LeftIsDown will also return @true in | |
2242 | wxWidgets whatever the underlying GUI behaviour is (which is | |
2243 | platform-dependent). The same applies, of course, to other mouse | |
2244 | buttons as well. | |
42013f4c FM |
2245 | |
2246 | ||
2247 | @beginEventTable{wxMouseEvent} | |
8c6791e4 | 2248 | @event{EVT_LEFT_DOWN(func)} |
3051a44a | 2249 | Process a @c wxEVT_LEFT_DOWN event. The handler of this event should normally |
42013f4c FM |
2250 | call event.Skip() to allow the default processing to take place as otherwise |
2251 | the window under mouse wouldn't get the focus. | |
8c6791e4 | 2252 | @event{EVT_LEFT_UP(func)} |
3051a44a | 2253 | Process a @c wxEVT_LEFT_UP event. |
8c6791e4 | 2254 | @event{EVT_LEFT_DCLICK(func)} |
3051a44a | 2255 | Process a @c wxEVT_LEFT_DCLICK event. |
8c6791e4 | 2256 | @event{EVT_MIDDLE_DOWN(func)} |
3051a44a | 2257 | Process a @c wxEVT_MIDDLE_DOWN event. |
8c6791e4 | 2258 | @event{EVT_MIDDLE_UP(func)} |
3051a44a | 2259 | Process a @c wxEVT_MIDDLE_UP event. |
8c6791e4 | 2260 | @event{EVT_MIDDLE_DCLICK(func)} |
3051a44a | 2261 | Process a @c wxEVT_MIDDLE_DCLICK event. |
8c6791e4 | 2262 | @event{EVT_RIGHT_DOWN(func)} |
3051a44a | 2263 | Process a @c wxEVT_RIGHT_DOWN event. |
8c6791e4 | 2264 | @event{EVT_RIGHT_UP(func)} |
3051a44a | 2265 | Process a @c wxEVT_RIGHT_UP event. |
8c6791e4 | 2266 | @event{EVT_RIGHT_DCLICK(func)} |
3051a44a | 2267 | Process a @c wxEVT_RIGHT_DCLICK event. |
8c6791e4 | 2268 | @event{EVT_MOUSE_AUX1_DOWN(func)} |
7f4f5e8c | 2269 | Process a @c wxEVT_AUX1_DOWN event. |
8c6791e4 | 2270 | @event{EVT_MOUSE_AUX1_UP(func)} |
7f4f5e8c | 2271 | Process a @c wxEVT_AUX1_UP event. |
8c6791e4 | 2272 | @event{EVT_MOUSE_AUX1_DCLICK(func)} |
7f4f5e8c | 2273 | Process a @c wxEVT_AUX1_DCLICK event. |
8c6791e4 | 2274 | @event{EVT_MOUSE_AUX2_DOWN(func)} |
7f4f5e8c | 2275 | Process a @c wxEVT_AUX2_DOWN event. |
8c6791e4 | 2276 | @event{EVT_MOUSE_AUX2_UP(func)} |
7f4f5e8c | 2277 | Process a @c wxEVT_AUX2_UP event. |
8c6791e4 | 2278 | @event{EVT_MOUSE_AUX2_DCLICK(func)} |
7f4f5e8c | 2279 | Process a @c wxEVT_AUX2_DCLICK event. |
8c6791e4 | 2280 | @event{EVT_MOTION(func)} |
3051a44a | 2281 | Process a @c wxEVT_MOTION event. |
8c6791e4 | 2282 | @event{EVT_ENTER_WINDOW(func)} |
3051a44a | 2283 | Process a @c wxEVT_ENTER_WINDOW event. |
8c6791e4 | 2284 | @event{EVT_LEAVE_WINDOW(func)} |
3051a44a | 2285 | Process a @c wxEVT_LEAVE_WINDOW event. |
8c6791e4 | 2286 | @event{EVT_MOUSEWHEEL(func)} |
3051a44a | 2287 | Process a @c wxEVT_MOUSEWHEEL event. |
8c6791e4 | 2288 | @event{EVT_MOUSE_EVENTS(func)} |
42013f4c FM |
2289 | Process all mouse events. |
2290 | @endEventTable | |
7c913512 | 2291 | |
23324ae1 FM |
2292 | @library{wxcore} |
2293 | @category{events} | |
7c913512 | 2294 | |
0e097789 | 2295 | @see wxKeyEvent |
23324ae1 | 2296 | */ |
0e097789 VZ |
2297 | class wxMouseEvent : public wxEvent, |
2298 | public wxMouseState | |
23324ae1 FM |
2299 | { |
2300 | public: | |
2301 | /** | |
42013f4c | 2302 | Constructor. Valid event types are: |
23324ae1 | 2303 | |
3a194bda SL |
2304 | @li @c wxEVT_ENTER_WINDOW |
2305 | @li @c wxEVT_LEAVE_WINDOW | |
2306 | @li @c wxEVT_LEFT_DOWN | |
2307 | @li @c wxEVT_LEFT_UP | |
2308 | @li @c wxEVT_LEFT_DCLICK | |
2309 | @li @c wxEVT_MIDDLE_DOWN | |
2310 | @li @c wxEVT_MIDDLE_UP | |
2311 | @li @c wxEVT_MIDDLE_DCLICK | |
2312 | @li @c wxEVT_RIGHT_DOWN | |
2313 | @li @c wxEVT_RIGHT_UP | |
2314 | @li @c wxEVT_RIGHT_DCLICK | |
31a9fc93 VZ |
2315 | @li @c wxEVT_AUX1_DOWN |
2316 | @li @c wxEVT_AUX1_UP | |
2317 | @li @c wxEVT_AUX1_DCLICK | |
2318 | @li @c wxEVT_AUX2_DOWN | |
2319 | @li @c wxEVT_AUX2_UP | |
2320 | @li @c wxEVT_AUX2_DCLICK | |
3a194bda SL |
2321 | @li @c wxEVT_MOTION |
2322 | @li @c wxEVT_MOUSEWHEEL | |
42013f4c FM |
2323 | */ |
2324 | wxMouseEvent(wxEventType mouseEventType = wxEVT_NULL); | |
23324ae1 | 2325 | |
23324ae1 | 2326 | /** |
42013f4c | 2327 | Returns @true if the event was a first extra button double click. |
23324ae1 | 2328 | */ |
42013f4c | 2329 | bool Aux1DClick() const; |
23324ae1 FM |
2330 | |
2331 | /** | |
42013f4c | 2332 | Returns @true if the first extra button mouse button changed to down. |
23324ae1 | 2333 | */ |
42013f4c | 2334 | bool Aux1Down() const; |
7c913512 | 2335 | |
23324ae1 | 2336 | /** |
42013f4c | 2337 | Returns @true if the first extra button mouse button changed to up. |
23324ae1 | 2338 | */ |
42013f4c | 2339 | bool Aux1Up() const; |
23324ae1 FM |
2340 | |
2341 | /** | |
42013f4c | 2342 | Returns @true if the event was a second extra button double click. |
23324ae1 | 2343 | */ |
42013f4c | 2344 | bool Aux2DClick() const; |
23324ae1 FM |
2345 | |
2346 | /** | |
42013f4c | 2347 | Returns @true if the second extra button mouse button changed to down. |
23324ae1 | 2348 | */ |
42013f4c | 2349 | bool Aux2Down() const; |
23324ae1 | 2350 | |
23324ae1 | 2351 | /** |
42013f4c | 2352 | Returns @true if the second extra button mouse button changed to up. |
23324ae1 | 2353 | */ |
42013f4c | 2354 | bool Aux2Up() const; |
23324ae1 FM |
2355 | |
2356 | /** | |
ab826fd8 | 2357 | Returns @true if the event was generated by the specified button. |
42013f4c | 2358 | |
ab826fd8 | 2359 | @see wxMouseState::ButtoinIsDown() |
23324ae1 | 2360 | */ |
ab826fd8 | 2361 | bool Button(wxMouseButton but) const; |
23324ae1 FM |
2362 | |
2363 | /** | |
42013f4c FM |
2364 | If the argument is omitted, this returns @true if the event was a mouse |
2365 | double click event. Otherwise the argument specifies which double click event | |
2366 | was generated (see Button() for the possible values). | |
23324ae1 | 2367 | */ |
ab826fd8 | 2368 | bool ButtonDClick(wxMouseButton but = wxMOUSE_BTN_ANY) const; |
23324ae1 FM |
2369 | |
2370 | /** | |
42013f4c FM |
2371 | If the argument is omitted, this returns @true if the event was a mouse |
2372 | button down event. Otherwise the argument specifies which button-down event | |
2373 | was generated (see Button() for the possible values). | |
23324ae1 | 2374 | */ |
ab826fd8 | 2375 | bool ButtonDown(wxMouseButton but = wxMOUSE_BTN_ANY) const; |
23324ae1 FM |
2376 | |
2377 | /** | |
42013f4c FM |
2378 | If the argument is omitted, this returns @true if the event was a mouse |
2379 | button up event. Otherwise the argument specifies which button-up event | |
2380 | was generated (see Button() for the possible values). | |
23324ae1 | 2381 | */ |
ab826fd8 | 2382 | bool ButtonUp(wxMouseButton but = wxMOUSE_BTN_ANY) const; |
23324ae1 | 2383 | |
23324ae1 | 2384 | /** |
42013f4c FM |
2385 | Returns @true if this was a dragging event (motion while a button is depressed). |
2386 | ||
2387 | @see Moving() | |
23324ae1 | 2388 | */ |
42013f4c | 2389 | bool Dragging() const; |
23324ae1 FM |
2390 | |
2391 | /** | |
42013f4c FM |
2392 | Returns @true if the mouse was entering the window. |
2393 | ||
2394 | @see Leaving() | |
23324ae1 | 2395 | */ |
42013f4c | 2396 | bool Entering() const; |
23324ae1 FM |
2397 | |
2398 | /** | |
42013f4c FM |
2399 | Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE |
2400 | if no button is involved (for mouse move, enter or leave event, for example). | |
2401 | Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and | |
2402 | double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT | |
2403 | for the same events for the middle and the right buttons respectively. | |
23324ae1 | 2404 | */ |
42013f4c | 2405 | int GetButton() const; |
e54c96f1 | 2406 | |
42013f4c FM |
2407 | /** |
2408 | Returns the number of mouse clicks for this event: 1 for a simple click, 2 | |
2409 | for a double-click, 3 for a triple-click and so on. | |
7c913512 | 2410 | |
42013f4c FM |
2411 | Currently this function is implemented only in wxMac and returns -1 for the |
2412 | other platforms (you can still distinguish simple clicks from double-clicks as | |
2413 | they generate different kinds of events however). | |
7c913512 | 2414 | |
1e24c2af | 2415 | @since 2.9.0 |
42013f4c FM |
2416 | */ |
2417 | int GetClickCount() const; | |
7c913512 | 2418 | |
23324ae1 | 2419 | /** |
42013f4c FM |
2420 | Returns the configured number of lines (or whatever) to be scrolled per |
2421 | wheel action. Defaults to three. | |
23324ae1 | 2422 | */ |
42013f4c | 2423 | int GetLinesPerAction() const; |
23324ae1 FM |
2424 | |
2425 | /** | |
42013f4c FM |
2426 | Returns the logical mouse position in pixels (i.e. translated according to the |
2427 | translation set for the DC, which usually indicates that the window has been | |
2428 | scrolled). | |
23324ae1 | 2429 | */ |
42013f4c | 2430 | wxPoint GetLogicalPosition(const wxDC& dc) const; |
23324ae1 | 2431 | |
42013f4c FM |
2432 | /** |
2433 | Get wheel delta, normally 120. | |
7c913512 | 2434 | |
42013f4c FM |
2435 | This is the threshold for action to be taken, and one such action |
2436 | (for example, scrolling one increment) should occur for each delta. | |
2437 | */ | |
2438 | int GetWheelDelta() const; | |
7c913512 | 2439 | |
42013f4c FM |
2440 | /** |
2441 | Get wheel rotation, positive or negative indicates direction of rotation. | |
7c913512 | 2442 | |
42013f4c FM |
2443 | Current devices all send an event when rotation is at least +/-WheelDelta, but |
2444 | finer resolution devices can be created in the future. | |
7c913512 | 2445 | |
42013f4c FM |
2446 | Because of this you shouldn't assume that one event is equal to 1 line, but you |
2447 | should be able to either do partial line scrolling or wait until several | |
2448 | events accumulate before scrolling. | |
23324ae1 | 2449 | */ |
42013f4c | 2450 | int GetWheelRotation() const; |
23324ae1 | 2451 | |
ec6278a1 | 2452 | /** |
41469c9e VZ |
2453 | Gets the axis the wheel operation concerns. |
2454 | ||
2455 | Usually the mouse wheel is used to scroll vertically so @c | |
2456 | wxMOUSE_WHEEL_VERTICAL is returned but some mice (and most trackpads) | |
2457 | also allow to use the wheel to scroll horizontally in which case | |
2458 | @c wxMOUSE_WHEEL_HORIZONTAL is returned. | |
ec6278a1 | 2459 | |
41469c9e | 2460 | Notice that before wxWidgets 2.9.4 this method returned @c int. |
ec6278a1 | 2461 | */ |
41469c9e | 2462 | wxMouseWheelAxis GetWheelAxis() const; |
ec6278a1 | 2463 | |
23324ae1 | 2464 | /** |
42013f4c FM |
2465 | Returns @true if the event was a mouse button event (not necessarily a button |
2466 | down event - that may be tested using ButtonDown()). | |
23324ae1 | 2467 | */ |
42013f4c | 2468 | bool IsButton() const; |
23324ae1 FM |
2469 | |
2470 | /** | |
42013f4c FM |
2471 | Returns @true if the system has been setup to do page scrolling with |
2472 | the mouse wheel instead of line scrolling. | |
23324ae1 | 2473 | */ |
42013f4c | 2474 | bool IsPageScroll() const; |
7c913512 | 2475 | |
42013f4c FM |
2476 | /** |
2477 | Returns @true if the mouse was leaving the window. | |
7c913512 | 2478 | |
42013f4c FM |
2479 | @see Entering(). |
2480 | */ | |
2481 | bool Leaving() const; | |
7c913512 | 2482 | |
23324ae1 | 2483 | /** |
42013f4c | 2484 | Returns @true if the event was a left double click. |
23324ae1 | 2485 | */ |
42013f4c | 2486 | bool LeftDClick() const; |
23324ae1 FM |
2487 | |
2488 | /** | |
42013f4c | 2489 | Returns @true if the left mouse button changed to down. |
23324ae1 | 2490 | */ |
42013f4c | 2491 | bool LeftDown() const; |
7c913512 | 2492 | |
42013f4c FM |
2493 | /** |
2494 | Returns @true if the left mouse button changed to up. | |
2495 | */ | |
2496 | bool LeftUp() const; | |
7c913512 | 2497 | |
23324ae1 | 2498 | /** |
42013f4c FM |
2499 | Returns @true if the Meta key was down at the time of the event. |
2500 | */ | |
2501 | bool MetaDown() const; | |
3c4f71cc | 2502 | |
42013f4c FM |
2503 | /** |
2504 | Returns @true if the event was a middle double click. | |
23324ae1 | 2505 | */ |
42013f4c | 2506 | bool MiddleDClick() const; |
23324ae1 FM |
2507 | |
2508 | /** | |
42013f4c | 2509 | Returns @true if the middle mouse button changed to down. |
23324ae1 | 2510 | */ |
42013f4c | 2511 | bool MiddleDown() const; |
23324ae1 | 2512 | |
42013f4c FM |
2513 | /** |
2514 | Returns @true if the middle mouse button changed to up. | |
2515 | */ | |
2516 | bool MiddleUp() const; | |
e54c96f1 | 2517 | |
42013f4c FM |
2518 | /** |
2519 | Returns @true if this was a motion event and no mouse buttons were pressed. | |
2520 | If any mouse button is held pressed, then this method returns @false and | |
2521 | Dragging() returns @true. | |
2522 | */ | |
2523 | bool Moving() const; | |
7c913512 | 2524 | |
42013f4c FM |
2525 | /** |
2526 | Returns @true if the event was a right double click. | |
2527 | */ | |
2528 | bool RightDClick() const; | |
7c913512 | 2529 | |
42013f4c FM |
2530 | /** |
2531 | Returns @true if the right mouse button changed to down. | |
2532 | */ | |
2533 | bool RightDown() const; | |
7c913512 | 2534 | |
42013f4c FM |
2535 | /** |
2536 | Returns @true if the right mouse button changed to up. | |
2537 | */ | |
2538 | bool RightUp() const; | |
23324ae1 FM |
2539 | }; |
2540 | ||
2541 | ||
e54c96f1 | 2542 | |
23324ae1 | 2543 | /** |
42013f4c | 2544 | @class wxDropFilesEvent |
7c913512 | 2545 | |
42013f4c FM |
2546 | This class is used for drop files events, that is, when files have been dropped |
2547 | onto the window. This functionality is currently only available under Windows. | |
7c913512 | 2548 | |
42013f4c FM |
2549 | The window must have previously been enabled for dropping by calling |
2550 | wxWindow::DragAcceptFiles(). | |
2551 | ||
2552 | Important note: this is a separate implementation to the more general drag and drop | |
2553 | implementation documented in the @ref overview_dnd. It uses the older, Windows | |
2554 | message-based approach of dropping files. | |
2555 | ||
2556 | @beginEventTable{wxDropFilesEvent} | |
8c6791e4 | 2557 | @event{EVT_DROP_FILES(func)} |
3051a44a | 2558 | Process a @c wxEVT_DROP_FILES event. |
42013f4c FM |
2559 | @endEventTable |
2560 | ||
2561 | @onlyfor{wxmsw} | |
7c913512 | 2562 | |
23324ae1 FM |
2563 | @library{wxcore} |
2564 | @category{events} | |
7c913512 | 2565 | |
3e083d65 | 2566 | @see @ref overview_events |
23324ae1 | 2567 | */ |
42013f4c | 2568 | class wxDropFilesEvent : public wxEvent |
23324ae1 FM |
2569 | { |
2570 | public: | |
2571 | /** | |
42013f4c | 2572 | Constructor. |
23324ae1 | 2573 | */ |
42013f4c FM |
2574 | wxDropFilesEvent(wxEventType id = 0, int noFiles = 0, |
2575 | wxString* files = NULL); | |
23324ae1 FM |
2576 | |
2577 | /** | |
42013f4c | 2578 | Returns an array of filenames. |
23324ae1 | 2579 | */ |
42013f4c | 2580 | wxString* GetFiles() const; |
23324ae1 FM |
2581 | |
2582 | /** | |
42013f4c | 2583 | Returns the number of files dropped. |
23324ae1 | 2584 | */ |
42013f4c | 2585 | int GetNumberOfFiles() const; |
23324ae1 FM |
2586 | |
2587 | /** | |
42013f4c FM |
2588 | Returns the position at which the files were dropped. |
2589 | Returns an array of filenames. | |
23324ae1 | 2590 | */ |
42013f4c | 2591 | wxPoint GetPosition() const; |
23324ae1 FM |
2592 | }; |
2593 | ||
2594 | ||
e54c96f1 | 2595 | |
23324ae1 | 2596 | /** |
42013f4c | 2597 | @class wxCommandEvent |
7c913512 | 2598 | |
42013f4c FM |
2599 | This event class contains information about command events, which originate |
2600 | from a variety of simple controls. | |
2601 | ||
3a567740 FM |
2602 | Note that wxCommandEvents and wxCommandEvent-derived event classes by default |
2603 | and unlike other wxEvent-derived classes propagate upward from the source | |
2604 | window (the window which emits the event) up to the first parent which processes | |
2605 | the event. Be sure to read @ref overview_events_propagation. | |
2606 | ||
42013f4c FM |
2607 | More complex controls, such as wxTreeCtrl, have separate command event classes. |
2608 | ||
2609 | @beginEventTable{wxCommandEvent} | |
8c6791e4 | 2610 | @event{EVT_COMMAND(id, event, func)} |
42013f4c FM |
2611 | Process a command, supplying the window identifier, command event identifier, |
2612 | and member function. | |
8c6791e4 | 2613 | @event{EVT_COMMAND_RANGE(id1, id2, event, func)} |
42013f4c FM |
2614 | Process a command for a range of window identifiers, supplying the minimum and |
2615 | maximum window identifiers, command event identifier, and member function. | |
8c6791e4 | 2616 | @event{EVT_BUTTON(id, func)} |
b476cde6 | 2617 | Process a @c wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control. |
8c6791e4 | 2618 | @event{EVT_CHECKBOX(id, func)} |
b476cde6 | 2619 | Process a @c wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control. |
8c6791e4 | 2620 | @event{EVT_CHOICE(id, func)} |
b476cde6 | 2621 | Process a @c wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control. |
8c6791e4 | 2622 | @event{EVT_COMBOBOX(id, func)} |
b476cde6 | 2623 | Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control. |
8c6791e4 | 2624 | @event{EVT_LISTBOX(id, func)} |
b476cde6 | 2625 | Process a @c wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control. |
8c6791e4 | 2626 | @event{EVT_LISTBOX_DCLICK(id, func)} |
b476cde6 | 2627 | Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control. |
51fbe4cc RR |
2628 | @event{EVT_CHECKLISTBOX(id, func)} |
2629 | Process a @c wxEVT_COMMAND_CHECKLISTBOX_TOGGLED command, which is generated by a wxCheckListBox control. | |
8c6791e4 | 2630 | @event{EVT_MENU(id, func)} |
b476cde6 | 2631 | Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item. |
8c6791e4 | 2632 | @event{EVT_MENU_RANGE(id1, id2, func)} |
b476cde6 | 2633 | Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items. |
8c6791e4 | 2634 | @event{EVT_CONTEXT_MENU(func)} |
42013f4c FM |
2635 | Process the event generated when the user has requested a popup menu to appear by |
2636 | pressing a special keyboard key (under Windows) or by right clicking the mouse. | |
8c6791e4 | 2637 | @event{EVT_RADIOBOX(id, func)} |
b476cde6 | 2638 | Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control. |
8c6791e4 | 2639 | @event{EVT_RADIOBUTTON(id, func)} |
b476cde6 | 2640 | Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control. |
8c6791e4 | 2641 | @event{EVT_SCROLLBAR(id, func)} |
b476cde6 | 2642 | Process a @c wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar |
42013f4c FM |
2643 | control. This is provided for compatibility only; more specific scrollbar event macros |
2644 | should be used instead (see wxScrollEvent). | |
8c6791e4 | 2645 | @event{EVT_SLIDER(id, func)} |
b476cde6 | 2646 | Process a @c wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control. |
8c6791e4 | 2647 | @event{EVT_TEXT(id, func)} |
b476cde6 | 2648 | Process a @c wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control. |
8c6791e4 | 2649 | @event{EVT_TEXT_ENTER(id, func)} |
b476cde6 | 2650 | Process a @c wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control. |
42013f4c FM |
2651 | Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it |
2652 | to generate such events. | |
8c6791e4 | 2653 | @event{EVT_TEXT_MAXLEN(id, func)} |
b476cde6 | 2654 | Process a @c wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control |
42013f4c FM |
2655 | when the user tries to enter more characters into it than the limit previously set |
2656 | with SetMaxLength(). | |
8c6791e4 | 2657 | @event{EVT_TOGGLEBUTTON(id, func)} |
b476cde6 | 2658 | Process a @c wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event. |
8c6791e4 | 2659 | @event{EVT_TOOL(id, func)} |
b476cde6 | 2660 | Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c wxEVT_COMMAND_MENU_SELECTED). |
42013f4c | 2661 | Pass the id of the tool. |
8c6791e4 | 2662 | @event{EVT_TOOL_RANGE(id1, id2, func)} |
b476cde6 | 2663 | Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools. |
8c6791e4 | 2664 | @event{EVT_TOOL_RCLICKED(id, func)} |
e431dd05 | 2665 | Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool. (Not available on wxOSX.) |
8c6791e4 | 2666 | @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)} |
e431dd05 | 2667 | Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. (Not available on wxOSX.) |
8c6791e4 | 2668 | @event{EVT_TOOL_ENTER(id, func)} |
b476cde6 | 2669 | Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself. |
42013f4c | 2670 | The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor |
e431dd05 | 2671 | has moved off a tool. (Not available on wxOSX.) |
8c6791e4 | 2672 | @event{EVT_COMMAND_LEFT_CLICK(id, func)} |
b476cde6 | 2673 | Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only). |
8c6791e4 | 2674 | @event{EVT_COMMAND_LEFT_DCLICK(id, func)} |
b476cde6 | 2675 | Process a @c wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only). |
8c6791e4 | 2676 | @event{EVT_COMMAND_RIGHT_CLICK(id, func)} |
b476cde6 | 2677 | Process a @c wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only). |
8c6791e4 | 2678 | @event{EVT_COMMAND_SET_FOCUS(id, func)} |
b476cde6 | 2679 | Process a @c wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only). |
8c6791e4 | 2680 | @event{EVT_COMMAND_KILL_FOCUS(id, func)} |
b476cde6 | 2681 | Process a @c wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only). |
8c6791e4 | 2682 | @event{EVT_COMMAND_ENTER(id, func)} |
b476cde6 | 2683 | Process a @c wxEVT_COMMAND_ENTER command, which is generated by a control. |
42013f4c | 2684 | @endEventTable |
7c913512 | 2685 | |
23324ae1 | 2686 | @library{wxcore} |
1f1d2182 | 2687 | @category{events} |
23324ae1 | 2688 | */ |
42013f4c | 2689 | class wxCommandEvent : public wxEvent |
23324ae1 FM |
2690 | { |
2691 | public: | |
2692 | /** | |
2693 | Constructor. | |
2694 | */ | |
408776d0 | 2695 | wxCommandEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
2696 | |
2697 | /** | |
42013f4c FM |
2698 | Returns client data pointer for a listbox or choice selection event |
2699 | (not valid for a deselection). | |
2700 | */ | |
2701 | void* GetClientData() const; | |
3c4f71cc | 2702 | |
42013f4c FM |
2703 | /** |
2704 | Returns client object pointer for a listbox or choice selection event | |
2705 | (not valid for a deselection). | |
2706 | */ | |
2707 | wxClientData* GetClientObject() const; | |
3c4f71cc | 2708 | |
42013f4c | 2709 | /** |
8cddee2d | 2710 | Returns extra information dependent on the event objects type. |
3c4f71cc | 2711 | |
42013f4c FM |
2712 | If the event comes from a listbox selection, it is a boolean |
2713 | determining whether the event was a selection (@true) or a | |
2714 | deselection (@false). A listbox deselection only occurs for | |
2715 | multiple-selection boxes, and in this case the index and string values | |
2716 | are indeterminate and the listbox must be examined by the application. | |
2717 | */ | |
2718 | long GetExtraLong() const; | |
3c4f71cc | 2719 | |
42013f4c FM |
2720 | /** |
2721 | Returns the integer identifier corresponding to a listbox, choice or | |
2722 | radiobox selection (only if the event was a selection, not a deselection), | |
2723 | or a boolean value representing the value of a checkbox. | |
e23e368b VZ |
2724 | |
2725 | For a menu item, this method returns -1 if the item is not checkable or | |
2726 | a boolean value (true or false) for checkable items indicating the new | |
2727 | state of the item. | |
42013f4c FM |
2728 | */ |
2729 | int GetInt() const; | |
3c4f71cc | 2730 | |
42013f4c FM |
2731 | /** |
2732 | Returns item index for a listbox or choice selection event (not valid for | |
2733 | a deselection). | |
23324ae1 | 2734 | */ |
42013f4c | 2735 | int GetSelection() const; |
23324ae1 FM |
2736 | |
2737 | /** | |
85339748 RR |
2738 | Returns item string for a listbox or choice selection event. If one |
2739 | or several items have been deselected, returns the index of the first | |
2740 | deselected item. If some items have been selected and others deselected | |
2741 | at the same time, it will return the index of the first selected item. | |
23324ae1 | 2742 | */ |
42013f4c | 2743 | wxString GetString() const; |
23324ae1 FM |
2744 | |
2745 | /** | |
42013f4c FM |
2746 | This method can be used with checkbox and menu events: for the checkboxes, the |
2747 | method returns @true for a selection event and @false for a deselection one. | |
2748 | For the menu events, this method indicates if the menu item just has become | |
2749 | checked or unchecked (and thus only makes sense for checkable menu items). | |
3c4f71cc | 2750 | |
57ab6f23 | 2751 | Notice that this method cannot be used with wxCheckListBox currently. |
23324ae1 | 2752 | */ |
42013f4c | 2753 | bool IsChecked() const; |
23324ae1 FM |
2754 | |
2755 | /** | |
85339748 RR |
2756 | For a listbox or similar event, returns @true if it is a selection, @false |
2757 | if it is a deselection. If some items have been selected and others deselected | |
2758 | at the same time, it will return @true. | |
23324ae1 | 2759 | */ |
42013f4c | 2760 | bool IsSelection() const; |
e54c96f1 | 2761 | |
42013f4c FM |
2762 | /** |
2763 | Sets the client data for this event. | |
2764 | */ | |
2765 | void SetClientData(void* clientData); | |
7c913512 | 2766 | |
42013f4c FM |
2767 | /** |
2768 | Sets the client object for this event. The client object is not owned by the | |
2769 | event object and the event object will not delete the client object in its destructor. | |
7c913512 | 2770 | |
42013f4c FM |
2771 | The client object must be owned and deleted by another object (e.g. a control) |
2772 | that has longer life time than the event object. | |
2773 | */ | |
2774 | void SetClientObject(wxClientData* clientObject); | |
7c913512 | 2775 | |
23324ae1 | 2776 | /** |
42013f4c | 2777 | Sets the @b m_extraLong member. |
23324ae1 | 2778 | */ |
42013f4c | 2779 | void SetExtraLong(long extraLong); |
23324ae1 FM |
2780 | |
2781 | /** | |
42013f4c | 2782 | Sets the @b m_commandInt member. |
23324ae1 | 2783 | */ |
42013f4c | 2784 | void SetInt(int intCommand); |
23324ae1 FM |
2785 | |
2786 | /** | |
42013f4c | 2787 | Sets the @b m_commandString member. |
23324ae1 | 2788 | */ |
42013f4c | 2789 | void SetString(const wxString& string); |
23324ae1 FM |
2790 | }; |
2791 | ||
2792 | ||
e54c96f1 | 2793 | |
23324ae1 | 2794 | /** |
42013f4c | 2795 | @class wxActivateEvent |
7c913512 | 2796 | |
42013f4c FM |
2797 | An activate event is sent when a window or application is being activated |
2798 | or deactivated. | |
7c913512 | 2799 | |
42013f4c | 2800 | @beginEventTable{wxActivateEvent} |
8c6791e4 | 2801 | @event{EVT_ACTIVATE(func)} |
3051a44a | 2802 | Process a @c wxEVT_ACTIVATE event. |
8c6791e4 | 2803 | @event{EVT_ACTIVATE_APP(func)} |
3051a44a FM |
2804 | Process a @c wxEVT_ACTIVATE_APP event. |
2805 | This event is received by the wxApp-derived instance only. | |
8c6791e4 | 2806 | @event{EVT_HIBERNATE(func)} |
42013f4c FM |
2807 | Process a hibernate event, supplying the member function. This event applies |
2808 | to wxApp only, and only on Windows SmartPhone and PocketPC. | |
2809 | It is generated when the system is low on memory; the application should free | |
2810 | up as much memory as possible, and restore full working state when it receives | |
3a194bda | 2811 | a @c wxEVT_ACTIVATE or @c wxEVT_ACTIVATE_APP event. |
42013f4c FM |
2812 | @endEventTable |
2813 | ||
42013f4c | 2814 | @library{wxcore} |
23324ae1 | 2815 | @category{events} |
7c913512 | 2816 | |
3e083d65 | 2817 | @see @ref overview_events, wxApp::IsActive |
23324ae1 | 2818 | */ |
42013f4c | 2819 | class wxActivateEvent : public wxEvent |
23324ae1 FM |
2820 | { |
2821 | public: | |
2822 | /** | |
2823 | Constructor. | |
2824 | */ | |
42013f4c FM |
2825 | wxActivateEvent(wxEventType eventType = wxEVT_NULL, bool active = true, |
2826 | int id = 0); | |
23324ae1 FM |
2827 | |
2828 | /** | |
42013f4c | 2829 | Returns @true if the application or window is being activated, @false otherwise. |
23324ae1 | 2830 | */ |
42013f4c | 2831 | bool GetActive() const; |
23324ae1 FM |
2832 | }; |
2833 | ||
2834 | ||
e54c96f1 | 2835 | |
23324ae1 | 2836 | /** |
42013f4c | 2837 | @class wxContextMenuEvent |
7c913512 | 2838 | |
42013f4c | 2839 | This class is used for context menu events, sent to give |
3051a44a | 2840 | the application a chance to show a context (popup) menu for a wxWindow. |
42013f4c FM |
2841 | |
2842 | Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this | |
2843 | means that the event originated from a keyboard context button event, and you | |
2844 | should compute a suitable position yourself, for example by calling wxGetMousePosition(). | |
2845 | ||
2846 | When a keyboard context menu button is pressed on Windows, a right-click event | |
2847 | with default position is sent first, and if this event is not processed, the | |
2848 | context menu event is sent. So if you process mouse events and you find your | |
2849 | context menu event handler is not being called, you could call wxEvent::Skip() | |
2850 | for mouse right-down events. | |
2851 | ||
2852 | @beginEventTable{wxContextMenuEvent} | |
8c6791e4 | 2853 | @event{EVT_CONTEXT_MENU(func)} |
42013f4c FM |
2854 | A right click (or other context menu command depending on platform) has been detected. |
2855 | @endEventTable | |
2856 | ||
7c913512 | 2857 | |
23324ae1 FM |
2858 | @library{wxcore} |
2859 | @category{events} | |
7c913512 | 2860 | |
3e083d65 | 2861 | @see wxCommandEvent, @ref overview_events |
23324ae1 | 2862 | */ |
42013f4c | 2863 | class wxContextMenuEvent : public wxCommandEvent |
23324ae1 FM |
2864 | { |
2865 | public: | |
2866 | /** | |
2867 | Constructor. | |
2868 | */ | |
a90e69f7 | 2869 | wxContextMenuEvent(wxEventType type = wxEVT_NULL, int id = 0, |
42013f4c FM |
2870 | const wxPoint& pos = wxDefaultPosition); |
2871 | ||
2872 | /** | |
2873 | Returns the position in screen coordinates at which the menu should be shown. | |
2874 | Use wxWindow::ScreenToClient to convert to client coordinates. | |
2875 | ||
2876 | You can also omit a position from wxWindow::PopupMenu in order to use | |
2877 | the current mouse pointer position. | |
2878 | ||
2879 | If the event originated from a keyboard event, the value returned from this | |
2880 | function will be wxDefaultPosition. | |
2881 | */ | |
2882 | const wxPoint& GetPosition() const; | |
2883 | ||
2884 | /** | |
2885 | Sets the position at which the menu should be shown. | |
2886 | */ | |
2887 | void SetPosition(const wxPoint& point); | |
23324ae1 FM |
2888 | }; |
2889 | ||
2890 | ||
e54c96f1 | 2891 | |
23324ae1 | 2892 | /** |
42013f4c | 2893 | @class wxEraseEvent |
7c913512 | 2894 | |
42013f4c | 2895 | An erase event is sent when a window's background needs to be repainted. |
7c913512 | 2896 | |
42013f4c FM |
2897 | On some platforms, such as GTK+, this event is simulated (simply generated just |
2898 | before the paint event) and may cause flicker. It is therefore recommended that | |
2899 | you set the text background colour explicitly in order to prevent flicker. | |
2900 | The default background colour under GTK+ is grey. | |
2901 | ||
2902 | To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table | |
2903 | definition. | |
2904 | ||
5fafec4d VZ |
2905 | You must use the device context returned by GetDC() to draw on, don't create |
2906 | a wxPaintDC in the event handler. | |
7c913512 | 2907 | |
42013f4c | 2908 | @beginEventTable{wxEraseEvent} |
8c6791e4 | 2909 | @event{EVT_ERASE_BACKGROUND(func)} |
3051a44a | 2910 | Process a @c wxEVT_ERASE_BACKGROUND event. |
42013f4c | 2911 | @endEventTable |
7c913512 | 2912 | |
23324ae1 FM |
2913 | @library{wxcore} |
2914 | @category{events} | |
7c913512 | 2915 | |
3e083d65 | 2916 | @see @ref overview_events |
23324ae1 | 2917 | */ |
42013f4c | 2918 | class wxEraseEvent : public wxEvent |
23324ae1 FM |
2919 | { |
2920 | public: | |
2921 | /** | |
2922 | Constructor. | |
2923 | */ | |
42013f4c FM |
2924 | wxEraseEvent(int id = 0, wxDC* dc = NULL); |
2925 | ||
2926 | /** | |
2927 | Returns the device context associated with the erase event to draw on. | |
5fafec4d VZ |
2928 | |
2929 | The returned pointer is never @NULL. | |
42013f4c FM |
2930 | */ |
2931 | wxDC* GetDC() const; | |
23324ae1 FM |
2932 | }; |
2933 | ||
2934 | ||
e54c96f1 | 2935 | |
23324ae1 | 2936 | /** |
42013f4c | 2937 | @class wxFocusEvent |
7c913512 | 2938 | |
42013f4c FM |
2939 | A focus event is sent when a window's focus changes. The window losing focus |
2940 | receives a "kill focus" event while the window gaining it gets a "set focus" one. | |
7c913512 | 2941 | |
42013f4c FM |
2942 | Notice that the set focus event happens both when the user gives focus to the |
2943 | window (whether using the mouse or keyboard) and when it is done from the | |
2944 | program itself using wxWindow::SetFocus. | |
2945 | ||
9a25f336 VZ |
2946 | The focus event handlers should almost invariably call wxEvent::Skip() on |
2947 | their event argument to allow the default handling to take place. Failure | |
2948 | to do this may result in incorrect behaviour of the native controls. Also | |
2949 | note that wxEVT_KILL_FOCUS handler must not call wxWindow::SetFocus() as | |
2950 | this, again, is not supported by all native controls. If you need to do | |
2951 | this, consider using the @ref sec_delayed_action described in wxIdleEvent | |
2952 | documentation. | |
2953 | ||
42013f4c | 2954 | @beginEventTable{wxFocusEvent} |
8c6791e4 | 2955 | @event{EVT_SET_FOCUS(func)} |
3051a44a | 2956 | Process a @c wxEVT_SET_FOCUS event. |
8c6791e4 | 2957 | @event{EVT_KILL_FOCUS(func)} |
3051a44a | 2958 | Process a @c wxEVT_KILL_FOCUS event. |
42013f4c | 2959 | @endEventTable |
7c913512 | 2960 | |
23324ae1 FM |
2961 | @library{wxcore} |
2962 | @category{events} | |
7c913512 | 2963 | |
3e083d65 | 2964 | @see @ref overview_events |
23324ae1 | 2965 | */ |
42013f4c | 2966 | class wxFocusEvent : public wxEvent |
23324ae1 FM |
2967 | { |
2968 | public: | |
23324ae1 FM |
2969 | /** |
2970 | Constructor. | |
2971 | */ | |
42013f4c | 2972 | wxFocusEvent(wxEventType eventType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
2973 | |
2974 | /** | |
42013f4c FM |
2975 | Returns the window associated with this event, that is the window which had the |
2976 | focus before for the @c wxEVT_SET_FOCUS event and the window which is | |
2977 | going to receive focus for the @c wxEVT_KILL_FOCUS one. | |
23324ae1 | 2978 | |
42013f4c | 2979 | Warning: the window pointer may be @NULL! |
23324ae1 | 2980 | */ |
42013f4c | 2981 | wxWindow *GetWindow() const; |
a90e69f7 RD |
2982 | |
2983 | void SetWindow(wxWindow *win); | |
42013f4c | 2984 | }; |
23324ae1 | 2985 | |
23324ae1 | 2986 | |
23324ae1 | 2987 | |
42013f4c FM |
2988 | /** |
2989 | @class wxChildFocusEvent | |
23324ae1 | 2990 | |
42013f4c FM |
2991 | A child focus event is sent to a (parent-)window when one of its child windows |
2992 | gains focus, so that the window could restore the focus back to its corresponding | |
2993 | child if it loses it now and regains later. | |
23324ae1 | 2994 | |
42013f4c | 2995 | Notice that child window is the direct child of the window receiving event. |
57ab6f23 | 2996 | Use wxWindow::FindFocus() to retrieve the window which is actually getting focus. |
42013f4c FM |
2997 | |
2998 | @beginEventTable{wxChildFocusEvent} | |
8c6791e4 | 2999 | @event{EVT_CHILD_FOCUS(func)} |
3051a44a | 3000 | Process a @c wxEVT_CHILD_FOCUS event. |
42013f4c FM |
3001 | @endEventTable |
3002 | ||
3003 | @library{wxcore} | |
3004 | @category{events} | |
23324ae1 | 3005 | |
3e083d65 | 3006 | @see @ref overview_events |
42013f4c FM |
3007 | */ |
3008 | class wxChildFocusEvent : public wxCommandEvent | |
3009 | { | |
3010 | public: | |
23324ae1 | 3011 | /** |
42013f4c FM |
3012 | Constructor. |
3013 | ||
3014 | @param win | |
3015 | The direct child which is (or which contains the window which is) receiving | |
3016 | the focus. | |
23324ae1 | 3017 | */ |
42013f4c | 3018 | wxChildFocusEvent(wxWindow* win = NULL); |
23324ae1 FM |
3019 | |
3020 | /** | |
42013f4c FM |
3021 | Returns the direct child which receives the focus, or a (grand-)parent of the |
3022 | control receiving the focus. | |
3023 | ||
3024 | To get the actually focused control use wxWindow::FindFocus. | |
23324ae1 | 3025 | */ |
42013f4c | 3026 | wxWindow *GetWindow() const; |
23324ae1 FM |
3027 | }; |
3028 | ||
3029 | ||
e54c96f1 | 3030 | |
23324ae1 | 3031 | /** |
42013f4c | 3032 | @class wxMouseCaptureLostEvent |
7c913512 | 3033 | |
0af4bd16 VZ |
3034 | A mouse capture lost event is sent to a window that had obtained mouse capture, |
3035 | which was subsequently lost due to an "external" event (for example, when a dialog | |
3036 | box is shown or if another application captures the mouse). | |
42013f4c | 3037 | |
0af4bd16 | 3038 | If this happens, this event is sent to all windows that are on the capture stack |
42013f4c FM |
3039 | (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is |
3040 | not sent if the capture changes because of a call to CaptureMouse or | |
3041 | ReleaseMouse. | |
3042 | ||
3043 | This event is currently emitted under Windows only. | |
3044 | ||
3045 | @beginEventTable{wxMouseCaptureLostEvent} | |
8c6791e4 | 3046 | @event{EVT_MOUSE_CAPTURE_LOST(func)} |
3051a44a | 3047 | Process a @c wxEVT_MOUSE_CAPTURE_LOST event. |
42013f4c | 3048 | @endEventTable |
7c913512 | 3049 | |
42013f4c | 3050 | @onlyfor{wxmsw} |
7c913512 | 3051 | |
23324ae1 FM |
3052 | @library{wxcore} |
3053 | @category{events} | |
7c913512 | 3054 | |
3e083d65 | 3055 | @see wxMouseCaptureChangedEvent, @ref overview_events, |
3051a44a | 3056 | wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture |
23324ae1 | 3057 | */ |
42013f4c | 3058 | class wxMouseCaptureLostEvent : public wxEvent |
23324ae1 FM |
3059 | { |
3060 | public: | |
3061 | /** | |
3062 | Constructor. | |
3063 | */ | |
42013f4c | 3064 | wxMouseCaptureLostEvent(wxWindowID windowId = 0); |
23324ae1 FM |
3065 | }; |
3066 | ||
3067 | ||
e54c96f1 | 3068 | |
a90e69f7 RD |
3069 | class wxDisplayChangedEvent : public wxEvent |
3070 | { | |
3071 | public: | |
3072 | wxDisplayChangedEvent(); | |
3073 | }; | |
3074 | ||
3075 | ||
3076 | class wxPaletteChangedEvent : public wxEvent | |
3077 | { | |
3078 | public: | |
3079 | wxPaletteChangedEvent(wxWindowID winid = 0); | |
3080 | ||
3081 | void SetChangedWindow(wxWindow* win); | |
3082 | wxWindow* GetChangedWindow() const; | |
3083 | }; | |
3084 | ||
3085 | ||
3086 | class wxQueryNewPaletteEvent : public wxEvent | |
3087 | { | |
3088 | public: | |
3089 | wxQueryNewPaletteEvent(wxWindowID winid = 0); | |
3090 | ||
3091 | void SetPaletteRealized(bool realized); | |
3092 | bool GetPaletteRealized(); | |
3093 | }; | |
3094 | ||
3095 | ||
3096 | ||
3097 | ||
23324ae1 | 3098 | /** |
42013f4c | 3099 | @class wxNotifyEvent |
7c913512 | 3100 | |
42013f4c | 3101 | This class is not used by the event handlers by itself, but is a base class |
3e97a905 | 3102 | for other event classes (such as wxBookCtrlEvent). |
7c913512 | 3103 | |
42013f4c FM |
3104 | It (or an object of a derived class) is sent when the controls state is being |
3105 | changed and allows the program to wxNotifyEvent::Veto() this change if it wants | |
3106 | to prevent it from happening. | |
7c913512 | 3107 | |
23324ae1 FM |
3108 | @library{wxcore} |
3109 | @category{events} | |
7c913512 | 3110 | |
3e97a905 | 3111 | @see wxBookCtrlEvent |
23324ae1 | 3112 | */ |
42013f4c | 3113 | class wxNotifyEvent : public wxCommandEvent |
23324ae1 FM |
3114 | { |
3115 | public: | |
3116 | /** | |
42013f4c | 3117 | Constructor (used internally by wxWidgets only). |
23324ae1 | 3118 | */ |
42013f4c | 3119 | wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
3120 | |
3121 | /** | |
42013f4c FM |
3122 | This is the opposite of Veto(): it explicitly allows the event to be processed. |
3123 | For most events it is not necessary to call this method as the events are allowed | |
3124 | anyhow but some are forbidden by default (this will be mentioned in the corresponding | |
3125 | event description). | |
23324ae1 | 3126 | */ |
42013f4c | 3127 | void Allow(); |
23324ae1 FM |
3128 | |
3129 | /** | |
42013f4c FM |
3130 | Returns @true if the change is allowed (Veto() hasn't been called) or @false |
3131 | otherwise (if it was). | |
23324ae1 | 3132 | */ |
42013f4c | 3133 | bool IsAllowed() const; |
23324ae1 FM |
3134 | |
3135 | /** | |
42013f4c | 3136 | Prevents the change announced by this event from happening. |
23324ae1 | 3137 | |
42013f4c FM |
3138 | It is in general a good idea to notify the user about the reasons for vetoing |
3139 | the change because otherwise the applications behaviour (which just refuses to | |
3140 | do what the user wants) might be quite surprising. | |
23324ae1 | 3141 | */ |
42013f4c FM |
3142 | void Veto(); |
3143 | }; | |
3144 | ||
23324ae1 | 3145 | |
d48b06bd FM |
3146 | /** |
3147 | @class wxThreadEvent | |
23324ae1 | 3148 | |
5d4a0504 VZ |
3149 | This class adds some simple functionality to wxEvent to facilitate |
3150 | inter-thread communication. | |
23324ae1 | 3151 | |
5d4a0504 VZ |
3152 | This event is not natively emitted by any control/class: it is just |
3153 | a helper class for the user. | |
3a567740 | 3154 | Its most important feature is the GetEventCategory() implementation which |
5d4a0504 | 3155 | allows thread events @b NOT to be processed by wxEventLoopBase::YieldFor calls |
3a567740 FM |
3156 | (unless the @c wxEVT_CATEGORY_THREAD is specified - which is never in wx code). |
3157 | ||
d48b06bd | 3158 | @library{wxcore} |
3c99e2fd | 3159 | @category{events,threading} |
d48b06bd | 3160 | |
dde19c21 | 3161 | @see @ref overview_thread, wxEventLoopBase::YieldFor |
c1b293bb VS |
3162 | |
3163 | @since 2.9.0 | |
d48b06bd | 3164 | */ |
c1b293bb | 3165 | class wxThreadEvent : public wxEvent |
42013f4c | 3166 | { |
d48b06bd FM |
3167 | public: |
3168 | /** | |
3169 | Constructor. | |
d48b06bd | 3170 | */ |
c1b293bb | 3171 | wxThreadEvent(wxEventType eventType = wxEVT_THREAD, int id = wxID_ANY); |
23324ae1 | 3172 | |
d48b06bd FM |
3173 | /** |
3174 | Clones this event making sure that all internal members which use | |
3175 | COW (only @c m_commandString for now; see @ref overview_refcount) | |
3176 | are unshared (see wxObject::UnShare). | |
3177 | */ | |
3178 | virtual wxEvent *Clone() const; | |
3179 | ||
3180 | /** | |
3181 | Returns @c wxEVT_CATEGORY_THREAD. | |
3182 | ||
74d60f66 | 3183 | This is important to avoid unwanted processing of thread events |
dde19c21 | 3184 | when calling wxEventLoopBase::YieldFor(). |
d48b06bd FM |
3185 | */ |
3186 | virtual wxEventCategory GetEventCategory() const; | |
dae60aee VS |
3187 | |
3188 | /** | |
3189 | Sets custom data payload. | |
3190 | ||
3191 | The @a payload argument may be of any type that wxAny can handle | |
3192 | (i.e. pretty much anything). Note that T's copy constructor must be | |
3193 | thread-safe, i.e. create a copy that doesn't share anything with | |
3194 | the original (see Clone()). | |
3195 | ||
3196 | @note This method is not available with Visual C++ 6. | |
3197 | ||
3198 | @since 2.9.1 | |
3199 | ||
3200 | @see GetPayload(), wxAny | |
3201 | */ | |
3202 | template<typename T> | |
3203 | void SetPayload(const T& payload); | |
3204 | ||
3205 | /** | |
3206 | Get custom data payload. | |
3207 | ||
3208 | Correct type is checked in debug builds. | |
3209 | ||
3210 | @note This method is not available with Visual C++ 6. | |
3211 | ||
3212 | @since 2.9.1 | |
3213 | ||
3214 | @see SetPayload(), wxAny | |
3215 | */ | |
3216 | template<typename T> | |
3217 | T GetPayload() const; | |
c1b293bb VS |
3218 | |
3219 | /** | |
3220 | Returns extra information integer value. | |
3221 | */ | |
3222 | long GetExtraLong() const; | |
3223 | ||
3224 | /** | |
3225 | Returns stored integer value. | |
3226 | */ | |
3227 | int GetInt() const; | |
3228 | ||
3229 | /** | |
3230 | Returns stored string value. | |
3231 | */ | |
3232 | wxString GetString() const; | |
3233 | ||
3234 | ||
3235 | /** | |
3236 | Sets the extra information value. | |
3237 | */ | |
3238 | void SetExtraLong(long extraLong); | |
3239 | ||
3240 | /** | |
3241 | Sets the integer value. | |
3242 | */ | |
3243 | void SetInt(int intCommand); | |
3244 | ||
3245 | /** | |
3246 | Sets the string value. | |
3247 | */ | |
3248 | void SetString(const wxString& string); | |
42013f4c | 3249 | }; |
e54c96f1 | 3250 | |
d48b06bd | 3251 | |
23324ae1 | 3252 | /** |
42013f4c | 3253 | @class wxHelpEvent |
7c913512 | 3254 | |
42013f4c FM |
3255 | A help event is sent when the user has requested context-sensitive help. |
3256 | This can either be caused by the application requesting context-sensitive help mode | |
3257 | via wxContextHelp, or (on MS Windows) by the system generating a WM_HELP message when | |
3258 | the user pressed F1 or clicked on the query button in a dialog caption. | |
7c913512 | 3259 | |
42013f4c FM |
3260 | A help event is sent to the window that the user clicked on, and is propagated |
3261 | up the window hierarchy until the event is processed or there are no more event | |
3262 | handlers. | |
3263 | ||
3264 | The application should call wxEvent::GetId to check the identity of the | |
3265 | clicked-on window, and then either show some suitable help or call wxEvent::Skip() | |
3266 | if the identifier is unrecognised. | |
3267 | ||
3268 | Calling Skip is important because it allows wxWidgets to generate further | |
3269 | events for ancestors of the clicked-on window. Otherwise it would be impossible to | |
3270 | show help for container windows, since processing would stop after the first window | |
3271 | found. | |
3272 | ||
3273 | @beginEventTable{wxHelpEvent} | |
8c6791e4 | 3274 | @event{EVT_HELP(id, func)} |
3051a44a | 3275 | Process a @c wxEVT_HELP event. |
8c6791e4 | 3276 | @event{EVT_HELP_RANGE(id1, id2, func)} |
3051a44a | 3277 | Process a @c wxEVT_HELP event for a range of ids. |
42013f4c | 3278 | @endEventTable |
7c913512 | 3279 | |
23324ae1 FM |
3280 | @library{wxcore} |
3281 | @category{events} | |
7c913512 | 3282 | |
3e083d65 | 3283 | @see wxContextHelp, wxDialog, @ref overview_events |
23324ae1 | 3284 | */ |
42013f4c | 3285 | class wxHelpEvent : public wxCommandEvent |
23324ae1 FM |
3286 | { |
3287 | public: | |
a44f3b5a FM |
3288 | /** |
3289 | Indicates how a wxHelpEvent was generated. | |
3290 | */ | |
3291 | enum Origin | |
3292 | { | |
3293 | Origin_Unknown, /**< unrecognized event source. */ | |
3294 | Origin_Keyboard, /**< event generated from F1 key press. */ | |
3295 | ||
3296 | /** event generated by wxContextHelp or from the [?] button on | |
3297 | the title bar (Windows). */ | |
3298 | Origin_HelpButton | |
3299 | }; | |
3300 | ||
23324ae1 FM |
3301 | /** |
3302 | Constructor. | |
3303 | */ | |
42013f4c FM |
3304 | wxHelpEvent(wxEventType type = wxEVT_NULL, |
3305 | wxWindowID winid = 0, | |
3306 | const wxPoint& pt = wxDefaultPosition, | |
a44f3b5a | 3307 | wxHelpEvent::Origin origin = Origin_Unknown); |
42013f4c FM |
3308 | |
3309 | /** | |
3310 | Returns the origin of the help event which is one of the ::wxHelpEventOrigin | |
3311 | values. | |
3312 | ||
3313 | The application may handle events generated using the keyboard or mouse | |
3314 | differently, e.g. by using wxGetMousePosition() for the mouse events. | |
3315 | ||
3316 | @see SetOrigin() | |
3317 | */ | |
43c48e1e | 3318 | wxHelpEvent::Origin GetOrigin() const; |
23324ae1 FM |
3319 | |
3320 | /** | |
42013f4c FM |
3321 | Returns the left-click position of the mouse, in screen coordinates. |
3322 | This allows the application to position the help appropriately. | |
23324ae1 | 3323 | */ |
42013f4c | 3324 | const wxPoint& GetPosition() const; |
23324ae1 FM |
3325 | |
3326 | /** | |
42013f4c FM |
3327 | Set the help event origin, only used internally by wxWidgets normally. |
3328 | ||
3329 | @see GetOrigin() | |
23324ae1 | 3330 | */ |
43c48e1e | 3331 | void SetOrigin(wxHelpEvent::Origin origin); |
23324ae1 FM |
3332 | |
3333 | /** | |
42013f4c | 3334 | Sets the left-click position of the mouse, in screen coordinates. |
23324ae1 | 3335 | */ |
42013f4c | 3336 | void SetPosition(const wxPoint& pt); |
23324ae1 FM |
3337 | }; |
3338 | ||
3339 | ||
e54c96f1 | 3340 | |
23324ae1 | 3341 | /** |
42013f4c | 3342 | @class wxScrollEvent |
7c913512 | 3343 | |
42013f4c FM |
3344 | A scroll event holds information about events sent from stand-alone |
3345 | scrollbars (see wxScrollBar) and sliders (see wxSlider). | |
7c913512 | 3346 | |
42013f4c FM |
3347 | Note that scrolled windows send the wxScrollWinEvent which does not derive from |
3348 | wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of | |
3349 | events and use the event table macros mentioned below only for the scrollbar-like | |
3350 | controls. | |
7c913512 | 3351 | |
3a74a290 | 3352 | @section scrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED |
7c913512 | 3353 | |
42013f4c FM |
3354 | The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb |
3355 | using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed | |
3356 | by an EVT_SCROLL_CHANGED event). | |
7c913512 | 3357 | |
42013f4c FM |
3358 | The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change the thumb |
3359 | position, and when clicking next to the thumb (In all these cases the EVT_SCROLL_THUMBRELEASE | |
3360 | event does not happen). | |
7c913512 | 3361 | |
42013f4c FM |
3362 | In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving has finished |
3363 | independently of the way it had started. Please see the widgets sample ("Slider" page) | |
3364 | to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action. | |
3365 | ||
3366 | @remarks | |
3367 | Note that unless specifying a scroll control identifier, you will need to test for scrollbar | |
3368 | orientation with wxScrollEvent::GetOrientation, since horizontal and vertical scroll events | |
3369 | are processed using the same event handler. | |
3370 | ||
3371 | @beginEventTable{wxScrollEvent} | |
3372 | You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting | |
3373 | scroll events from controls, or EVT_SCROLL... macros without window IDs for | |
3374 | intercepting scroll events from the receiving window -- except for this, the | |
3375 | macros behave exactly the same. | |
8c6791e4 | 3376 | @event{EVT_SCROLL(func)} |
42013f4c | 3377 | Process all scroll events. |
8c6791e4 | 3378 | @event{EVT_SCROLL_TOP(func)} |
3a194bda | 3379 | Process @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position). |
8c6791e4 | 3380 | @event{EVT_SCROLL_BOTTOM(func)} |
3a194bda | 3381 | Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). |
8c6791e4 | 3382 | @event{EVT_SCROLL_LINEUP(func)} |
3a194bda | 3383 | Process @c wxEVT_SCROLL_LINEUP line up events. |
8c6791e4 | 3384 | @event{EVT_SCROLL_LINEDOWN(func)} |
3a194bda | 3385 | Process @c wxEVT_SCROLL_LINEDOWN line down events. |
8c6791e4 | 3386 | @event{EVT_SCROLL_PAGEUP(func)} |
3a194bda | 3387 | Process @c wxEVT_SCROLL_PAGEUP page up events. |
8c6791e4 | 3388 | @event{EVT_SCROLL_PAGEDOWN(func)} |
3a194bda | 3389 | Process @c wxEVT_SCROLL_PAGEDOWN page down events. |
8c6791e4 | 3390 | @event{EVT_SCROLL_THUMBTRACK(func)} |
3a194bda | 3391 | Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent as the |
42013f4c | 3392 | user drags the thumbtrack). |
8c6791e4 | 3393 | @event{EVT_SCROLL_THUMBRELEASE(func)} |
3a194bda | 3394 | Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events. |
8c6791e4 | 3395 | @event{EVT_SCROLL_CHANGED(func)} |
3a194bda | 3396 | Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). |
8c6791e4 | 3397 | @event{EVT_COMMAND_SCROLL(id, func)} |
42013f4c | 3398 | Process all scroll events. |
8c6791e4 | 3399 | @event{EVT_COMMAND_SCROLL_TOP(id, func)} |
3a194bda | 3400 | Process @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position). |
8c6791e4 | 3401 | @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)} |
3a194bda | 3402 | Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). |
8c6791e4 | 3403 | @event{EVT_COMMAND_SCROLL_LINEUP(id, func)} |
3a194bda | 3404 | Process @c wxEVT_SCROLL_LINEUP line up events. |
8c6791e4 | 3405 | @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)} |
3a194bda | 3406 | Process @c wxEVT_SCROLL_LINEDOWN line down events. |
8c6791e4 | 3407 | @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)} |
3a194bda | 3408 | Process @c wxEVT_SCROLL_PAGEUP page up events. |
8c6791e4 | 3409 | @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)} |
3a194bda | 3410 | Process @c wxEVT_SCROLL_PAGEDOWN page down events. |
8c6791e4 | 3411 | @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)} |
3a194bda | 3412 | Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent |
42013f4c | 3413 | as the user drags the thumbtrack). |
8c6791e4 | 3414 | @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)} |
3a194bda | 3415 | Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events. |
8c6791e4 | 3416 | @event{EVT_COMMAND_SCROLL_CHANGED(func)} |
3a194bda | 3417 | Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). |
42013f4c | 3418 | @endEventTable |
7c913512 | 3419 | |
23324ae1 | 3420 | @library{wxcore} |
1f1d2182 | 3421 | @category{events} |
7c913512 | 3422 | |
3e083d65 | 3423 | @see wxScrollBar, wxSlider, wxSpinButton, wxScrollWinEvent, @ref overview_events |
23324ae1 | 3424 | */ |
42013f4c | 3425 | class wxScrollEvent : public wxCommandEvent |
23324ae1 FM |
3426 | { |
3427 | public: | |
3428 | /** | |
42013f4c | 3429 | Constructor. |
23324ae1 | 3430 | */ |
42013f4c FM |
3431 | wxScrollEvent(wxEventType commandType = wxEVT_NULL, int id = 0, int pos = 0, |
3432 | int orientation = 0); | |
23324ae1 FM |
3433 | |
3434 | /** | |
42013f4c FM |
3435 | Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the |
3436 | scrollbar. | |
23324ae1 | 3437 | */ |
42013f4c | 3438 | int GetOrientation() const; |
23324ae1 FM |
3439 | |
3440 | /** | |
42013f4c | 3441 | Returns the position of the scrollbar. |
23324ae1 | 3442 | */ |
42013f4c | 3443 | int GetPosition() const; |
a90e69f7 RD |
3444 | |
3445 | ||
3446 | void SetOrientation(int orient); | |
3447 | void SetPosition(int pos); | |
23324ae1 FM |
3448 | }; |
3449 | ||
42013f4c FM |
3450 | /** |
3451 | See wxIdleEvent::SetMode() for more info. | |
3452 | */ | |
3453 | enum wxIdleMode | |
3454 | { | |
3455 | /** Send idle events to all windows */ | |
3456 | wxIDLE_PROCESS_ALL, | |
3457 | ||
3458 | /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */ | |
3459 | wxIDLE_PROCESS_SPECIFIED | |
3460 | }; | |
23324ae1 | 3461 | |
e54c96f1 | 3462 | |
23324ae1 | 3463 | /** |
42013f4c | 3464 | @class wxIdleEvent |
7c913512 | 3465 | |
42013f4c FM |
3466 | This class is used for idle events, which are generated when the system becomes |
3467 | idle. Note that, unless you do something specifically, the idle events are not | |
3468 | sent if the system remains idle once it has become it, e.g. only a single idle | |
3469 | event will be generated until something else resulting in more normal events | |
3470 | happens and only then is the next idle event sent again. | |
3471 | ||
3472 | If you need to ensure a continuous stream of idle events, you can either use | |
3473 | wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically | |
3474 | (for example from a timer event handler), but note that both of these approaches | |
3475 | (and especially the first one) increase the system load and so should be avoided | |
3476 | if possible. | |
3477 | ||
06bfd045 VZ |
3478 | By default, idle events are sent to all windows, including even the hidden |
3479 | ones because they may be shown if some condition is met from their @c | |
3480 | wxEVT_IDLE (or related @c wxEVT_UPDATE_UI) handler. The children of hidden | |
3481 | windows do not receive idle events however as they can't change their state | |
3482 | in any way noticeable by the user. Finally, the global wxApp object also | |
3483 | receives these events, as usual, so it can be used for any global idle time | |
3484 | processing. | |
3485 | ||
3486 | If sending idle events to all windows is causing a significant overhead in | |
3487 | your application, you can call wxIdleEvent::SetMode with the value | |
3488 | wxIDLE_PROCESS_SPECIFIED, and set the wxWS_EX_PROCESS_IDLE extra window | |
3489 | style for every window which should receive idle events, all the other ones | |
3490 | will not receive them in this case. | |
42013f4c FM |
3491 | |
3492 | @beginEventTable{wxIdleEvent} | |
8c6791e4 | 3493 | @event{EVT_IDLE(func)} |
3051a44a | 3494 | Process a @c wxEVT_IDLE event. |
42013f4c | 3495 | @endEventTable |
7c913512 | 3496 | |
23324ae1 | 3497 | @library{wxbase} |
1f1d2182 | 3498 | @category{events} |
7c913512 | 3499 | |
9a25f336 VZ |
3500 | @section sec_delayed_action Delayed Action Mechanism |
3501 | ||
3502 | wxIdleEvent can be used to perform some action "at slightly later time". | |
3503 | This can be necessary in several circumstances when, for whatever reason, | |
3504 | something can't be done in the current event handler. For example, if a | |
3505 | mouse event handler is called with the mouse button pressed, the mouse can | |
3506 | be currently captured and some operations with it -- notably capturing it | |
3507 | again -- might be impossible or lead to undesirable results. If you still | |
3508 | want to capture it, you can do it from @c wxEVT_IDLE handler when it is | |
3509 | called the next time instead of doing it immediately. | |
3510 | ||
3511 | This can be achieved in two different ways: when using static event tables, | |
3512 | you will need a flag indicating to the (always connected) idle event | |
3513 | handler whether the desired action should be performed. The originally | |
3514 | called handler would then set it to indicate that it should indeed be done | |
3515 | and the idle handler itself would reset it to prevent it from doing the | |
3516 | same action again. | |
3517 | ||
3518 | Using dynamically connected event handlers things are even simpler as the | |
3519 | original event handler can simply wxEvtHandler::Connect() or | |
3520 | wxEvtHandler::Bind() the idle event handler which would only be executed | |
3521 | then and could wxEvtHandler::Disconnect() or wxEvtHandler::Unbind() itself. | |
3522 | ||
3523 | ||
3e083d65 | 3524 | @see @ref overview_events, wxUpdateUIEvent, wxWindow::OnInternalIdle |
23324ae1 | 3525 | */ |
42013f4c | 3526 | class wxIdleEvent : public wxEvent |
23324ae1 FM |
3527 | { |
3528 | public: | |
3529 | /** | |
3530 | Constructor. | |
3531 | */ | |
42013f4c | 3532 | wxIdleEvent(); |
23324ae1 | 3533 | |
23324ae1 | 3534 | /** |
42013f4c FM |
3535 | Static function returning a value specifying how wxWidgets will send idle |
3536 | events: to all windows, or only to those which specify that they | |
3537 | will process the events. | |
3c4f71cc | 3538 | |
42013f4c | 3539 | @see SetMode(). |
23324ae1 | 3540 | */ |
42013f4c | 3541 | static wxIdleMode GetMode(); |
23324ae1 | 3542 | |
23324ae1 | 3543 | /** |
42013f4c FM |
3544 | Returns @true if the OnIdle function processing this event requested more |
3545 | processing time. | |
3c4f71cc | 3546 | |
42013f4c | 3547 | @see RequestMore() |
23324ae1 | 3548 | */ |
42013f4c | 3549 | bool MoreRequested() const; |
23324ae1 FM |
3550 | |
3551 | /** | |
42013f4c | 3552 | Tells wxWidgets that more processing is required. |
3c4f71cc | 3553 | |
42013f4c FM |
3554 | This function can be called by an OnIdle handler for a window or window event |
3555 | handler to indicate that wxApp::OnIdle should forward the OnIdle event once | |
3556 | more to the application windows. | |
3c4f71cc | 3557 | |
42013f4c FM |
3558 | If no window calls this function during OnIdle, then the application will |
3559 | remain in a passive event loop (not calling OnIdle) until a new event is | |
3560 | posted to the application by the windowing system. | |
3561 | ||
3562 | @see MoreRequested() | |
23324ae1 | 3563 | */ |
42013f4c | 3564 | void RequestMore(bool needMore = true); |
23324ae1 FM |
3565 | |
3566 | /** | |
42013f4c FM |
3567 | Static function for specifying how wxWidgets will send idle events: to |
3568 | all windows, or only to those which specify that they will process the events. | |
3c4f71cc | 3569 | |
42013f4c FM |
3570 | @param mode |
3571 | Can be one of the ::wxIdleMode values. | |
3572 | The default is wxIDLE_PROCESS_ALL. | |
23324ae1 | 3573 | */ |
42013f4c FM |
3574 | static void SetMode(wxIdleMode mode); |
3575 | }; | |
23324ae1 | 3576 | |
3c4f71cc | 3577 | |
23324ae1 | 3578 | |
42013f4c FM |
3579 | /** |
3580 | @class wxInitDialogEvent | |
3c4f71cc | 3581 | |
42013f4c FM |
3582 | A wxInitDialogEvent is sent as a dialog or panel is being initialised. |
3583 | Handlers for this event can transfer data to the window. | |
23324ae1 | 3584 | |
42013f4c | 3585 | The default handler calls wxWindow::TransferDataToWindow. |
3c4f71cc | 3586 | |
42013f4c | 3587 | @beginEventTable{wxInitDialogEvent} |
8c6791e4 | 3588 | @event{EVT_INIT_DIALOG(func)} |
3051a44a | 3589 | Process a @c wxEVT_INIT_DIALOG event. |
42013f4c FM |
3590 | @endEventTable |
3591 | ||
3592 | @library{wxcore} | |
3593 | @category{events} | |
23324ae1 | 3594 | |
3e083d65 | 3595 | @see @ref overview_events |
42013f4c FM |
3596 | */ |
3597 | class wxInitDialogEvent : public wxEvent | |
3598 | { | |
3599 | public: | |
23324ae1 | 3600 | /** |
42013f4c FM |
3601 | Constructor. |
3602 | */ | |
3603 | wxInitDialogEvent(int id = 0); | |
3604 | }; | |
3c4f71cc | 3605 | |
3c4f71cc | 3606 | |
3c4f71cc | 3607 | |
42013f4c FM |
3608 | /** |
3609 | @class wxWindowDestroyEvent | |
3c4f71cc | 3610 | |
a79a6671 VZ |
3611 | This event is sent as early as possible during the window destruction |
3612 | process. | |
3613 | ||
3614 | For the top level windows, as early as possible means that this is done by | |
3615 | wxFrame or wxDialog destructor, i.e. after the destructor of the derived | |
3616 | class was executed and so any methods specific to the derived class can't | |
3617 | be called any more from this event handler. If you need to do this, you | |
3618 | must call wxWindow::SendDestroyEvent() from your derived class destructor. | |
23324ae1 | 3619 | |
a79a6671 VZ |
3620 | For the child windows, this event is generated just before deleting the |
3621 | window from wxWindow::Destroy() (which is also called when the parent | |
3622 | window is deleted) or from the window destructor if operator @c delete was | |
3623 | used directly (which is not recommended for this very reason). | |
3c4f71cc | 3624 | |
a79a6671 VZ |
3625 | It is usually pointless to handle this event in the window itself but it ca |
3626 | be very useful to receive notifications about the window destruction in the | |
3627 | parent window or in any other object interested in this window. | |
3c4f71cc | 3628 | |
42013f4c FM |
3629 | @library{wxcore} |
3630 | @category{events} | |
3c4f71cc | 3631 | |
3e083d65 | 3632 | @see @ref overview_events, wxWindowCreateEvent |
42013f4c FM |
3633 | */ |
3634 | class wxWindowDestroyEvent : public wxCommandEvent | |
3635 | { | |
3636 | public: | |
3637 | /** | |
3638 | Constructor. | |
23324ae1 | 3639 | */ |
42013f4c | 3640 | wxWindowDestroyEvent(wxWindow* win = NULL); |
a79a6671 | 3641 | |
57ab6f23 | 3642 | /// Return the window being destroyed. |
a79a6671 | 3643 | wxWindow *GetWindow() const; |
42013f4c | 3644 | }; |
23324ae1 | 3645 | |
3c4f71cc | 3646 | |
42013f4c FM |
3647 | /** |
3648 | @class wxNavigationKeyEvent | |
3c4f71cc | 3649 | |
42013f4c FM |
3650 | This event class contains information about navigation events, |
3651 | generated by navigation keys such as tab and page down. | |
23324ae1 | 3652 | |
42013f4c FM |
3653 | This event is mainly used by wxWidgets implementations. |
3654 | A wxNavigationKeyEvent handler is automatically provided by wxWidgets | |
90230407 VZ |
3655 | when you enable keyboard navigation inside a window by inheriting it from |
3656 | wxNavigationEnabled<>. | |
3c4f71cc | 3657 | |
42013f4c | 3658 | @beginEventTable{wxNavigationKeyEvent} |
8c6791e4 | 3659 | @event{EVT_NAVIGATION_KEY(func)} |
42013f4c FM |
3660 | Process a navigation key event. |
3661 | @endEventTable | |
3c4f71cc | 3662 | |
42013f4c FM |
3663 | @library{wxcore} |
3664 | @category{events} | |
3c4f71cc | 3665 | |
42013f4c FM |
3666 | @see wxWindow::Navigate, wxWindow::NavigateIn |
3667 | */ | |
3668 | class wxNavigationKeyEvent : public wxEvent | |
3669 | { | |
3670 | public: | |
3051a44a FM |
3671 | /** |
3672 | Flags which can be used with wxNavigationKeyEvent. | |
3673 | */ | |
3674 | enum wxNavigationKeyEventFlags | |
3675 | { | |
3676 | IsBackward = 0x0000, | |
3677 | IsForward = 0x0001, | |
3678 | WinChange = 0x0002, | |
3679 | FromTab = 0x0004 | |
3680 | }; | |
3681 | ||
42013f4c FM |
3682 | wxNavigationKeyEvent(); |
3683 | wxNavigationKeyEvent(const wxNavigationKeyEvent& event); | |
23324ae1 FM |
3684 | |
3685 | /** | |
42013f4c | 3686 | Returns the child that has the focus, or @NULL. |
23324ae1 | 3687 | */ |
42013f4c | 3688 | wxWindow* GetCurrentFocus() const; |
23324ae1 FM |
3689 | |
3690 | /** | |
42013f4c FM |
3691 | Returns @true if the navigation was in the forward direction. |
3692 | */ | |
3693 | bool GetDirection() const; | |
3c4f71cc | 3694 | |
42013f4c FM |
3695 | /** |
3696 | Returns @true if the navigation event was from a tab key. | |
3697 | This is required for proper navigation over radio buttons. | |
3698 | */ | |
3699 | bool IsFromTab() const; | |
3c4f71cc | 3700 | |
42013f4c FM |
3701 | /** |
3702 | Returns @true if the navigation event represents a window change | |
3703 | (for example, from Ctrl-Page Down in a notebook). | |
23324ae1 | 3704 | */ |
42013f4c | 3705 | bool IsWindowChange() const; |
23324ae1 FM |
3706 | |
3707 | /** | |
42013f4c FM |
3708 | Sets the current focus window member. |
3709 | */ | |
3710 | void SetCurrentFocus(wxWindow* currentFocus); | |
3c4f71cc | 3711 | |
42013f4c FM |
3712 | /** |
3713 | Sets the direction to forward if @a direction is @true, or backward | |
3714 | if @false. | |
3715 | */ | |
3716 | void SetDirection(bool direction); | |
3c4f71cc | 3717 | |
42013f4c FM |
3718 | /** |
3719 | Sets the flags for this event. | |
3720 | The @a flags can be a combination of the ::wxNavigationKeyEventFlags values. | |
23324ae1 | 3721 | */ |
42013f4c | 3722 | void SetFlags(long flags); |
23324ae1 FM |
3723 | |
3724 | /** | |
42013f4c FM |
3725 | Marks the navigation event as from a tab key. |
3726 | */ | |
3727 | void SetFromTab(bool fromTab); | |
3c4f71cc | 3728 | |
42013f4c FM |
3729 | /** |
3730 | Marks the event as a window change event. | |
23324ae1 | 3731 | */ |
42013f4c | 3732 | void SetWindowChange(bool windowChange); |
23324ae1 FM |
3733 | }; |
3734 | ||
3735 | ||
e54c96f1 | 3736 | |
23324ae1 | 3737 | /** |
42013f4c | 3738 | @class wxMouseCaptureChangedEvent |
7c913512 | 3739 | |
42013f4c | 3740 | An mouse capture changed event is sent to a window that loses its |
3051a44a | 3741 | mouse capture. This is called even if wxWindow::ReleaseMouse |
42013f4c FM |
3742 | was called by the application code. Handling this event allows |
3743 | an application to cater for unexpected capture releases which | |
3744 | might otherwise confuse mouse handling code. | |
7c913512 | 3745 | |
42013f4c FM |
3746 | @onlyfor{wxmsw} |
3747 | ||
3748 | @beginEventTable{wxMouseCaptureChangedEvent} | |
8c6791e4 | 3749 | @event{EVT_MOUSE_CAPTURE_CHANGED(func)} |
3051a44a | 3750 | Process a @c wxEVT_MOUSE_CAPTURE_CHANGED event. |
42013f4c | 3751 | @endEventTable |
7c913512 | 3752 | |
23324ae1 FM |
3753 | @library{wxcore} |
3754 | @category{events} | |
7c913512 | 3755 | |
3e083d65 | 3756 | @see wxMouseCaptureLostEvent, @ref overview_events, |
3051a44a | 3757 | wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture |
23324ae1 | 3758 | */ |
42013f4c | 3759 | class wxMouseCaptureChangedEvent : public wxEvent |
23324ae1 FM |
3760 | { |
3761 | public: | |
3762 | /** | |
3763 | Constructor. | |
3764 | */ | |
42013f4c FM |
3765 | wxMouseCaptureChangedEvent(wxWindowID windowId = 0, |
3766 | wxWindow* gainedCapture = NULL); | |
23324ae1 FM |
3767 | |
3768 | /** | |
42013f4c FM |
3769 | Returns the window that gained the capture, or @NULL if it was a |
3770 | non-wxWidgets window. | |
23324ae1 | 3771 | */ |
42013f4c | 3772 | wxWindow* GetCapturedWindow() const; |
23324ae1 FM |
3773 | }; |
3774 | ||
3775 | ||
e54c96f1 | 3776 | |
23324ae1 | 3777 | /** |
42013f4c | 3778 | @class wxCloseEvent |
7c913512 | 3779 | |
42013f4c FM |
3780 | This event class contains information about window and session close events. |
3781 | ||
3782 | The handler function for EVT_CLOSE is called when the user has tried to close a | |
3783 | a frame or dialog box using the window manager (X) or system menu (Windows). | |
3784 | It can also be invoked by the application itself programmatically, for example by | |
3785 | calling the wxWindow::Close function. | |
3786 | ||
3787 | You should check whether the application is forcing the deletion of the window | |
3788 | using wxCloseEvent::CanVeto. If this is @false, you @e must destroy the window | |
3789 | using wxWindow::Destroy. | |
3790 | ||
3791 | If the return value is @true, it is up to you whether you respond by destroying | |
3792 | the window. | |
3793 | ||
3794 | If you don't destroy the window, you should call wxCloseEvent::Veto to | |
3795 | let the calling code know that you did not destroy the window. | |
3796 | This allows the wxWindow::Close function to return @true or @false depending | |
3797 | on whether the close instruction was honoured or not. | |
3798 | ||
195be56d FM |
3799 | Example of a wxCloseEvent handler: |
3800 | ||
3801 | @code | |
3802 | void MyFrame::OnClose(wxCloseEvent& event) | |
3803 | { | |
3804 | if ( event.CanVeto() && m_bFileNotSaved ) | |
3805 | { | |
3806 | if ( wxMessageBox("The file has not been saved... continue closing?", | |
3807 | "Please confirm", | |
3808 | wxICON_QUESTION | wxYES_NO) != wxYES ) | |
3809 | { | |
3810 | event.Veto(); | |
3811 | return; | |
3812 | } | |
3813 | } | |
3814 | ||
3815 | Destroy(); // you may also do: event.Skip(); | |
3816 | // since the default event handler does call Destroy(), too | |
3817 | } | |
3818 | @endcode | |
3819 | ||
9fb99466 VZ |
3820 | The EVT_END_SESSION event is slightly different as it is sent by the system |
3821 | when the user session is ending (e.g. because of log out or shutdown) and | |
3822 | so all windows are being forcefully closed. At least under MSW, after the | |
3823 | handler for this event is executed the program is simply killed by the | |
3824 | system. Because of this, the default handler for this event provided by | |
3825 | wxWidgets calls all the usual cleanup code (including wxApp::OnExit()) so | |
3826 | that it could still be executed and exit()s the process itself, without | |
3827 | waiting for being killed. If this behaviour is for some reason undesirable, | |
3828 | make sure that you define a handler for this event in your wxApp-derived | |
3829 | class and do not call @c event.Skip() in it (but be aware that the system | |
3830 | will still kill your application). | |
3831 | ||
42013f4c | 3832 | @beginEventTable{wxCloseEvent} |
8c6791e4 | 3833 | @event{EVT_CLOSE(func)} |
869aa92d | 3834 | Process a @c wxEVT_CLOSE_WINDOW command event, supplying the member function. |
42013f4c | 3835 | This event applies to wxFrame and wxDialog classes. |
8c6791e4 | 3836 | @event{EVT_QUERY_END_SESSION(func)} |
869aa92d | 3837 | Process a @c wxEVT_QUERY_END_SESSION session event, supplying the member function. |
9fb99466 | 3838 | This event can be handled in wxApp-derived class only. |
8c6791e4 | 3839 | @event{EVT_END_SESSION(func)} |
869aa92d | 3840 | Process a @c wxEVT_END_SESSION session event, supplying the member function. |
9fb99466 | 3841 | This event can be handled in wxApp-derived class only. |
42013f4c | 3842 | @endEventTable |
7c913512 | 3843 | |
23324ae1 FM |
3844 | @library{wxcore} |
3845 | @category{events} | |
7c913512 | 3846 | |
42013f4c | 3847 | @see wxWindow::Close, @ref overview_windowdeletion |
23324ae1 | 3848 | */ |
42013f4c | 3849 | class wxCloseEvent : public wxEvent |
23324ae1 FM |
3850 | { |
3851 | public: | |
3852 | /** | |
3853 | Constructor. | |
3854 | */ | |
42013f4c | 3855 | wxCloseEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
3856 | |
3857 | /** | |
42013f4c FM |
3858 | Returns @true if you can veto a system shutdown or a window close event. |
3859 | Vetoing a window close event is not possible if the calling code wishes to | |
3860 | force the application to exit, and so this function must be called to check this. | |
23324ae1 | 3861 | */ |
42013f4c FM |
3862 | bool CanVeto() const; |
3863 | ||
3864 | /** | |
3865 | Returns @true if the user is just logging off or @false if the system is | |
3866 | shutting down. This method can only be called for end session and query end | |
3867 | session events, it doesn't make sense for close window event. | |
3868 | */ | |
3869 | bool GetLoggingOff() const; | |
3870 | ||
3871 | /** | |
3872 | Sets the 'can veto' flag. | |
3873 | */ | |
3874 | void SetCanVeto(bool canVeto); | |
3875 | ||
42013f4c FM |
3876 | /** |
3877 | Sets the 'logging off' flag. | |
3878 | */ | |
3879 | void SetLoggingOff(bool loggingOff); | |
3880 | ||
3881 | /** | |
3882 | Call this from your event handler to veto a system shutdown or to signal | |
3883 | to the calling application that a window close did not happen. | |
3884 | ||
3885 | You can only veto a shutdown if CanVeto() returns @true. | |
3886 | */ | |
3887 | void Veto(bool veto = true); | |
23324ae1 FM |
3888 | }; |
3889 | ||
3890 | ||
e54c96f1 | 3891 | |
23324ae1 | 3892 | /** |
42013f4c | 3893 | @class wxMenuEvent |
7c913512 | 3894 | |
42013f4c FM |
3895 | This class is used for a variety of menu-related events. Note that |
3896 | these do not include menu command events, which are | |
3897 | handled using wxCommandEvent objects. | |
7c913512 | 3898 | |
b476cde6 | 3899 | The default handler for @c wxEVT_MENU_HIGHLIGHT displays help |
42013f4c | 3900 | text in the first field of the status bar. |
7c913512 | 3901 | |
42013f4c | 3902 | @beginEventTable{wxMenuEvent} |
8c6791e4 | 3903 | @event{EVT_MENU_OPEN(func)} |
42013f4c FM |
3904 | A menu is about to be opened. On Windows, this is only sent once for each |
3905 | navigation of the menubar (up until all menus have closed). | |
8c6791e4 | 3906 | @event{EVT_MENU_CLOSE(func)} |
42013f4c | 3907 | A menu has been just closed. |
8c6791e4 | 3908 | @event{EVT_MENU_HIGHLIGHT(id, func)} |
42013f4c FM |
3909 | The menu item with the specified id has been highlighted: used to show |
3910 | help prompts in the status bar by wxFrame | |
8c6791e4 | 3911 | @event{EVT_MENU_HIGHLIGHT_ALL(func)} |
42013f4c FM |
3912 | A menu item has been highlighted, i.e. the currently selected menu item has changed. |
3913 | @endEventTable | |
7c913512 | 3914 | |
42013f4c | 3915 | @library{wxcore} |
23324ae1 | 3916 | @category{events} |
7c913512 | 3917 | |
3e083d65 | 3918 | @see wxCommandEvent, @ref overview_events |
23324ae1 | 3919 | */ |
42013f4c | 3920 | class wxMenuEvent : public wxEvent |
23324ae1 FM |
3921 | { |
3922 | public: | |
3923 | /** | |
42013f4c | 3924 | Constructor. |
23324ae1 | 3925 | */ |
a90e69f7 | 3926 | wxMenuEvent(wxEventType type = wxEVT_NULL, int id = 0, wxMenu* menu = NULL); |
23324ae1 FM |
3927 | |
3928 | /** | |
7f3f059a VZ |
3929 | Returns the menu which is being opened or closed. |
3930 | ||
3931 | This method can only be used with the @c OPEN and @c CLOSE events. | |
3932 | ||
3933 | The returned value is never @NULL in the ports implementing this | |
3934 | function, which currently includes all the major ones. | |
23324ae1 | 3935 | */ |
42013f4c | 3936 | wxMenu* GetMenu() const; |
23324ae1 FM |
3937 | |
3938 | /** | |
42013f4c FM |
3939 | Returns the menu identifier associated with the event. |
3940 | This method should be only used with the @c HIGHLIGHT events. | |
23324ae1 | 3941 | */ |
42013f4c | 3942 | int GetMenuId() const; |
23324ae1 FM |
3943 | |
3944 | /** | |
42013f4c FM |
3945 | Returns @true if the menu which is being opened or closed is a popup menu, |
3946 | @false if it is a normal one. | |
23324ae1 | 3947 | |
42013f4c | 3948 | This method should only be used with the @c OPEN and @c CLOSE events. |
23324ae1 | 3949 | */ |
42013f4c FM |
3950 | bool IsPopup() const; |
3951 | }; | |
23324ae1 | 3952 | |
d317fdeb VZ |
3953 | /** |
3954 | @class wxShowEvent | |
d317fdeb VZ |
3955 | |
3956 | An event being sent when the window is shown or hidden. | |
a183ec70 VZ |
3957 | The event is triggered by calls to wxWindow::Show(), and any user |
3958 | action showing a previously hidden window or vice versa (if allowed by | |
3959 | the current platform and/or window manager). | |
3960 | Notice that the event is not triggered when the application is iconized | |
3961 | (minimized) or restored under wxMSW. | |
d317fdeb | 3962 | |
d317fdeb VZ |
3963 | @onlyfor{wxmsw,wxgtk,wxos2} |
3964 | ||
3965 | @beginEventTable{wxShowEvent} | |
3966 | @event{EVT_SHOW(func)} | |
3051a44a | 3967 | Process a @c wxEVT_SHOW event. |
d317fdeb VZ |
3968 | @endEventTable |
3969 | ||
3970 | @library{wxcore} | |
3971 | @category{events} | |
3972 | ||
3e083d65 | 3973 | @see @ref overview_events, wxWindow::Show, |
d317fdeb VZ |
3974 | wxWindow::IsShown |
3975 | */ | |
3976 | ||
3977 | class wxShowEvent : public wxEvent | |
3978 | { | |
3979 | public: | |
3980 | /** | |
3981 | Constructor. | |
3982 | */ | |
3983 | wxShowEvent(int winid = 0, bool show = false); | |
3984 | ||
3985 | /** | |
3986 | Set whether the windows was shown or hidden. | |
3987 | */ | |
3988 | void SetShow(bool show); | |
3989 | ||
3990 | /** | |
3991 | Return @true if the window has been shown, @false if it has been | |
3992 | hidden. | |
3993 | */ | |
3994 | bool IsShown() const; | |
3995 | ||
3996 | /** | |
3997 | @deprecated This function is deprecated in favour of IsShown(). | |
3998 | */ | |
3999 | bool GetShow() const; | |
4000 | }; | |
4001 | ||
4002 | ||
23324ae1 | 4003 | |
42013f4c FM |
4004 | /** |
4005 | @class wxIconizeEvent | |
23324ae1 | 4006 | |
42013f4c | 4007 | An event being sent when the frame is iconized (minimized) or restored. |
23324ae1 | 4008 | |
42013f4c | 4009 | Currently only wxMSW and wxGTK generate such events. |
23324ae1 | 4010 | |
42013f4c | 4011 | @onlyfor{wxmsw,wxgtk} |
23324ae1 | 4012 | |
42013f4c | 4013 | @beginEventTable{wxIconizeEvent} |
8c6791e4 | 4014 | @event{EVT_ICONIZE(func)} |
3051a44a | 4015 | Process a @c wxEVT_ICONIZE event. |
42013f4c | 4016 | @endEventTable |
23324ae1 | 4017 | |
42013f4c FM |
4018 | @library{wxcore} |
4019 | @category{events} | |
23324ae1 | 4020 | |
3e083d65 | 4021 | @see @ref overview_events, wxTopLevelWindow::Iconize, |
42013f4c FM |
4022 | wxTopLevelWindow::IsIconized |
4023 | */ | |
4024 | class wxIconizeEvent : public wxEvent | |
4025 | { | |
4026 | public: | |
23324ae1 | 4027 | /** |
42013f4c | 4028 | Constructor. |
23324ae1 | 4029 | */ |
42013f4c | 4030 | wxIconizeEvent(int id = 0, bool iconized = true); |
23324ae1 FM |
4031 | |
4032 | /** | |
42013f4c FM |
4033 | Returns @true if the frame has been iconized, @false if it has been |
4034 | restored. | |
23324ae1 | 4035 | */ |
d317fdeb VZ |
4036 | bool IsIconized() const; |
4037 | ||
4038 | /** | |
4039 | @deprecated This function is deprecated in favour of IsIconized(). | |
4040 | */ | |
42013f4c FM |
4041 | bool Iconized() const; |
4042 | }; | |
23324ae1 | 4043 | |
23324ae1 | 4044 | |
42013f4c FM |
4045 | |
4046 | /** | |
4047 | @class wxMoveEvent | |
42013f4c | 4048 | |
3051a44a | 4049 | A move event holds information about wxTopLevelWindow move change events. |
42013f4c | 4050 | |
77211166 VZ |
4051 | These events are currently only generated by wxMSW port. |
4052 | ||
42013f4c | 4053 | @beginEventTable{wxMoveEvent} |
8c6791e4 | 4054 | @event{EVT_MOVE(func)} |
3051a44a | 4055 | Process a @c wxEVT_MOVE event, which is generated when a window is moved. |
8c6791e4 | 4056 | @event{EVT_MOVE_START(func)} |
3051a44a | 4057 | Process a @c wxEVT_MOVE_START event, which is generated when the user starts |
42013f4c | 4058 | to move or size a window. wxMSW only. |
37fff49c VZ |
4059 | @event{EVT_MOVING(func)} |
4060 | Process a @c wxEVT_MOVING event, which is generated while the user is | |
4061 | moving the window. wxMSW only. | |
8c6791e4 | 4062 | @event{EVT_MOVE_END(func)} |
3051a44a | 4063 | Process a @c wxEVT_MOVE_END event, which is generated when the user stops |
42013f4c FM |
4064 | moving or sizing a window. wxMSW only. |
4065 | @endEventTable | |
4066 | ||
4067 | @library{wxcore} | |
4068 | @category{events} | |
4069 | ||
3e083d65 | 4070 | @see wxPoint, @ref overview_events |
42013f4c FM |
4071 | */ |
4072 | class wxMoveEvent : public wxEvent | |
4073 | { | |
4074 | public: | |
23324ae1 | 4075 | /** |
42013f4c | 4076 | Constructor. |
23324ae1 | 4077 | */ |
42013f4c | 4078 | wxMoveEvent(const wxPoint& pt, int id = 0); |
23324ae1 FM |
4079 | |
4080 | /** | |
42013f4c | 4081 | Returns the position of the window generating the move change event. |
23324ae1 | 4082 | */ |
42013f4c | 4083 | wxPoint GetPosition() const; |
a90e69f7 RD |
4084 | |
4085 | wxRect GetRect() const; | |
4086 | void SetRect(const wxRect& rect); | |
4087 | void SetPosition(const wxPoint& pos); | |
23324ae1 FM |
4088 | }; |
4089 | ||
4090 | ||
4091 | /** | |
4092 | @class wxSizeEvent | |
7c913512 | 4093 | |
3051a44a | 4094 | A size event holds information about size change events of wxWindow. |
7c913512 | 4095 | |
23324ae1 | 4096 | The EVT_SIZE handler function will be called when the window has been resized. |
7c913512 | 4097 | |
42013f4c | 4098 | You may wish to use this for frames to resize their child windows as appropriate. |
7c913512 | 4099 | |
0ddf0ac6 | 4100 | Note that the size passed is of the whole window: call wxWindow::GetClientSize() |
42013f4c | 4101 | for the area which may be used by the application. |
7c913512 | 4102 | |
23324ae1 | 4103 | When a window is resized, usually only a small part of the window is damaged |
42013f4c FM |
4104 | and you may only need to repaint that area. However, if your drawing depends on the |
4105 | size of the window, you may need to clear the DC explicitly and repaint the whole window. | |
4106 | In which case, you may need to call wxWindow::Refresh to invalidate the entire window. | |
4107 | ||
b0162e32 SC |
4108 | @b Important : Sizers ( see @ref overview_sizer ) rely on size events to function |
4109 | correctly. Therefore, in a sizer-based layout, do not forget to call Skip on all | |
4110 | size events you catch (and don't catch size events at all when you don't need to). | |
4111 | ||
42013f4c | 4112 | @beginEventTable{wxSizeEvent} |
8c6791e4 | 4113 | @event{EVT_SIZE(func)} |
3051a44a | 4114 | Process a @c wxEVT_SIZE event. |
42013f4c | 4115 | @endEventTable |
7c913512 | 4116 | |
23324ae1 FM |
4117 | @library{wxcore} |
4118 | @category{events} | |
7c913512 | 4119 | |
3e083d65 | 4120 | @see wxSize, @ref overview_events |
23324ae1 FM |
4121 | */ |
4122 | class wxSizeEvent : public wxEvent | |
4123 | { | |
4124 | public: | |
4125 | /** | |
4126 | Constructor. | |
4127 | */ | |
4128 | wxSizeEvent(const wxSize& sz, int id = 0); | |
4129 | ||
4130 | /** | |
4131 | Returns the entire size of the window generating the size change event. | |
0ddf0ac6 VZ |
4132 | |
4133 | This is the new total size of the window, i.e. the same size as would | |
4134 | be returned by wxWindow::GetSize() if it were called now. Use | |
4135 | wxWindow::GetClientSize() if you catch this event in a top level window | |
4136 | such as wxFrame to find the size available for the window contents. | |
23324ae1 | 4137 | */ |
328f5751 | 4138 | wxSize GetSize() const; |
a90e69f7 RD |
4139 | void SetSize(wxSize size); |
4140 | ||
4141 | wxRect GetRect() const; | |
4142 | void SetRect(wxRect rect); | |
23324ae1 FM |
4143 | }; |
4144 | ||
4145 | ||
e54c96f1 | 4146 | |
23324ae1 FM |
4147 | /** |
4148 | @class wxSetCursorEvent | |
7c913512 | 4149 | |
3051a44a FM |
4150 | A wxSetCursorEvent is generated from wxWindow when the mouse cursor is about |
4151 | to be set as a result of mouse motion. | |
42013f4c FM |
4152 | |
4153 | This event gives the application the chance to perform specific mouse cursor | |
4154 | processing based on the current position of the mouse within the window. | |
4155 | Use wxSetCursorEvent::SetCursor to specify the cursor you want to be displayed. | |
4156 | ||
4157 | @beginEventTable{wxSetCursorEvent} | |
8c6791e4 | 4158 | @event{EVT_SET_CURSOR(func)} |
3051a44a | 4159 | Process a @c wxEVT_SET_CURSOR event. |
42013f4c | 4160 | @endEventTable |
7c913512 | 4161 | |
23324ae1 | 4162 | @library{wxcore} |
1f1d2182 | 4163 | @category{events} |
7c913512 | 4164 | |
e54c96f1 | 4165 | @see ::wxSetCursor, wxWindow::wxSetCursor |
23324ae1 FM |
4166 | */ |
4167 | class wxSetCursorEvent : public wxEvent | |
4168 | { | |
4169 | public: | |
4170 | /** | |
4171 | Constructor, used by the library itself internally to initialize the event | |
4172 | object. | |
4173 | */ | |
4174 | wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0); | |
4175 | ||
4176 | /** | |
4177 | Returns a reference to the cursor specified by this event. | |
4178 | */ | |
a6052817 | 4179 | const wxCursor& GetCursor() const; |
23324ae1 FM |
4180 | |
4181 | /** | |
4182 | Returns the X coordinate of the mouse in client coordinates. | |
4183 | */ | |
328f5751 | 4184 | wxCoord GetX() const; |
23324ae1 FM |
4185 | |
4186 | /** | |
4187 | Returns the Y coordinate of the mouse in client coordinates. | |
4188 | */ | |
328f5751 | 4189 | wxCoord GetY() const; |
23324ae1 FM |
4190 | |
4191 | /** | |
4192 | Returns @true if the cursor specified by this event is a valid cursor. | |
3c4f71cc | 4193 | |
23324ae1 | 4194 | @remarks You cannot specify wxNullCursor with this event, as it is not |
4cc4bfaf | 4195 | considered a valid cursor. |
23324ae1 | 4196 | */ |
328f5751 | 4197 | bool HasCursor() const; |
23324ae1 FM |
4198 | |
4199 | /** | |
4200 | Sets the cursor associated with this event. | |
4201 | */ | |
4202 | void SetCursor(const wxCursor& cursor); | |
4203 | }; | |
e54c96f1 | 4204 | |
39fb8056 FM |
4205 | |
4206 | ||
7fa7088e BP |
4207 | // ============================================================================ |
4208 | // Global functions/macros | |
4209 | // ============================================================================ | |
4210 | ||
b21126db | 4211 | /** @addtogroup group_funcmacro_events */ |
7fa7088e BP |
4212 | //@{ |
4213 | ||
c0c5bfad | 4214 | /** |
3e083d65 VZ |
4215 | A value uniquely identifying the type of the event. |
4216 | ||
4217 | The values of this type should only be created using wxNewEventType(). | |
c0c5bfad | 4218 | |
6496345c FM |
4219 | See the macro DEFINE_EVENT_TYPE() for more info. |
4220 | ||
3e083d65 | 4221 | @see @ref overview_events_introduction |
6496345c FM |
4222 | */ |
4223 | typedef int wxEventType; | |
4224 | ||
3e083d65 VZ |
4225 | /** |
4226 | A special event type usually used to indicate that some wxEvent has yet | |
4227 | no type assigned. | |
4228 | */ | |
4229 | wxEventType wxEVT_NULL; | |
4230 | ||
a90e69f7 RD |
4231 | wxEventType wxEVT_ANY; |
4232 | ||
6496345c FM |
4233 | /** |
4234 | Generates a new unique event type. | |
4475b410 VZ |
4235 | |
4236 | Usually this function is only used by wxDEFINE_EVENT() and not called | |
4237 | directly. | |
6496345c FM |
4238 | */ |
4239 | wxEventType wxNewEventType(); | |
4240 | ||
4475b410 VZ |
4241 | /** |
4242 | Define a new event type associated with the specified event class. | |
4243 | ||
4244 | This macro defines a new unique event type @a name associated with the | |
4245 | event class @a cls. | |
4246 | ||
4247 | For example: | |
4248 | @code | |
4249 | wxDEFINE_EVENT(MY_COMMAND_EVENT, wxCommandEvent); | |
4250 | ||
4251 | class MyCustomEvent : public wxEvent { ... }; | |
4252 | wxDEFINE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent); | |
4253 | @endcode | |
4254 | ||
4255 | @see wxDECLARE_EVENT(), @ref overview_events_custom | |
4256 | */ | |
4257 | #define wxDEFINE_EVENT(name, cls) \ | |
4258 | const wxEventTypeTag< cls > name(wxNewEventType()) | |
4259 | ||
4260 | /** | |
4261 | Declares a custom event type. | |
4262 | ||
4263 | This macro declares a variable called @a name which must be defined | |
4264 | elsewhere using wxDEFINE_EVENT(). | |
4265 | ||
4266 | The class @a cls must be the wxEvent-derived class associated with the | |
4267 | events of this type and its full declaration must be visible from the point | |
4268 | of use of this macro. | |
ff3fd98a VZ |
4269 | |
4270 | For example: | |
4271 | @code | |
4272 | wxDECLARE_EVENT(MY_COMMAND_EVENT, wxCommandEvent); | |
4273 | ||
4274 | class MyCustomEvent : public wxEvent { ... }; | |
4275 | wxDECLARE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent); | |
4276 | @endcode | |
4475b410 VZ |
4277 | */ |
4278 | #define wxDECLARE_EVENT(name, cls) \ | |
4279 | wxDECLARE_EXPORTED_EVENT(wxEMPTY_PARAMETER_VALUE, name, cls) | |
4280 | ||
4281 | /** | |
4282 | Variant of wxDECLARE_EVENT() used for event types defined inside a shared | |
4283 | library. | |
4284 | ||
4285 | This is mostly used by wxWidgets internally, e.g. | |
4286 | @code | |
4287 | wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_CORE, wxEVT_COMMAND_BUTTON_CLICKED, wxCommandEvent) | |
4288 | @endcode | |
4289 | */ | |
4290 | #define wxDECLARE_EXPORTED_EVENT( expdecl, name, cls ) \ | |
4291 | extern const expdecl wxEventTypeTag< cls > name; | |
4292 | ||
4293 | /** | |
4294 | Helper macro for definition of custom event table macros. | |
4295 | ||
4296 | This macro must only be used if wxEVENTS_COMPATIBILITY_2_8 is 1, otherwise | |
4297 | it is better and more clear to just use the address of the function | |
4298 | directly as this is all this macro does in this case. However it needs to | |
4299 | explicitly cast @a func to @a functype, which is the type of wxEvtHandler | |
4300 | member function taking the custom event argument when | |
4301 | wxEVENTS_COMPATIBILITY_2_8 is 0. | |
4302 | ||
4303 | See wx__DECLARE_EVT0 for an example of use. | |
4304 | ||
4305 | @see @ref overview_events_custom_ownclass | |
4306 | */ | |
4307 | #define wxEVENT_HANDLER_CAST(functype, func) (&func) | |
4308 | ||
4475b410 | 4309 | /** |
d455444a | 4310 | This macro is used to define event table macros for handling custom |
4475b410 VZ |
4311 | events. |
4312 | ||
4313 | Example of use: | |
4314 | @code | |
4315 | class MyEvent : public wxEvent { ... }; | |
4316 | ||
4317 | // note that this is not necessary unless using old compilers: for the | |
4318 | // reasonably new ones just use &func instead of MyEventHandler(func) | |
4319 | typedef void (wxEvtHandler::*MyEventFunction)(MyEvent&); | |
4320 | #define MyEventHandler(func) wxEVENT_HANDLER_CAST(MyEventFunction, func) | |
4321 | ||
4322 | wxDEFINE_EVENT(MY_EVENT_TYPE, MyEvent); | |
4323 | ||
4324 | #define EVT_MY(id, func) \ | |
4325 | wx__DECLARE_EVT1(MY_EVENT_TYPE, id, MyEventHandler(func)) | |
4326 | ||
4327 | ... | |
4328 | ||
a0e9a5df | 4329 | wxBEGIN_EVENT_TABLE(MyFrame, wxFrame) |
4475b410 | 4330 | EVT_MY(wxID_ANY, MyFrame::OnMyEvent) |
a0e9a5df | 4331 | wxEND_EVENT_TABLE() |
4475b410 VZ |
4332 | @endcode |
4333 | ||
4334 | @param evt | |
4335 | The event type to handle. | |
4336 | @param id | |
4337 | The identifier of events to handle. | |
4475b410 VZ |
4338 | @param fn |
4339 | The event handler method. | |
4340 | */ | |
4475b410 VZ |
4341 | #define wx__DECLARE_EVT1(evt, id, fn) \ |
4342 | wx__DECLARE_EVT2(evt, id, wxID_ANY, fn) | |
d455444a FM |
4343 | |
4344 | /** | |
4345 | Generalized version of the wx__DECLARE_EVT1() macro taking a range of | |
4346 | IDs instead of a single one. | |
4347 | Argument @a id1 is the first identifier of the range, @a id2 is the | |
4348 | second identifier of the range. | |
4349 | */ | |
4350 | #define wx__DECLARE_EVT2(evt, id1, id2, fn) \ | |
4351 | DECLARE_EVENT_TABLE_ENTRY(evt, id1, id2, fn, NULL), | |
4352 | ||
4353 | /** | |
4354 | Simplified version of the wx__DECLARE_EVT1() macro, to be used when the | |
4355 | event type must be handled regardless of the ID associated with the | |
4356 | specific event instances. | |
4357 | */ | |
4475b410 VZ |
4358 | #define wx__DECLARE_EVT0(evt, fn) \ |
4359 | wx__DECLARE_EVT1(evt, wxID_ANY, fn) | |
4475b410 | 4360 | |
6496345c FM |
4361 | /** |
4362 | Use this macro inside a class declaration to declare a @e static event table | |
4363 | for that class. | |
4364 | ||
a0e9a5df FM |
4365 | In the implementation file you'll need to use the wxBEGIN_EVENT_TABLE() |
4366 | and the wxEND_EVENT_TABLE() macros, plus some additional @c EVT_xxx macro | |
6496345c | 4367 | to capture events. |
a0e9a5df FM |
4368 | |
4369 | Note that this macro requires a final semicolon. | |
6496345c | 4370 | |
3e083d65 | 4371 | @see @ref overview_events_eventtables |
6496345c | 4372 | */ |
a0e9a5df | 4373 | #define wxDECLARE_EVENT_TABLE() |
6496345c FM |
4374 | |
4375 | /** | |
4376 | Use this macro in a source file to start listing @e static event handlers | |
4377 | for a specific class. | |
4378 | ||
a0e9a5df | 4379 | Use wxEND_EVENT_TABLE() to terminate the event-declaration block. |
6496345c | 4380 | |
3e083d65 | 4381 | @see @ref overview_events_eventtables |
6496345c | 4382 | */ |
a0e9a5df | 4383 | #define wxBEGIN_EVENT_TABLE(theClass, baseClass) |
6496345c FM |
4384 | |
4385 | /** | |
4386 | Use this macro in a source file to end listing @e static event handlers | |
4387 | for a specific class. | |
4388 | ||
a0e9a5df | 4389 | Use wxBEGIN_EVENT_TABLE() to start the event-declaration block. |
6496345c | 4390 | |
3e083d65 | 4391 | @see @ref overview_events_eventtables |
6496345c | 4392 | */ |
a0e9a5df | 4393 | #define wxEND_EVENT_TABLE() |
6496345c | 4394 | |
39fb8056 FM |
4395 | /** |
4396 | In a GUI application, this function posts @a event to the specified @e dest | |
7fa7088e BP |
4397 | object using wxEvtHandler::AddPendingEvent(). |
4398 | ||
4399 | Otherwise, it dispatches @a event immediately using | |
4400 | wxEvtHandler::ProcessEvent(). See the respective documentation for details | |
c3f94162 VZ |
4401 | (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent() |
4402 | this function is not thread-safe for event objects having wxString fields, | |
4403 | use wxQueueEvent() instead. | |
39fb8056 | 4404 | |
7fa7088e | 4405 | @header{wx/event.h} |
39fb8056 | 4406 | */ |
c3f94162 VZ |
4407 | void wxPostEvent(wxEvtHandler* dest, const wxEvent& event); |
4408 | ||
4409 | /** | |
4410 | Queue an event for processing on the given object. | |
4411 | ||
4412 | This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation | |
4413 | for more details. | |
4414 | ||
4415 | @header{wx/event.h} | |
4416 | ||
4417 | @param dest | |
4418 | The object to queue the event on, can't be @c NULL. | |
4419 | @param event | |
4420 | The heap-allocated and non-@c NULL event to queue, the function takes | |
4421 | ownership of it. | |
4422 | */ | |
4423 | void wxQueueEvent(wxEvtHandler* dest, wxEvent *event); | |
7fa7088e | 4424 | |
a90e69f7 RD |
4425 | |
4426 | ||
4427 | wxEventType wxEVT_COMMAND_BUTTON_CLICKED; | |
4428 | wxEventType wxEVT_COMMAND_CHECKBOX_CLICKED; | |
4429 | wxEventType wxEVT_COMMAND_CHOICE_SELECTED; | |
4430 | wxEventType wxEVT_COMMAND_LISTBOX_SELECTED; | |
4431 | wxEventType wxEVT_COMMAND_LISTBOX_DOUBLECLICKED; | |
4432 | wxEventType wxEVT_COMMAND_CHECKLISTBOX_TOGGLED; | |
4433 | wxEventType wxEVT_COMMAND_MENU_SELECTED; | |
4434 | wxEventType wxEVT_COMMAND_SLIDER_UPDATED; | |
4435 | wxEventType wxEVT_COMMAND_RADIOBOX_SELECTED; | |
4436 | wxEventType wxEVT_COMMAND_RADIOBUTTON_SELECTED; | |
4437 | wxEventType wxEVT_COMMAND_SCROLLBAR_UPDATED; | |
4438 | wxEventType wxEVT_COMMAND_VLBOX_SELECTED; | |
4439 | wxEventType wxEVT_COMMAND_COMBOBOX_SELECTED; | |
4440 | wxEventType wxEVT_COMMAND_TOOL_RCLICKED; | |
4441 | wxEventType wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED; | |
4442 | wxEventType wxEVT_COMMAND_TOOL_ENTER; | |
4443 | wxEventType wxEVT_COMMAND_COMBOBOX_DROPDOWN; | |
4444 | wxEventType wxEVT_COMMAND_COMBOBOX_CLOSEUP; | |
c1b293bb | 4445 | wxEventType wxEVT_THREAD; |
a90e69f7 RD |
4446 | wxEventType wxEVT_LEFT_DOWN; |
4447 | wxEventType wxEVT_LEFT_UP; | |
4448 | wxEventType wxEVT_MIDDLE_DOWN; | |
4449 | wxEventType wxEVT_MIDDLE_UP; | |
4450 | wxEventType wxEVT_RIGHT_DOWN; | |
4451 | wxEventType wxEVT_RIGHT_UP; | |
4452 | wxEventType wxEVT_MOTION; | |
4453 | wxEventType wxEVT_ENTER_WINDOW; | |
4454 | wxEventType wxEVT_LEAVE_WINDOW; | |
4455 | wxEventType wxEVT_LEFT_DCLICK; | |
4456 | wxEventType wxEVT_MIDDLE_DCLICK; | |
4457 | wxEventType wxEVT_RIGHT_DCLICK; | |
4458 | wxEventType wxEVT_SET_FOCUS; | |
4459 | wxEventType wxEVT_KILL_FOCUS; | |
4460 | wxEventType wxEVT_CHILD_FOCUS; | |
4461 | wxEventType wxEVT_MOUSEWHEEL; | |
4462 | wxEventType wxEVT_AUX1_DOWN; | |
4463 | wxEventType wxEVT_AUX1_UP; | |
4464 | wxEventType wxEVT_AUX1_DCLICK; | |
4465 | wxEventType wxEVT_AUX2_DOWN; | |
4466 | wxEventType wxEVT_AUX2_UP; | |
4467 | wxEventType wxEVT_AUX2_DCLICK; | |
4468 | wxEventType wxEVT_CHAR; | |
4469 | wxEventType wxEVT_CHAR_HOOK; | |
4470 | wxEventType wxEVT_NAVIGATION_KEY; | |
4471 | wxEventType wxEVT_KEY_DOWN; | |
4472 | wxEventType wxEVT_KEY_UP; | |
4473 | wxEventType wxEVT_HOTKEY; | |
4474 | wxEventType wxEVT_SET_CURSOR; | |
4475 | wxEventType wxEVT_SCROLL_TOP; | |
4476 | wxEventType wxEVT_SCROLL_BOTTOM; | |
4477 | wxEventType wxEVT_SCROLL_LINEUP; | |
4478 | wxEventType wxEVT_SCROLL_LINEDOWN; | |
4479 | wxEventType wxEVT_SCROLL_PAGEUP; | |
4480 | wxEventType wxEVT_SCROLL_PAGEDOWN; | |
4481 | wxEventType wxEVT_SCROLL_THUMBTRACK; | |
4482 | wxEventType wxEVT_SCROLL_THUMBRELEASE; | |
4483 | wxEventType wxEVT_SCROLL_CHANGED; | |
4484 | wxEventType wxEVT_SPIN_UP; | |
4485 | wxEventType wxEVT_SPIN_DOWN; | |
4486 | wxEventType wxEVT_SPIN; | |
4487 | wxEventType wxEVT_SCROLLWIN_TOP; | |
4488 | wxEventType wxEVT_SCROLLWIN_BOTTOM; | |
4489 | wxEventType wxEVT_SCROLLWIN_LINEUP; | |
4490 | wxEventType wxEVT_SCROLLWIN_LINEDOWN; | |
4491 | wxEventType wxEVT_SCROLLWIN_PAGEUP; | |
4492 | wxEventType wxEVT_SCROLLWIN_PAGEDOWN; | |
4493 | wxEventType wxEVT_SCROLLWIN_THUMBTRACK; | |
4494 | wxEventType wxEVT_SCROLLWIN_THUMBRELEASE; | |
4495 | wxEventType wxEVT_SIZE; | |
4496 | wxEventType wxEVT_MOVE; | |
4497 | wxEventType wxEVT_CLOSE_WINDOW; | |
4498 | wxEventType wxEVT_END_SESSION; | |
4499 | wxEventType wxEVT_QUERY_END_SESSION; | |
4500 | wxEventType wxEVT_ACTIVATE_APP; | |
4501 | wxEventType wxEVT_ACTIVATE; | |
4502 | wxEventType wxEVT_CREATE; | |
4503 | wxEventType wxEVT_DESTROY; | |
4504 | wxEventType wxEVT_SHOW; | |
4505 | wxEventType wxEVT_ICONIZE; | |
4506 | wxEventType wxEVT_MAXIMIZE; | |
4507 | wxEventType wxEVT_MOUSE_CAPTURE_CHANGED; | |
4508 | wxEventType wxEVT_MOUSE_CAPTURE_LOST; | |
4509 | wxEventType wxEVT_PAINT; | |
4510 | wxEventType wxEVT_ERASE_BACKGROUND; | |
4511 | wxEventType wxEVT_NC_PAINT; | |
4512 | wxEventType wxEVT_MENU_OPEN; | |
4513 | wxEventType wxEVT_MENU_CLOSE; | |
4514 | wxEventType wxEVT_MENU_HIGHLIGHT; | |
4515 | wxEventType wxEVT_CONTEXT_MENU; | |
4516 | wxEventType wxEVT_SYS_COLOUR_CHANGED; | |
4517 | wxEventType wxEVT_DISPLAY_CHANGED; | |
4518 | wxEventType wxEVT_QUERY_NEW_PALETTE; | |
4519 | wxEventType wxEVT_PALETTE_CHANGED; | |
4520 | wxEventType wxEVT_JOY_BUTTON_DOWN; | |
4521 | wxEventType wxEVT_JOY_BUTTON_UP; | |
4522 | wxEventType wxEVT_JOY_MOVE; | |
4523 | wxEventType wxEVT_JOY_ZMOVE; | |
4524 | wxEventType wxEVT_DROP_FILES; | |
4525 | wxEventType wxEVT_INIT_DIALOG; | |
4526 | wxEventType wxEVT_IDLE; | |
4527 | wxEventType wxEVT_UPDATE_UI; | |
4528 | wxEventType wxEVT_SIZING; | |
4529 | wxEventType wxEVT_MOVING; | |
4530 | wxEventType wxEVT_MOVE_START; | |
4531 | wxEventType wxEVT_MOVE_END; | |
4532 | wxEventType wxEVT_HIBERNATE; | |
4533 | wxEventType wxEVT_COMMAND_TEXT_COPY; | |
4534 | wxEventType wxEVT_COMMAND_TEXT_CUT; | |
4535 | wxEventType wxEVT_COMMAND_TEXT_PASTE; | |
4536 | wxEventType wxEVT_COMMAND_LEFT_CLICK; | |
4537 | wxEventType wxEVT_COMMAND_LEFT_DCLICK; | |
4538 | wxEventType wxEVT_COMMAND_RIGHT_CLICK; | |
4539 | wxEventType wxEVT_COMMAND_RIGHT_DCLICK; | |
4540 | wxEventType wxEVT_COMMAND_SET_FOCUS; | |
4541 | wxEventType wxEVT_COMMAND_KILL_FOCUS; | |
4542 | wxEventType wxEVT_COMMAND_ENTER; | |
4543 | wxEventType wxEVT_HELP; | |
4544 | wxEventType wxEVT_DETAILED_HELP; | |
4545 | wxEventType wxEVT_COMMAND_TEXT_UPDATED; | |
4546 | wxEventType wxEVT_COMMAND_TOOL_CLICKED; | |
ea8fa3c4 | 4547 | wxEventType wxEVT_WINDOW_MODAL_DIALOG_CLOSED; |
a90e69f7 RD |
4548 | |
4549 | ||
4550 | ||
7fa7088e BP |
4551 | //@} |
4552 |