]>
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. | |
2f7baaec VZ |
1447 | |
1448 | Notice that this position is simply the current mouse pointer position | |
1449 | and has no special relationship to the key event itself. | |
42013f4c FM |
1450 | */ |
1451 | wxPoint GetPosition() const; | |
1452 | void GetPosition(long* x, long* y) const; | |
1453 | //@} | |
1454 | ||
1455 | /** | |
5995a84f VZ |
1456 | Returns the raw key code for this event. |
1457 | ||
1458 | The flags are platform-dependent and should only be used if the | |
1459 | functionality provided by other wxKeyEvent methods is insufficient. | |
1460 | ||
1461 | Under MSW, the raw key code is the value of @c wParam parameter of the | |
1462 | corresponding message. | |
1463 | ||
1464 | Under GTK, the raw key code is the @c keyval field of the corresponding | |
1465 | GDK event. | |
1466 | ||
1467 | Under OS X, the raw key code is the @c keyCode field of the | |
1468 | corresponding NSEvent. | |
42013f4c FM |
1469 | |
1470 | @note Currently the raw key codes are not supported by all ports, use | |
1471 | @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. | |
1472 | */ | |
1473 | wxUint32 GetRawKeyCode() const; | |
1474 | ||
1475 | /** | |
5995a84f VZ |
1476 | Returns the low level key flags for this event. |
1477 | ||
1478 | The flags are platform-dependent and should only be used if the | |
1479 | functionality provided by other wxKeyEvent methods is insufficient. | |
1480 | ||
1481 | Under MSW, the raw flags are just the value of @c lParam parameter of | |
1482 | the corresponding message. | |
1483 | ||
1484 | Under GTK, the raw flags contain the @c hardware_keycode field of the | |
1485 | corresponding GDK event. | |
1486 | ||
1487 | Under OS X, the raw flags contain the modifiers state. | |
42013f4c FM |
1488 | |
1489 | @note Currently the raw key flags are not supported by all ports, use | |
1490 | @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. | |
1491 | */ | |
1492 | wxUint32 GetRawKeyFlags() const; | |
1493 | ||
1494 | /** | |
1495 | Returns the Unicode character corresponding to this key event. | |
1496 | ||
0d2f3b9d | 1497 | If the key pressed doesn't have any character value (e.g. a cursor key) |
86408a03 VZ |
1498 | this method will return @c WXK_NONE. In this case you should use |
1499 | GetKeyCode() to retrieve the value of the key. | |
0d2f3b9d | 1500 | |
42013f4c FM |
1501 | This function is only available in Unicode build, i.e. when |
1502 | @c wxUSE_UNICODE is 1. | |
1503 | */ | |
1504 | wxChar GetUnicodeKey() const; | |
1505 | ||
1506 | /** | |
1507 | Returns the X position (in client coordinates) of the event. | |
2f7baaec VZ |
1508 | |
1509 | @see GetPosition() | |
42013f4c FM |
1510 | */ |
1511 | wxCoord GetX() const; | |
1512 | ||
1513 | /** | |
1514 | Returns the Y position (in client coordinates) of the event. | |
2f7baaec VZ |
1515 | |
1516 | @see GetPosition() | |
42013f4c FM |
1517 | */ |
1518 | wxCoord GetY() const; | |
4cf1a9bf VZ |
1519 | |
1520 | /** | |
1521 | Allow normal key events generation. | |
1522 | ||
1523 | Can be called from @c wxEVT_CHAR_HOOK handler to indicate that the | |
1524 | generation of normal events should @em not be suppressed, as it happens | |
1525 | by default when this event is handled. | |
1526 | ||
1527 | The intended use of this method is to allow some window object to | |
1528 | prevent @c wxEVT_CHAR_HOOK handler in its parent window from running by | |
1529 | defining its own handler for this event. Without calling this method, | |
1530 | this would result in not generating @c wxEVT_KEY_DOWN nor @c wxEVT_CHAR | |
1531 | events at all but by calling it you can ensure that these events would | |
1532 | still be generated, even if @c wxEVT_CHAR_HOOK event was handled. | |
1533 | ||
1534 | @since 2.9.3 | |
1535 | */ | |
1536 | void DoAllowNextEvent(); | |
1537 | ||
1538 | /** | |
1539 | Returns @true if DoAllowNextEvent() had been called, @false by default. | |
1540 | ||
1541 | This method is used by wxWidgets itself to determine whether the normal | |
1542 | key events should be generated after @c wxEVT_CHAR_HOOK processing. | |
1543 | ||
1544 | @since 2.9.3 | |
1545 | */ | |
1546 | bool IsNextEventAllowed() const; | |
23324ae1 FM |
1547 | }; |
1548 | ||
1549 | ||
e54c96f1 | 1550 | |
50e55c13 RD |
1551 | enum |
1552 | { | |
1553 | wxJOYSTICK1, | |
1554 | wxJOYSTICK2 | |
1555 | }; | |
1556 | ||
1557 | // Which button is down? | |
1558 | enum | |
1559 | { | |
1560 | wxJOY_BUTTON_ANY = -1, | |
1561 | wxJOY_BUTTON1 = 1, | |
1562 | wxJOY_BUTTON2 = 2, | |
1563 | wxJOY_BUTTON3 = 4, | |
1564 | wxJOY_BUTTON4 = 8 | |
1565 | }; | |
1566 | ||
1567 | ||
23324ae1 | 1568 | /** |
42013f4c | 1569 | @class wxJoystickEvent |
7c913512 | 1570 | |
42013f4c FM |
1571 | This event class contains information about joystick events, particularly |
1572 | events received by windows. | |
1f1d2182 | 1573 | |
42013f4c | 1574 | @beginEventTable{wxJoystickEvent} |
3051a44a FM |
1575 | @event{EVT_JOY_BUTTON_DOWN(func)} |
1576 | Process a @c wxEVT_JOY_BUTTON_DOWN event. | |
1577 | @event{EVT_JOY_BUTTON_UP(func)} | |
1578 | Process a @c wxEVT_JOY_BUTTON_UP event. | |
1579 | @event{EVT_JOY_MOVE(func)} | |
1580 | Process a @c wxEVT_JOY_MOVE event. | |
1581 | @event{EVT_JOY_ZMOVE(func)} | |
1582 | Process a @c wxEVT_JOY_ZMOVE event. | |
1583 | @event{EVT_JOYSTICK_EVENTS(func)} | |
42013f4c | 1584 | Processes all joystick events. |
1f1d2182 FM |
1585 | @endEventTable |
1586 | ||
23324ae1 FM |
1587 | @library{wxcore} |
1588 | @category{events} | |
7c913512 | 1589 | |
42013f4c | 1590 | @see wxJoystick |
23324ae1 | 1591 | */ |
42013f4c | 1592 | class wxJoystickEvent : public wxEvent |
23324ae1 FM |
1593 | { |
1594 | public: | |
1595 | /** | |
1596 | Constructor. | |
1597 | */ | |
42013f4c FM |
1598 | wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0, |
1599 | int joystick = wxJOYSTICK1, | |
1600 | int change = 0); | |
23324ae1 FM |
1601 | |
1602 | /** | |
42013f4c FM |
1603 | Returns @true if the event was a down event from the specified button |
1604 | (or any button). | |
23324ae1 | 1605 | |
42013f4c FM |
1606 | @param button |
1607 | Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to | |
1608 | indicate any button down event. | |
23324ae1 | 1609 | */ |
42013f4c | 1610 | bool ButtonDown(int button = wxJOY_BUTTON_ANY) const; |
23324ae1 FM |
1611 | |
1612 | /** | |
42013f4c | 1613 | Returns @true if the specified button (or any button) was in a down state. |
23324ae1 | 1614 | |
42013f4c FM |
1615 | @param button |
1616 | Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to | |
1617 | indicate any button down event. | |
23324ae1 | 1618 | */ |
42013f4c | 1619 | bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const; |
23324ae1 FM |
1620 | |
1621 | /** | |
42013f4c FM |
1622 | Returns @true if the event was an up event from the specified button |
1623 | (or any button). | |
1624 | ||
1625 | @param button | |
1626 | Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to | |
1627 | indicate any button down event. | |
23324ae1 | 1628 | */ |
42013f4c | 1629 | bool ButtonUp(int button = wxJOY_BUTTON_ANY) const; |
23324ae1 FM |
1630 | |
1631 | /** | |
42013f4c FM |
1632 | Returns the identifier of the button changing state. |
1633 | ||
1634 | This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. | |
23324ae1 | 1635 | */ |
42013f4c | 1636 | int GetButtonChange() const; |
23324ae1 FM |
1637 | |
1638 | /** | |
42013f4c FM |
1639 | Returns the down state of the buttons. |
1640 | ||
1641 | This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. | |
23324ae1 | 1642 | */ |
42013f4c | 1643 | int GetButtonState() const; |
23324ae1 FM |
1644 | |
1645 | /** | |
42013f4c FM |
1646 | Returns the identifier of the joystick generating the event - one of |
1647 | wxJOYSTICK1 and wxJOYSTICK2. | |
23324ae1 | 1648 | */ |
42013f4c | 1649 | int GetJoystick() const; |
23324ae1 FM |
1650 | |
1651 | /** | |
42013f4c | 1652 | Returns the x, y position of the joystick event. |
3b2f80c2 VZ |
1653 | |
1654 | These coordinates are valid for all the events except wxEVT_JOY_ZMOVE. | |
23324ae1 | 1655 | */ |
42013f4c | 1656 | wxPoint GetPosition() const; |
23324ae1 FM |
1657 | |
1658 | /** | |
42013f4c | 1659 | Returns the z position of the joystick event. |
3b2f80c2 VZ |
1660 | |
1661 | This method can only be used for wxEVT_JOY_ZMOVE events. | |
23324ae1 | 1662 | */ |
42013f4c | 1663 | int GetZPosition() const; |
23324ae1 FM |
1664 | |
1665 | /** | |
42013f4c FM |
1666 | Returns @true if this was a button up or down event |
1667 | (@e not 'is any button down?'). | |
23324ae1 | 1668 | */ |
42013f4c | 1669 | bool IsButton() const; |
23324ae1 FM |
1670 | |
1671 | /** | |
42013f4c | 1672 | Returns @true if this was an x, y move event. |
23324ae1 | 1673 | */ |
42013f4c | 1674 | bool IsMove() const; |
23324ae1 FM |
1675 | |
1676 | /** | |
42013f4c | 1677 | Returns @true if this was a z move event. |
23324ae1 | 1678 | */ |
42013f4c FM |
1679 | bool IsZMove() const; |
1680 | }; | |
23324ae1 | 1681 | |
3c4f71cc | 1682 | |
23324ae1 | 1683 | |
42013f4c FM |
1684 | /** |
1685 | @class wxScrollWinEvent | |
42013f4c FM |
1686 | |
1687 | A scroll event holds information about events sent from scrolling windows. | |
1688 | ||
3051a44a FM |
1689 | Note that you can use the EVT_SCROLLWIN* macros for intercepting scroll window events |
1690 | from the receiving window. | |
23324ae1 | 1691 | |
42013f4c | 1692 | @beginEventTable{wxScrollWinEvent} |
8c6791e4 | 1693 | @event{EVT_SCROLLWIN(func)} |
42013f4c | 1694 | Process all scroll events. |
8c6791e4 | 1695 | @event{EVT_SCROLLWIN_TOP(func)} |
3a194bda | 1696 | Process @c wxEVT_SCROLLWIN_TOP scroll-to-top events. |
8c6791e4 | 1697 | @event{EVT_SCROLLWIN_BOTTOM(func)} |
3a194bda | 1698 | Process @c wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events. |
8c6791e4 | 1699 | @event{EVT_SCROLLWIN_LINEUP(func)} |
3a194bda | 1700 | Process @c wxEVT_SCROLLWIN_LINEUP line up events. |
8c6791e4 | 1701 | @event{EVT_SCROLLWIN_LINEDOWN(func)} |
3a194bda | 1702 | Process @c wxEVT_SCROLLWIN_LINEDOWN line down events. |
8c6791e4 | 1703 | @event{EVT_SCROLLWIN_PAGEUP(func)} |
3a194bda | 1704 | Process @c wxEVT_SCROLLWIN_PAGEUP page up events. |
8c6791e4 | 1705 | @event{EVT_SCROLLWIN_PAGEDOWN(func)} |
3a194bda | 1706 | Process @c wxEVT_SCROLLWIN_PAGEDOWN page down events. |
8c6791e4 | 1707 | @event{EVT_SCROLLWIN_THUMBTRACK(func)} |
3a194bda | 1708 | Process @c wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events |
42013f4c | 1709 | (frequent events sent as the user drags the thumbtrack). |
8c6791e4 | 1710 | @event{EVT_SCROLLWIN_THUMBRELEASE(func)} |
3a194bda | 1711 | Process @c wxEVT_SCROLLWIN_THUMBRELEASE thumb release events. |
42013f4c FM |
1712 | @endEventTable |
1713 | ||
1714 | ||
1715 | @library{wxcore} | |
1716 | @category{events} | |
1717 | ||
3e083d65 | 1718 | @see wxScrollEvent, @ref overview_events |
42013f4c FM |
1719 | */ |
1720 | class wxScrollWinEvent : public wxEvent | |
1721 | { | |
1722 | public: | |
23324ae1 | 1723 | /** |
42013f4c | 1724 | Constructor. |
23324ae1 | 1725 | */ |
42013f4c FM |
1726 | wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0, |
1727 | int orientation = 0); | |
23324ae1 FM |
1728 | |
1729 | /** | |
42013f4c FM |
1730 | Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the |
1731 | scrollbar. | |
1732 | ||
1733 | @todo wxHORIZONTAL and wxVERTICAL should go in their own enum | |
23324ae1 | 1734 | */ |
42013f4c | 1735 | int GetOrientation() const; |
23324ae1 FM |
1736 | |
1737 | /** | |
42013f4c FM |
1738 | Returns the position of the scrollbar for the thumb track and release events. |
1739 | ||
1740 | Note that this field can't be used for the other events, you need to query | |
1741 | the window itself for the current position in that case. | |
23324ae1 | 1742 | */ |
42013f4c | 1743 | int GetPosition() const; |
a90e69f7 RD |
1744 | |
1745 | void SetOrientation(int orient); | |
1746 | void SetPosition(int pos); | |
23324ae1 FM |
1747 | }; |
1748 | ||
1749 | ||
e54c96f1 | 1750 | |
23324ae1 | 1751 | /** |
42013f4c | 1752 | @class wxSysColourChangedEvent |
7c913512 | 1753 | |
42013f4c FM |
1754 | This class is used for system colour change events, which are generated |
1755 | when the user changes the colour settings using the control panel. | |
1756 | This is only appropriate under Windows. | |
7c913512 | 1757 | |
42013f4c FM |
1758 | @remarks |
1759 | The default event handler for this event propagates the event to child windows, | |
1760 | since Windows only sends the events to top-level windows. | |
1761 | If intercepting this event for a top-level window, remember to call the base | |
1762 | class handler, or to pass the event on to the window's children explicitly. | |
3d6c68c1 | 1763 | |
42013f4c | 1764 | @beginEventTable{wxSysColourChangedEvent} |
8c6791e4 | 1765 | @event{EVT_SYS_COLOUR_CHANGED(func)} |
3051a44a | 1766 | Process a @c wxEVT_SYS_COLOUR_CHANGED event. |
3d6c68c1 VS |
1767 | @endEventTable |
1768 | ||
23324ae1 FM |
1769 | @library{wxcore} |
1770 | @category{events} | |
7c913512 | 1771 | |
3e083d65 | 1772 | @see @ref overview_events |
23324ae1 | 1773 | */ |
42013f4c | 1774 | class wxSysColourChangedEvent : public wxEvent |
23324ae1 FM |
1775 | { |
1776 | public: | |
1777 | /** | |
3d6c68c1 | 1778 | Constructor. |
23324ae1 | 1779 | */ |
42013f4c | 1780 | wxSysColourChangedEvent(); |
23324ae1 FM |
1781 | }; |
1782 | ||
1783 | ||
e54c96f1 | 1784 | |
23324ae1 | 1785 | /** |
42013f4c | 1786 | @class wxWindowCreateEvent |
7c913512 | 1787 | |
42013f4c FM |
1788 | This event is sent just after the actual window associated with a wxWindow |
1789 | object has been created. | |
7c913512 | 1790 | |
42013f4c FM |
1791 | Since it is derived from wxCommandEvent, the event propagates up |
1792 | the window hierarchy. | |
7c913512 | 1793 | |
42013f4c | 1794 | @beginEventTable{wxWindowCreateEvent} |
8c6791e4 | 1795 | @event{EVT_WINDOW_CREATE(func)} |
3051a44a | 1796 | Process a @c wxEVT_CREATE event. |
42013f4c | 1797 | @endEventTable |
7c913512 | 1798 | |
23324ae1 FM |
1799 | @library{wxcore} |
1800 | @category{events} | |
7c913512 | 1801 | |
3e083d65 | 1802 | @see @ref overview_events, wxWindowDestroyEvent |
23324ae1 | 1803 | */ |
42013f4c | 1804 | class wxWindowCreateEvent : public wxCommandEvent |
23324ae1 FM |
1805 | { |
1806 | public: | |
1807 | /** | |
42013f4c FM |
1808 | Constructor. |
1809 | */ | |
1810 | wxWindowCreateEvent(wxWindow* win = NULL); | |
a79a6671 | 1811 | |
57ab6f23 | 1812 | /// Return the window being created. |
a79a6671 | 1813 | wxWindow *GetWindow() const; |
42013f4c | 1814 | }; |
3c4f71cc | 1815 | |
23324ae1 | 1816 | |
23324ae1 | 1817 | |
42013f4c FM |
1818 | /** |
1819 | @class wxPaintEvent | |
23324ae1 | 1820 | |
42013f4c | 1821 | A paint event is sent when a window's contents needs to be repainted. |
23324ae1 | 1822 | |
7ca106e8 VZ |
1823 | The handler of this event must create a wxPaintDC object and use it for |
1824 | painting the window contents. For example: | |
42013f4c FM |
1825 | @code |
1826 | void MyWindow::OnPaint(wxPaintEvent& event) | |
1827 | { | |
1828 | wxPaintDC dc(this); | |
23324ae1 | 1829 | |
42013f4c FM |
1830 | DrawMyDocument(dc); |
1831 | } | |
1832 | @endcode | |
7ca106e8 VZ |
1833 | |
1834 | Notice that you must @e not create other kinds of wxDC (e.g. wxClientDC or | |
1835 | wxWindowDC) in EVT_PAINT handlers and also don't create wxPaintDC outside | |
1836 | of this event handlers. | |
1837 | ||
1838 | ||
42013f4c FM |
1839 | You can optimize painting by retrieving the rectangles that have been damaged |
1840 | and only repainting these. The rectangles are in terms of the client area, | |
1841 | and are unscrolled, so you will need to do some calculations using the current | |
1842 | view position to obtain logical, scrolled units. | |
1843 | Here is an example of using the wxRegionIterator class: | |
1844 | @code | |
1845 | // Called when window needs to be repainted. | |
1846 | void MyWindow::OnPaint(wxPaintEvent& event) | |
1847 | { | |
1848 | wxPaintDC dc(this); | |
23324ae1 | 1849 | |
42013f4c FM |
1850 | // Find Out where the window is scrolled to |
1851 | int vbX,vbY; // Top left corner of client | |
1852 | GetViewStart(&vbX,&vbY); | |
23324ae1 | 1853 | |
42013f4c FM |
1854 | int vX,vY,vW,vH; // Dimensions of client area in pixels |
1855 | wxRegionIterator upd(GetUpdateRegion()); // get the update rect list | |
23324ae1 | 1856 | |
42013f4c FM |
1857 | while (upd) |
1858 | { | |
1859 | vX = upd.GetX(); | |
1860 | vY = upd.GetY(); | |
1861 | vW = upd.GetW(); | |
1862 | vH = upd.GetH(); | |
23324ae1 | 1863 | |
42013f4c FM |
1864 | // Alternatively we can do this: |
1865 | // wxRect rect(upd.GetRect()); | |
3c4f71cc | 1866 | |
42013f4c FM |
1867 | // Repaint this rectangle |
1868 | ...some code... | |
3c4f71cc | 1869 | |
42013f4c FM |
1870 | upd ++ ; |
1871 | } | |
1872 | } | |
1873 | @endcode | |
3c4f71cc | 1874 | |
7ca106e8 VZ |
1875 | @remarks |
1876 | Please notice that in general it is impossible to change the drawing of a | |
1877 | standard control (such as wxButton) and so you shouldn't attempt to handle | |
1878 | paint events for them as even if it might work on some platforms, this is | |
1879 | inherently not portable and won't work everywhere. | |
1880 | ||
3c4f71cc | 1881 | |
42013f4c | 1882 | @beginEventTable{wxPaintEvent} |
8c6791e4 | 1883 | @event{EVT_PAINT(func)} |
3051a44a | 1884 | Process a @c wxEVT_PAINT event. |
42013f4c | 1885 | @endEventTable |
3c4f71cc | 1886 | |
42013f4c FM |
1887 | @library{wxcore} |
1888 | @category{events} | |
3c4f71cc | 1889 | |
3e083d65 | 1890 | @see @ref overview_events |
42013f4c FM |
1891 | */ |
1892 | class wxPaintEvent : public wxEvent | |
1893 | { | |
1894 | public: | |
1895 | /** | |
1896 | Constructor. | |
1897 | */ | |
1898 | wxPaintEvent(int id = 0); | |
1899 | }; | |
3c4f71cc | 1900 | |
3c4f71cc | 1901 | |
3c4f71cc | 1902 | |
42013f4c FM |
1903 | /** |
1904 | @class wxMaximizeEvent | |
3c4f71cc | 1905 | |
42013f4c FM |
1906 | An event being sent when a top level window is maximized. Notice that it is |
1907 | not sent when the window is restored to its original size after it had been | |
1908 | maximized, only a normal wxSizeEvent is generated in this case. | |
3c4f71cc | 1909 | |
89c6e024 | 1910 | Currently this event is only generated in wxMSW, wxGTK, wxOSX/Cocoa and wxOS2 |
e22e5ee4 VZ |
1911 | ports so portable programs should only rely on receiving @c wxEVT_SIZE and |
1912 | not necessarily this event when the window is maximized. | |
1913 | ||
42013f4c | 1914 | @beginEventTable{wxMaximizeEvent} |
8c6791e4 | 1915 | @event{EVT_MAXIMIZE(func)} |
3051a44a | 1916 | Process a @c wxEVT_MAXIMIZE event. |
42013f4c | 1917 | @endEventTable |
3c4f71cc | 1918 | |
42013f4c FM |
1919 | @library{wxcore} |
1920 | @category{events} | |
23324ae1 | 1921 | |
3e083d65 | 1922 | @see @ref overview_events, wxTopLevelWindow::Maximize, |
42013f4c FM |
1923 | wxTopLevelWindow::IsMaximized |
1924 | */ | |
1925 | class wxMaximizeEvent : public wxEvent | |
1926 | { | |
1927 | public: | |
23324ae1 | 1928 | /** |
42013f4c | 1929 | Constructor. Only used by wxWidgets internally. |
23324ae1 | 1930 | */ |
42013f4c FM |
1931 | wxMaximizeEvent(int id = 0); |
1932 | }; | |
23324ae1 | 1933 | |
42013f4c FM |
1934 | /** |
1935 | The possibles modes to pass to wxUpdateUIEvent::SetMode(). | |
1936 | */ | |
1937 | enum wxUpdateUIMode | |
1938 | { | |
1939 | /** Send UI update events to all windows. */ | |
1940 | wxUPDATE_UI_PROCESS_ALL, | |
23324ae1 | 1941 | |
42013f4c FM |
1942 | /** Send UI update events to windows that have |
1943 | the wxWS_EX_PROCESS_UI_UPDATES flag specified. */ | |
1944 | wxUPDATE_UI_PROCESS_SPECIFIED | |
1945 | }; | |
23324ae1 | 1946 | |
3c4f71cc | 1947 | |
42013f4c FM |
1948 | /** |
1949 | @class wxUpdateUIEvent | |
23324ae1 | 1950 | |
42013f4c FM |
1951 | This class is used for pseudo-events which are called by wxWidgets |
1952 | to give an application the chance to update various user interface elements. | |
23324ae1 | 1953 | |
42013f4c FM |
1954 | Without update UI events, an application has to work hard to check/uncheck, |
1955 | enable/disable, show/hide, and set the text for elements such as menu items | |
1956 | and toolbar buttons. The code for doing this has to be mixed up with the code | |
1957 | that is invoked when an action is invoked for a menu item or button. | |
3c4f71cc | 1958 | |
42013f4c FM |
1959 | With update UI events, you define an event handler to look at the state of the |
1960 | application and change UI elements accordingly. wxWidgets will call your member | |
1961 | functions in idle time, so you don't have to worry where to call this code. | |
23324ae1 | 1962 | |
42013f4c FM |
1963 | In addition to being a clearer and more declarative method, it also means you don't |
1964 | have to worry whether you're updating a toolbar or menubar identifier. The same | |
1965 | handler can update a menu item and toolbar button, if the identifier is the same. | |
1966 | Instead of directly manipulating the menu or button, you call functions in the event | |
1967 | object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a | |
1968 | call has been made, and which UI element to update. | |
23324ae1 | 1969 | |
42013f4c FM |
1970 | These events will work for popup menus as well as menubars. Just before a menu is |
1971 | popped up, wxMenu::UpdateUI is called to process any UI events for the window that | |
1972 | owns the menu. | |
23324ae1 | 1973 | |
42013f4c FM |
1974 | If you find that the overhead of UI update processing is affecting your application, |
1975 | you can do one or both of the following: | |
1976 | @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED, | |
1977 | and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should | |
1978 | receive update events. No other windows will receive update events. | |
1979 | @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay | |
1980 | between updates. You may need to call wxWindow::UpdateWindowUI at critical points, | |
1981 | for example when a dialog is about to be shown, in case the user sees a slight | |
1982 | delay before windows are updated. | |
3c4f71cc | 1983 | |
42013f4c FM |
1984 | Note that although events are sent in idle time, defining a wxIdleEvent handler |
1985 | for a window does not affect this because the events are sent from wxWindow::OnInternalIdle | |
1986 | which is always called in idle time. | |
23324ae1 | 1987 | |
42013f4c FM |
1988 | wxWidgets tries to optimize update events on some platforms. |
1989 | On Windows and GTK+, events for menubar items are only sent when the menu is about | |
1990 | to be shown, and not in idle time. | |
23324ae1 | 1991 | |
23324ae1 | 1992 | |
42013f4c | 1993 | @beginEventTable{wxUpdateUIEvent} |
8c6791e4 | 1994 | @event{EVT_UPDATE_UI(id, func)} |
3051a44a | 1995 | Process a @c wxEVT_UPDATE_UI event for the command with the given id. |
8c6791e4 | 1996 | @event{EVT_UPDATE_UI_RANGE(id1, id2, func)} |
3051a44a | 1997 | Process a @c wxEVT_UPDATE_UI event for any command with id included in the given range. |
42013f4c | 1998 | @endEventTable |
23324ae1 | 1999 | |
42013f4c FM |
2000 | @library{wxcore} |
2001 | @category{events} | |
23324ae1 | 2002 | |
3e083d65 | 2003 | @see @ref overview_events |
42013f4c FM |
2004 | */ |
2005 | class wxUpdateUIEvent : public wxCommandEvent | |
2006 | { | |
2007 | public: | |
23324ae1 | 2008 | /** |
42013f4c | 2009 | Constructor. |
23324ae1 | 2010 | */ |
42013f4c | 2011 | wxUpdateUIEvent(wxWindowID commandId = 0); |
23324ae1 FM |
2012 | |
2013 | /** | |
42013f4c FM |
2014 | Returns @true if it is appropriate to update (send UI update events to) |
2015 | this window. | |
23324ae1 | 2016 | |
42013f4c FM |
2017 | This function looks at the mode used (see wxUpdateUIEvent::SetMode), |
2018 | the wxWS_EX_PROCESS_UI_UPDATES flag in @a window, the time update events | |
2019 | were last sent in idle time, and the update interval, to determine whether | |
2020 | events should be sent to this window now. By default this will always | |
2021 | return @true because the update mode is initially wxUPDATE_UI_PROCESS_ALL | |
2022 | and the interval is set to 0; so update events will be sent as often as | |
2023 | possible. You can reduce the frequency that events are sent by changing the | |
2024 | mode and/or setting an update interval. | |
23324ae1 | 2025 | |
42013f4c | 2026 | @see ResetUpdateTime(), SetUpdateInterval(), SetMode() |
23324ae1 | 2027 | */ |
42013f4c | 2028 | static bool CanUpdate(wxWindow* window); |
23324ae1 FM |
2029 | |
2030 | /** | |
42013f4c | 2031 | Check or uncheck the UI element. |
23324ae1 | 2032 | */ |
42013f4c | 2033 | void Check(bool check); |
23324ae1 FM |
2034 | |
2035 | /** | |
42013f4c | 2036 | Enable or disable the UI element. |
23324ae1 | 2037 | */ |
42013f4c | 2038 | void Enable(bool enable); |
23324ae1 FM |
2039 | |
2040 | /** | |
42013f4c | 2041 | Returns @true if the UI element should be checked. |
23324ae1 | 2042 | */ |
42013f4c | 2043 | bool GetChecked() const; |
23324ae1 FM |
2044 | |
2045 | /** | |
42013f4c | 2046 | Returns @true if the UI element should be enabled. |
23324ae1 | 2047 | */ |
42013f4c | 2048 | bool GetEnabled() const; |
23324ae1 FM |
2049 | |
2050 | /** | |
42013f4c FM |
2051 | Static function returning a value specifying how wxWidgets will send update |
2052 | events: to all windows, or only to those which specify that they will process | |
2053 | the events. | |
23324ae1 | 2054 | |
42013f4c | 2055 | @see SetMode() |
23324ae1 | 2056 | */ |
42013f4c | 2057 | static wxUpdateUIMode GetMode(); |
23324ae1 FM |
2058 | |
2059 | /** | |
42013f4c FM |
2060 | Returns @true if the application has called Check(). |
2061 | For wxWidgets internal use only. | |
23324ae1 | 2062 | */ |
42013f4c | 2063 | bool GetSetChecked() const; |
23324ae1 FM |
2064 | |
2065 | /** | |
42013f4c FM |
2066 | Returns @true if the application has called Enable(). |
2067 | For wxWidgets internal use only. | |
23324ae1 | 2068 | */ |
42013f4c | 2069 | bool GetSetEnabled() const; |
23324ae1 FM |
2070 | |
2071 | /** | |
42013f4c FM |
2072 | Returns @true if the application has called Show(). |
2073 | For wxWidgets internal use only. | |
23324ae1 | 2074 | */ |
42013f4c | 2075 | bool GetSetShown() const; |
23324ae1 FM |
2076 | |
2077 | /** | |
42013f4c FM |
2078 | Returns @true if the application has called SetText(). |
2079 | For wxWidgets internal use only. | |
23324ae1 | 2080 | */ |
42013f4c | 2081 | bool GetSetText() const; |
23324ae1 FM |
2082 | |
2083 | /** | |
42013f4c | 2084 | Returns @true if the UI element should be shown. |
23324ae1 | 2085 | */ |
42013f4c | 2086 | bool GetShown() const; |
23324ae1 FM |
2087 | |
2088 | /** | |
42013f4c | 2089 | Returns the text that should be set for the UI element. |
23324ae1 | 2090 | */ |
42013f4c | 2091 | wxString GetText() const; |
23324ae1 FM |
2092 | |
2093 | /** | |
42013f4c FM |
2094 | Returns the current interval between updates in milliseconds. |
2095 | The value -1 disables updates, 0 updates as frequently as possible. | |
23324ae1 | 2096 | |
42013f4c | 2097 | @see SetUpdateInterval(). |
23324ae1 | 2098 | */ |
42013f4c | 2099 | static long GetUpdateInterval(); |
23324ae1 FM |
2100 | |
2101 | /** | |
42013f4c | 2102 | Used internally to reset the last-updated time to the current time. |
23324ae1 | 2103 | |
42013f4c FM |
2104 | It is assumed that update events are normally sent in idle time, so this |
2105 | is called at the end of idle processing. | |
23324ae1 | 2106 | |
42013f4c | 2107 | @see CanUpdate(), SetUpdateInterval(), SetMode() |
23324ae1 | 2108 | */ |
42013f4c | 2109 | static void ResetUpdateTime(); |
23324ae1 FM |
2110 | |
2111 | /** | |
42013f4c FM |
2112 | Specify how wxWidgets will send update events: to all windows, or only to |
2113 | those which specify that they will process the events. | |
23324ae1 | 2114 | |
42013f4c FM |
2115 | @param mode |
2116 | this parameter may be one of the ::wxUpdateUIMode enumeration values. | |
2117 | The default mode is wxUPDATE_UI_PROCESS_ALL. | |
23324ae1 | 2118 | */ |
42013f4c | 2119 | static void SetMode(wxUpdateUIMode mode); |
23324ae1 FM |
2120 | |
2121 | /** | |
42013f4c | 2122 | Sets the text for this UI element. |
23324ae1 | 2123 | */ |
42013f4c | 2124 | void SetText(const wxString& text); |
23324ae1 FM |
2125 | |
2126 | /** | |
42013f4c | 2127 | Sets the interval between updates in milliseconds. |
23324ae1 | 2128 | |
42013f4c FM |
2129 | Set to -1 to disable updates, or to 0 to update as frequently as possible. |
2130 | The default is 0. | |
23324ae1 | 2131 | |
42013f4c FM |
2132 | Use this to reduce the overhead of UI update events if your application |
2133 | has a lot of windows. If you set the value to -1 or greater than 0, | |
2134 | you may also need to call wxWindow::UpdateWindowUI at appropriate points | |
2135 | in your application, such as when a dialog is about to be shown. | |
23324ae1 | 2136 | */ |
42013f4c | 2137 | static void SetUpdateInterval(long updateInterval); |
23324ae1 FM |
2138 | |
2139 | /** | |
42013f4c | 2140 | Show or hide the UI element. |
23324ae1 | 2141 | */ |
42013f4c FM |
2142 | void Show(bool show); |
2143 | }; | |
23324ae1 FM |
2144 | |
2145 | ||
23324ae1 | 2146 | |
42013f4c FM |
2147 | /** |
2148 | @class wxClipboardTextEvent | |
23324ae1 | 2149 | |
42013f4c FM |
2150 | This class represents the events generated by a control (typically a |
2151 | wxTextCtrl but other windows can generate these events as well) when its | |
2152 | content gets copied or cut to, or pasted from the clipboard. | |
23324ae1 | 2153 | |
3a194bda SL |
2154 | There are three types of corresponding events @c wxEVT_COMMAND_TEXT_COPY, |
2155 | @c wxEVT_COMMAND_TEXT_CUT and @c wxEVT_COMMAND_TEXT_PASTE. | |
23324ae1 | 2156 | |
42013f4c FM |
2157 | If any of these events is processed (without being skipped) by an event |
2158 | handler, the corresponding operation doesn't take place which allows to | |
2159 | prevent the text from being copied from or pasted to a control. It is also | |
2160 | possible to examine the clipboard contents in the PASTE event handler and | |
2161 | transform it in some way before inserting in a control -- for example, | |
2162 | changing its case or removing invalid characters. | |
23324ae1 | 2163 | |
42013f4c FM |
2164 | Finally notice that a CUT event is always preceded by the COPY event which |
2165 | makes it possible to only process the latter if it doesn't matter if the | |
2166 | text was copied or cut. | |
23324ae1 | 2167 | |
42013f4c | 2168 | @note |
75aaa4c5 VZ |
2169 | These events are currently only generated by wxTextCtrl in wxGTK and wxOSX |
2170 | but are also generated by wxComboBox without wxCB_READONLY style in wxMSW. | |
23324ae1 | 2171 | |
42013f4c | 2172 | @beginEventTable{wxClipboardTextEvent} |
8c6791e4 | 2173 | @event{EVT_TEXT_COPY(id, func)} |
42013f4c | 2174 | Some or all of the controls content was copied to the clipboard. |
8c6791e4 | 2175 | @event{EVT_TEXT_CUT(id, func)} |
42013f4c FM |
2176 | Some or all of the controls content was cut (i.e. copied and |
2177 | deleted). | |
8c6791e4 | 2178 | @event{EVT_TEXT_PASTE(id, func)} |
42013f4c FM |
2179 | Clipboard content was pasted into the control. |
2180 | @endEventTable | |
23324ae1 | 2181 | |
23324ae1 | 2182 | |
42013f4c FM |
2183 | @library{wxcore} |
2184 | @category{events} | |
23324ae1 | 2185 | |
42013f4c FM |
2186 | @see wxClipboard |
2187 | */ | |
2188 | class wxClipboardTextEvent : public wxCommandEvent | |
2189 | { | |
2190 | public: | |
23324ae1 | 2191 | /** |
42013f4c | 2192 | Constructor. |
23324ae1 | 2193 | */ |
42013f4c | 2194 | wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
2195 | }; |
2196 | ||
41469c9e VZ |
2197 | /** |
2198 | Possible axis values for mouse wheel scroll events. | |
2199 | ||
2200 | @since 2.9.4 | |
2201 | */ | |
2202 | enum wxMouseWheelAxis | |
2203 | { | |
2204 | wxMOUSE_WHEEL_VERTICAL, ///< Vertical scroll event. | |
2205 | wxMOUSE_WHEEL_HORIZONTAL ///< Horizontal scroll event. | |
2206 | }; | |
23324ae1 | 2207 | |
e54c96f1 | 2208 | |
23324ae1 | 2209 | /** |
42013f4c | 2210 | @class wxMouseEvent |
7c913512 | 2211 | |
42013f4c FM |
2212 | This event class contains information about the events generated by the mouse: |
2213 | they include mouse buttons press and release events and mouse move events. | |
7c913512 | 2214 | |
42013f4c FM |
2215 | All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the |
2216 | left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and | |
2217 | @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more | |
2218 | buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events | |
2219 | can also be generated. Note that not all mice have even a middle button so a | |
2220 | portable application should avoid relying on the events from it (but the right | |
2221 | button click can be emulated using the left mouse button with the control key | |
2222 | under Mac platforms with a single button mouse). | |
2223 | ||
2224 | For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events | |
2225 | purposes, the mouse is considered to be inside the window if it is in the | |
2226 | window client area and not inside one of its children. In other words, the | |
2227 | parent window receives @c wxEVT_LEAVE_WINDOW event not only when the | |
2228 | mouse leaves the window entirely but also when it enters one of its children. | |
2229 | ||
92dbce73 VZ |
2230 | The position associated with a mouse event is expressed in the window |
2231 | coordinates of the window which generated the event, you can use | |
2232 | wxWindow::ClientToScreen() to convert it to screen coordinates and possibly | |
2233 | call wxWindow::ScreenToClient() next to convert it to window coordinates of | |
2234 | another window. | |
2235 | ||
42013f4c FM |
2236 | @note Note that under Windows CE mouse enter and leave events are not natively |
2237 | supported by the system but are generated by wxWidgets itself. This has several | |
2238 | drawbacks: the LEAVE_WINDOW event might be received some time after the mouse | |
2239 | left the window and the state variables for it may have changed during this time. | |
2240 | ||
2241 | @note Note the difference between methods like wxMouseEvent::LeftDown and | |
ab826fd8 VZ |
2242 | the inherited wxMouseState::LeftIsDown: the former returns @true when |
2243 | the event corresponds to the left mouse button click while the latter | |
2244 | returns @true if the left mouse button is currently being pressed. | |
2245 | For example, when the user is dragging the mouse you can use | |
2246 | wxMouseEvent::LeftIsDown to test whether the left mouse button is | |
2247 | (still) depressed. Also, by convention, if wxMouseEvent::LeftDown | |
2248 | returns @true, wxMouseEvent::LeftIsDown will also return @true in | |
2249 | wxWidgets whatever the underlying GUI behaviour is (which is | |
2250 | platform-dependent). The same applies, of course, to other mouse | |
2251 | buttons as well. | |
42013f4c FM |
2252 | |
2253 | ||
2254 | @beginEventTable{wxMouseEvent} | |
8c6791e4 | 2255 | @event{EVT_LEFT_DOWN(func)} |
3051a44a | 2256 | Process a @c wxEVT_LEFT_DOWN event. The handler of this event should normally |
42013f4c FM |
2257 | call event.Skip() to allow the default processing to take place as otherwise |
2258 | the window under mouse wouldn't get the focus. | |
8c6791e4 | 2259 | @event{EVT_LEFT_UP(func)} |
3051a44a | 2260 | Process a @c wxEVT_LEFT_UP event. |
8c6791e4 | 2261 | @event{EVT_LEFT_DCLICK(func)} |
3051a44a | 2262 | Process a @c wxEVT_LEFT_DCLICK event. |
8c6791e4 | 2263 | @event{EVT_MIDDLE_DOWN(func)} |
3051a44a | 2264 | Process a @c wxEVT_MIDDLE_DOWN event. |
8c6791e4 | 2265 | @event{EVT_MIDDLE_UP(func)} |
3051a44a | 2266 | Process a @c wxEVT_MIDDLE_UP event. |
8c6791e4 | 2267 | @event{EVT_MIDDLE_DCLICK(func)} |
3051a44a | 2268 | Process a @c wxEVT_MIDDLE_DCLICK event. |
8c6791e4 | 2269 | @event{EVT_RIGHT_DOWN(func)} |
3051a44a | 2270 | Process a @c wxEVT_RIGHT_DOWN event. |
8c6791e4 | 2271 | @event{EVT_RIGHT_UP(func)} |
3051a44a | 2272 | Process a @c wxEVT_RIGHT_UP event. |
8c6791e4 | 2273 | @event{EVT_RIGHT_DCLICK(func)} |
3051a44a | 2274 | Process a @c wxEVT_RIGHT_DCLICK event. |
8c6791e4 | 2275 | @event{EVT_MOUSE_AUX1_DOWN(func)} |
7f4f5e8c | 2276 | Process a @c wxEVT_AUX1_DOWN event. |
8c6791e4 | 2277 | @event{EVT_MOUSE_AUX1_UP(func)} |
7f4f5e8c | 2278 | Process a @c wxEVT_AUX1_UP event. |
8c6791e4 | 2279 | @event{EVT_MOUSE_AUX1_DCLICK(func)} |
7f4f5e8c | 2280 | Process a @c wxEVT_AUX1_DCLICK event. |
8c6791e4 | 2281 | @event{EVT_MOUSE_AUX2_DOWN(func)} |
7f4f5e8c | 2282 | Process a @c wxEVT_AUX2_DOWN event. |
8c6791e4 | 2283 | @event{EVT_MOUSE_AUX2_UP(func)} |
7f4f5e8c | 2284 | Process a @c wxEVT_AUX2_UP event. |
8c6791e4 | 2285 | @event{EVT_MOUSE_AUX2_DCLICK(func)} |
7f4f5e8c | 2286 | Process a @c wxEVT_AUX2_DCLICK event. |
8c6791e4 | 2287 | @event{EVT_MOTION(func)} |
3051a44a | 2288 | Process a @c wxEVT_MOTION event. |
8c6791e4 | 2289 | @event{EVT_ENTER_WINDOW(func)} |
3051a44a | 2290 | Process a @c wxEVT_ENTER_WINDOW event. |
8c6791e4 | 2291 | @event{EVT_LEAVE_WINDOW(func)} |
3051a44a | 2292 | Process a @c wxEVT_LEAVE_WINDOW event. |
8c6791e4 | 2293 | @event{EVT_MOUSEWHEEL(func)} |
3051a44a | 2294 | Process a @c wxEVT_MOUSEWHEEL event. |
8c6791e4 | 2295 | @event{EVT_MOUSE_EVENTS(func)} |
42013f4c FM |
2296 | Process all mouse events. |
2297 | @endEventTable | |
7c913512 | 2298 | |
23324ae1 FM |
2299 | @library{wxcore} |
2300 | @category{events} | |
7c913512 | 2301 | |
0e097789 | 2302 | @see wxKeyEvent |
23324ae1 | 2303 | */ |
0e097789 VZ |
2304 | class wxMouseEvent : public wxEvent, |
2305 | public wxMouseState | |
23324ae1 FM |
2306 | { |
2307 | public: | |
2308 | /** | |
42013f4c | 2309 | Constructor. Valid event types are: |
23324ae1 | 2310 | |
3a194bda SL |
2311 | @li @c wxEVT_ENTER_WINDOW |
2312 | @li @c wxEVT_LEAVE_WINDOW | |
2313 | @li @c wxEVT_LEFT_DOWN | |
2314 | @li @c wxEVT_LEFT_UP | |
2315 | @li @c wxEVT_LEFT_DCLICK | |
2316 | @li @c wxEVT_MIDDLE_DOWN | |
2317 | @li @c wxEVT_MIDDLE_UP | |
2318 | @li @c wxEVT_MIDDLE_DCLICK | |
2319 | @li @c wxEVT_RIGHT_DOWN | |
2320 | @li @c wxEVT_RIGHT_UP | |
2321 | @li @c wxEVT_RIGHT_DCLICK | |
31a9fc93 VZ |
2322 | @li @c wxEVT_AUX1_DOWN |
2323 | @li @c wxEVT_AUX1_UP | |
2324 | @li @c wxEVT_AUX1_DCLICK | |
2325 | @li @c wxEVT_AUX2_DOWN | |
2326 | @li @c wxEVT_AUX2_UP | |
2327 | @li @c wxEVT_AUX2_DCLICK | |
3a194bda SL |
2328 | @li @c wxEVT_MOTION |
2329 | @li @c wxEVT_MOUSEWHEEL | |
42013f4c FM |
2330 | */ |
2331 | wxMouseEvent(wxEventType mouseEventType = wxEVT_NULL); | |
23324ae1 | 2332 | |
23324ae1 | 2333 | /** |
42013f4c | 2334 | Returns @true if the event was a first extra button double click. |
23324ae1 | 2335 | */ |
42013f4c | 2336 | bool Aux1DClick() const; |
23324ae1 FM |
2337 | |
2338 | /** | |
42013f4c | 2339 | Returns @true if the first extra button mouse button changed to down. |
23324ae1 | 2340 | */ |
42013f4c | 2341 | bool Aux1Down() const; |
7c913512 | 2342 | |
23324ae1 | 2343 | /** |
42013f4c | 2344 | Returns @true if the first extra button mouse button changed to up. |
23324ae1 | 2345 | */ |
42013f4c | 2346 | bool Aux1Up() const; |
23324ae1 FM |
2347 | |
2348 | /** | |
42013f4c | 2349 | Returns @true if the event was a second extra button double click. |
23324ae1 | 2350 | */ |
42013f4c | 2351 | bool Aux2DClick() const; |
23324ae1 FM |
2352 | |
2353 | /** | |
42013f4c | 2354 | Returns @true if the second extra button mouse button changed to down. |
23324ae1 | 2355 | */ |
42013f4c | 2356 | bool Aux2Down() const; |
23324ae1 | 2357 | |
23324ae1 | 2358 | /** |
42013f4c | 2359 | Returns @true if the second extra button mouse button changed to up. |
23324ae1 | 2360 | */ |
42013f4c | 2361 | bool Aux2Up() const; |
23324ae1 FM |
2362 | |
2363 | /** | |
ab826fd8 | 2364 | Returns @true if the event was generated by the specified button. |
42013f4c | 2365 | |
ab826fd8 | 2366 | @see wxMouseState::ButtoinIsDown() |
23324ae1 | 2367 | */ |
ab826fd8 | 2368 | bool Button(wxMouseButton but) const; |
23324ae1 FM |
2369 | |
2370 | /** | |
42013f4c FM |
2371 | If the argument is omitted, this returns @true if the event was a mouse |
2372 | double click event. Otherwise the argument specifies which double click event | |
2373 | was generated (see Button() for the possible values). | |
23324ae1 | 2374 | */ |
ab826fd8 | 2375 | bool ButtonDClick(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 down event. Otherwise the argument specifies which button-down event | |
2380 | was generated (see Button() for the possible values). | |
23324ae1 | 2381 | */ |
ab826fd8 | 2382 | bool ButtonDown(wxMouseButton but = wxMOUSE_BTN_ANY) const; |
23324ae1 FM |
2383 | |
2384 | /** | |
42013f4c FM |
2385 | If the argument is omitted, this returns @true if the event was a mouse |
2386 | button up event. Otherwise the argument specifies which button-up event | |
2387 | was generated (see Button() for the possible values). | |
23324ae1 | 2388 | */ |
ab826fd8 | 2389 | bool ButtonUp(wxMouseButton but = wxMOUSE_BTN_ANY) const; |
23324ae1 | 2390 | |
23324ae1 | 2391 | /** |
42013f4c FM |
2392 | Returns @true if this was a dragging event (motion while a button is depressed). |
2393 | ||
2394 | @see Moving() | |
23324ae1 | 2395 | */ |
42013f4c | 2396 | bool Dragging() const; |
23324ae1 FM |
2397 | |
2398 | /** | |
42013f4c FM |
2399 | Returns @true if the mouse was entering the window. |
2400 | ||
2401 | @see Leaving() | |
23324ae1 | 2402 | */ |
42013f4c | 2403 | bool Entering() const; |
23324ae1 FM |
2404 | |
2405 | /** | |
42013f4c FM |
2406 | Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE |
2407 | if no button is involved (for mouse move, enter or leave event, for example). | |
2408 | Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and | |
2409 | double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT | |
2410 | for the same events for the middle and the right buttons respectively. | |
23324ae1 | 2411 | */ |
42013f4c | 2412 | int GetButton() const; |
e54c96f1 | 2413 | |
42013f4c FM |
2414 | /** |
2415 | Returns the number of mouse clicks for this event: 1 for a simple click, 2 | |
2416 | for a double-click, 3 for a triple-click and so on. | |
7c913512 | 2417 | |
42013f4c FM |
2418 | Currently this function is implemented only in wxMac and returns -1 for the |
2419 | other platforms (you can still distinguish simple clicks from double-clicks as | |
2420 | they generate different kinds of events however). | |
7c913512 | 2421 | |
1e24c2af | 2422 | @since 2.9.0 |
42013f4c FM |
2423 | */ |
2424 | int GetClickCount() const; | |
7c913512 | 2425 | |
23324ae1 | 2426 | /** |
42013f4c FM |
2427 | Returns the configured number of lines (or whatever) to be scrolled per |
2428 | wheel action. Defaults to three. | |
23324ae1 | 2429 | */ |
42013f4c | 2430 | int GetLinesPerAction() const; |
23324ae1 FM |
2431 | |
2432 | /** | |
42013f4c FM |
2433 | Returns the logical mouse position in pixels (i.e. translated according to the |
2434 | translation set for the DC, which usually indicates that the window has been | |
2435 | scrolled). | |
23324ae1 | 2436 | */ |
42013f4c | 2437 | wxPoint GetLogicalPosition(const wxDC& dc) const; |
23324ae1 | 2438 | |
42013f4c FM |
2439 | /** |
2440 | Get wheel delta, normally 120. | |
7c913512 | 2441 | |
42013f4c FM |
2442 | This is the threshold for action to be taken, and one such action |
2443 | (for example, scrolling one increment) should occur for each delta. | |
2444 | */ | |
2445 | int GetWheelDelta() const; | |
7c913512 | 2446 | |
42013f4c FM |
2447 | /** |
2448 | Get wheel rotation, positive or negative indicates direction of rotation. | |
7c913512 | 2449 | |
42013f4c FM |
2450 | Current devices all send an event when rotation is at least +/-WheelDelta, but |
2451 | finer resolution devices can be created in the future. | |
7c913512 | 2452 | |
42013f4c FM |
2453 | Because of this you shouldn't assume that one event is equal to 1 line, but you |
2454 | should be able to either do partial line scrolling or wait until several | |
2455 | events accumulate before scrolling. | |
23324ae1 | 2456 | */ |
42013f4c | 2457 | int GetWheelRotation() const; |
23324ae1 | 2458 | |
ec6278a1 | 2459 | /** |
41469c9e VZ |
2460 | Gets the axis the wheel operation concerns. |
2461 | ||
2462 | Usually the mouse wheel is used to scroll vertically so @c | |
2463 | wxMOUSE_WHEEL_VERTICAL is returned but some mice (and most trackpads) | |
2464 | also allow to use the wheel to scroll horizontally in which case | |
2465 | @c wxMOUSE_WHEEL_HORIZONTAL is returned. | |
ec6278a1 | 2466 | |
41469c9e | 2467 | Notice that before wxWidgets 2.9.4 this method returned @c int. |
ec6278a1 | 2468 | */ |
41469c9e | 2469 | wxMouseWheelAxis GetWheelAxis() const; |
ec6278a1 | 2470 | |
23324ae1 | 2471 | /** |
42013f4c FM |
2472 | Returns @true if the event was a mouse button event (not necessarily a button |
2473 | down event - that may be tested using ButtonDown()). | |
23324ae1 | 2474 | */ |
42013f4c | 2475 | bool IsButton() const; |
23324ae1 FM |
2476 | |
2477 | /** | |
42013f4c FM |
2478 | Returns @true if the system has been setup to do page scrolling with |
2479 | the mouse wheel instead of line scrolling. | |
23324ae1 | 2480 | */ |
42013f4c | 2481 | bool IsPageScroll() const; |
7c913512 | 2482 | |
42013f4c FM |
2483 | /** |
2484 | Returns @true if the mouse was leaving the window. | |
7c913512 | 2485 | |
42013f4c FM |
2486 | @see Entering(). |
2487 | */ | |
2488 | bool Leaving() const; | |
7c913512 | 2489 | |
23324ae1 | 2490 | /** |
42013f4c | 2491 | Returns @true if the event was a left double click. |
23324ae1 | 2492 | */ |
42013f4c | 2493 | bool LeftDClick() const; |
23324ae1 FM |
2494 | |
2495 | /** | |
42013f4c | 2496 | Returns @true if the left mouse button changed to down. |
23324ae1 | 2497 | */ |
42013f4c | 2498 | bool LeftDown() const; |
7c913512 | 2499 | |
42013f4c FM |
2500 | /** |
2501 | Returns @true if the left mouse button changed to up. | |
2502 | */ | |
2503 | bool LeftUp() const; | |
7c913512 | 2504 | |
23324ae1 | 2505 | /** |
42013f4c FM |
2506 | Returns @true if the Meta key was down at the time of the event. |
2507 | */ | |
2508 | bool MetaDown() const; | |
3c4f71cc | 2509 | |
42013f4c FM |
2510 | /** |
2511 | Returns @true if the event was a middle double click. | |
23324ae1 | 2512 | */ |
42013f4c | 2513 | bool MiddleDClick() const; |
23324ae1 FM |
2514 | |
2515 | /** | |
42013f4c | 2516 | Returns @true if the middle mouse button changed to down. |
23324ae1 | 2517 | */ |
42013f4c | 2518 | bool MiddleDown() const; |
23324ae1 | 2519 | |
42013f4c FM |
2520 | /** |
2521 | Returns @true if the middle mouse button changed to up. | |
2522 | */ | |
2523 | bool MiddleUp() const; | |
e54c96f1 | 2524 | |
42013f4c FM |
2525 | /** |
2526 | Returns @true if this was a motion event and no mouse buttons were pressed. | |
2527 | If any mouse button is held pressed, then this method returns @false and | |
2528 | Dragging() returns @true. | |
2529 | */ | |
2530 | bool Moving() const; | |
7c913512 | 2531 | |
42013f4c FM |
2532 | /** |
2533 | Returns @true if the event was a right double click. | |
2534 | */ | |
2535 | bool RightDClick() const; | |
7c913512 | 2536 | |
42013f4c FM |
2537 | /** |
2538 | Returns @true if the right mouse button changed to down. | |
2539 | */ | |
2540 | bool RightDown() const; | |
7c913512 | 2541 | |
42013f4c FM |
2542 | /** |
2543 | Returns @true if the right mouse button changed to up. | |
2544 | */ | |
2545 | bool RightUp() const; | |
23324ae1 FM |
2546 | }; |
2547 | ||
2548 | ||
e54c96f1 | 2549 | |
23324ae1 | 2550 | /** |
42013f4c | 2551 | @class wxDropFilesEvent |
7c913512 | 2552 | |
42013f4c FM |
2553 | This class is used for drop files events, that is, when files have been dropped |
2554 | onto the window. This functionality is currently only available under Windows. | |
7c913512 | 2555 | |
42013f4c FM |
2556 | The window must have previously been enabled for dropping by calling |
2557 | wxWindow::DragAcceptFiles(). | |
2558 | ||
2559 | Important note: this is a separate implementation to the more general drag and drop | |
2560 | implementation documented in the @ref overview_dnd. It uses the older, Windows | |
2561 | message-based approach of dropping files. | |
2562 | ||
2563 | @beginEventTable{wxDropFilesEvent} | |
8c6791e4 | 2564 | @event{EVT_DROP_FILES(func)} |
3051a44a | 2565 | Process a @c wxEVT_DROP_FILES event. |
42013f4c FM |
2566 | @endEventTable |
2567 | ||
2568 | @onlyfor{wxmsw} | |
7c913512 | 2569 | |
23324ae1 FM |
2570 | @library{wxcore} |
2571 | @category{events} | |
7c913512 | 2572 | |
3e083d65 | 2573 | @see @ref overview_events |
23324ae1 | 2574 | */ |
42013f4c | 2575 | class wxDropFilesEvent : public wxEvent |
23324ae1 FM |
2576 | { |
2577 | public: | |
2578 | /** | |
42013f4c | 2579 | Constructor. |
23324ae1 | 2580 | */ |
42013f4c FM |
2581 | wxDropFilesEvent(wxEventType id = 0, int noFiles = 0, |
2582 | wxString* files = NULL); | |
23324ae1 FM |
2583 | |
2584 | /** | |
42013f4c | 2585 | Returns an array of filenames. |
23324ae1 | 2586 | */ |
42013f4c | 2587 | wxString* GetFiles() const; |
23324ae1 FM |
2588 | |
2589 | /** | |
42013f4c | 2590 | Returns the number of files dropped. |
23324ae1 | 2591 | */ |
42013f4c | 2592 | int GetNumberOfFiles() const; |
23324ae1 FM |
2593 | |
2594 | /** | |
42013f4c FM |
2595 | Returns the position at which the files were dropped. |
2596 | Returns an array of filenames. | |
23324ae1 | 2597 | */ |
42013f4c | 2598 | wxPoint GetPosition() const; |
23324ae1 FM |
2599 | }; |
2600 | ||
2601 | ||
e54c96f1 | 2602 | |
23324ae1 | 2603 | /** |
42013f4c | 2604 | @class wxCommandEvent |
7c913512 | 2605 | |
42013f4c FM |
2606 | This event class contains information about command events, which originate |
2607 | from a variety of simple controls. | |
2608 | ||
3a567740 FM |
2609 | Note that wxCommandEvents and wxCommandEvent-derived event classes by default |
2610 | and unlike other wxEvent-derived classes propagate upward from the source | |
2611 | window (the window which emits the event) up to the first parent which processes | |
2612 | the event. Be sure to read @ref overview_events_propagation. | |
2613 | ||
42013f4c FM |
2614 | More complex controls, such as wxTreeCtrl, have separate command event classes. |
2615 | ||
2616 | @beginEventTable{wxCommandEvent} | |
8c6791e4 | 2617 | @event{EVT_COMMAND(id, event, func)} |
42013f4c FM |
2618 | Process a command, supplying the window identifier, command event identifier, |
2619 | and member function. | |
8c6791e4 | 2620 | @event{EVT_COMMAND_RANGE(id1, id2, event, func)} |
42013f4c FM |
2621 | Process a command for a range of window identifiers, supplying the minimum and |
2622 | maximum window identifiers, command event identifier, and member function. | |
8c6791e4 | 2623 | @event{EVT_BUTTON(id, func)} |
b476cde6 | 2624 | Process a @c wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control. |
8c6791e4 | 2625 | @event{EVT_CHECKBOX(id, func)} |
b476cde6 | 2626 | Process a @c wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control. |
8c6791e4 | 2627 | @event{EVT_CHOICE(id, func)} |
b476cde6 | 2628 | Process a @c wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control. |
8c6791e4 | 2629 | @event{EVT_COMBOBOX(id, func)} |
b476cde6 | 2630 | Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control. |
8c6791e4 | 2631 | @event{EVT_LISTBOX(id, func)} |
b476cde6 | 2632 | Process a @c wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control. |
8c6791e4 | 2633 | @event{EVT_LISTBOX_DCLICK(id, func)} |
b476cde6 | 2634 | Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control. |
51fbe4cc RR |
2635 | @event{EVT_CHECKLISTBOX(id, func)} |
2636 | Process a @c wxEVT_COMMAND_CHECKLISTBOX_TOGGLED command, which is generated by a wxCheckListBox control. | |
8c6791e4 | 2637 | @event{EVT_MENU(id, func)} |
b476cde6 | 2638 | Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item. |
8c6791e4 | 2639 | @event{EVT_MENU_RANGE(id1, id2, func)} |
b476cde6 | 2640 | Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items. |
8c6791e4 | 2641 | @event{EVT_CONTEXT_MENU(func)} |
42013f4c FM |
2642 | Process the event generated when the user has requested a popup menu to appear by |
2643 | pressing a special keyboard key (under Windows) or by right clicking the mouse. | |
8c6791e4 | 2644 | @event{EVT_RADIOBOX(id, func)} |
b476cde6 | 2645 | Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control. |
8c6791e4 | 2646 | @event{EVT_RADIOBUTTON(id, func)} |
b476cde6 | 2647 | Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control. |
8c6791e4 | 2648 | @event{EVT_SCROLLBAR(id, func)} |
b476cde6 | 2649 | Process a @c wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar |
42013f4c FM |
2650 | control. This is provided for compatibility only; more specific scrollbar event macros |
2651 | should be used instead (see wxScrollEvent). | |
8c6791e4 | 2652 | @event{EVT_SLIDER(id, func)} |
b476cde6 | 2653 | Process a @c wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control. |
8c6791e4 | 2654 | @event{EVT_TEXT(id, func)} |
b476cde6 | 2655 | Process a @c wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control. |
8c6791e4 | 2656 | @event{EVT_TEXT_ENTER(id, func)} |
b476cde6 | 2657 | Process a @c wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control. |
42013f4c FM |
2658 | Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it |
2659 | to generate such events. | |
8c6791e4 | 2660 | @event{EVT_TEXT_MAXLEN(id, func)} |
b476cde6 | 2661 | Process a @c wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control |
42013f4c FM |
2662 | when the user tries to enter more characters into it than the limit previously set |
2663 | with SetMaxLength(). | |
8c6791e4 | 2664 | @event{EVT_TOGGLEBUTTON(id, func)} |
b476cde6 | 2665 | Process a @c wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event. |
8c6791e4 | 2666 | @event{EVT_TOOL(id, func)} |
b476cde6 | 2667 | Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c wxEVT_COMMAND_MENU_SELECTED). |
42013f4c | 2668 | Pass the id of the tool. |
8c6791e4 | 2669 | @event{EVT_TOOL_RANGE(id1, id2, func)} |
b476cde6 | 2670 | Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools. |
8c6791e4 | 2671 | @event{EVT_TOOL_RCLICKED(id, func)} |
e431dd05 | 2672 | Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool. (Not available on wxOSX.) |
8c6791e4 | 2673 | @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)} |
e431dd05 | 2674 | Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. (Not available on wxOSX.) |
8c6791e4 | 2675 | @event{EVT_TOOL_ENTER(id, func)} |
b476cde6 | 2676 | Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself. |
42013f4c | 2677 | The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor |
e431dd05 | 2678 | has moved off a tool. (Not available on wxOSX.) |
8c6791e4 | 2679 | @event{EVT_COMMAND_LEFT_CLICK(id, func)} |
b476cde6 | 2680 | Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only). |
8c6791e4 | 2681 | @event{EVT_COMMAND_LEFT_DCLICK(id, func)} |
b476cde6 | 2682 | Process a @c wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only). |
8c6791e4 | 2683 | @event{EVT_COMMAND_RIGHT_CLICK(id, func)} |
b476cde6 | 2684 | Process a @c wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only). |
8c6791e4 | 2685 | @event{EVT_COMMAND_SET_FOCUS(id, func)} |
b476cde6 | 2686 | Process a @c wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only). |
8c6791e4 | 2687 | @event{EVT_COMMAND_KILL_FOCUS(id, func)} |
b476cde6 | 2688 | Process a @c wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only). |
8c6791e4 | 2689 | @event{EVT_COMMAND_ENTER(id, func)} |
b476cde6 | 2690 | Process a @c wxEVT_COMMAND_ENTER command, which is generated by a control. |
42013f4c | 2691 | @endEventTable |
7c913512 | 2692 | |
23324ae1 | 2693 | @library{wxcore} |
1f1d2182 | 2694 | @category{events} |
23324ae1 | 2695 | */ |
42013f4c | 2696 | class wxCommandEvent : public wxEvent |
23324ae1 FM |
2697 | { |
2698 | public: | |
2699 | /** | |
2700 | Constructor. | |
2701 | */ | |
408776d0 | 2702 | wxCommandEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
2703 | |
2704 | /** | |
42013f4c FM |
2705 | Returns client data pointer for a listbox or choice selection event |
2706 | (not valid for a deselection). | |
2707 | */ | |
2708 | void* GetClientData() const; | |
3c4f71cc | 2709 | |
42013f4c FM |
2710 | /** |
2711 | Returns client object pointer for a listbox or choice selection event | |
2712 | (not valid for a deselection). | |
2713 | */ | |
2714 | wxClientData* GetClientObject() const; | |
3c4f71cc | 2715 | |
42013f4c | 2716 | /** |
8cddee2d | 2717 | Returns extra information dependent on the event objects type. |
3c4f71cc | 2718 | |
42013f4c FM |
2719 | If the event comes from a listbox selection, it is a boolean |
2720 | determining whether the event was a selection (@true) or a | |
2721 | deselection (@false). A listbox deselection only occurs for | |
2722 | multiple-selection boxes, and in this case the index and string values | |
2723 | are indeterminate and the listbox must be examined by the application. | |
2724 | */ | |
2725 | long GetExtraLong() const; | |
3c4f71cc | 2726 | |
42013f4c FM |
2727 | /** |
2728 | Returns the integer identifier corresponding to a listbox, choice or | |
2729 | radiobox selection (only if the event was a selection, not a deselection), | |
2730 | or a boolean value representing the value of a checkbox. | |
e23e368b VZ |
2731 | |
2732 | For a menu item, this method returns -1 if the item is not checkable or | |
2733 | a boolean value (true or false) for checkable items indicating the new | |
2734 | state of the item. | |
42013f4c FM |
2735 | */ |
2736 | int GetInt() const; | |
3c4f71cc | 2737 | |
42013f4c FM |
2738 | /** |
2739 | Returns item index for a listbox or choice selection event (not valid for | |
2740 | a deselection). | |
23324ae1 | 2741 | */ |
42013f4c | 2742 | int GetSelection() const; |
23324ae1 FM |
2743 | |
2744 | /** | |
85339748 RR |
2745 | Returns item string for a listbox or choice selection event. If one |
2746 | or several items have been deselected, returns the index of the first | |
2747 | deselected item. If some items have been selected and others deselected | |
2748 | at the same time, it will return the index of the first selected item. | |
23324ae1 | 2749 | */ |
42013f4c | 2750 | wxString GetString() const; |
23324ae1 FM |
2751 | |
2752 | /** | |
42013f4c FM |
2753 | This method can be used with checkbox and menu events: for the checkboxes, the |
2754 | method returns @true for a selection event and @false for a deselection one. | |
2755 | For the menu events, this method indicates if the menu item just has become | |
2756 | checked or unchecked (and thus only makes sense for checkable menu items). | |
3c4f71cc | 2757 | |
57ab6f23 | 2758 | Notice that this method cannot be used with wxCheckListBox currently. |
23324ae1 | 2759 | */ |
42013f4c | 2760 | bool IsChecked() const; |
23324ae1 FM |
2761 | |
2762 | /** | |
85339748 RR |
2763 | For a listbox or similar event, returns @true if it is a selection, @false |
2764 | if it is a deselection. If some items have been selected and others deselected | |
2765 | at the same time, it will return @true. | |
23324ae1 | 2766 | */ |
42013f4c | 2767 | bool IsSelection() const; |
e54c96f1 | 2768 | |
42013f4c FM |
2769 | /** |
2770 | Sets the client data for this event. | |
2771 | */ | |
2772 | void SetClientData(void* clientData); | |
7c913512 | 2773 | |
42013f4c FM |
2774 | /** |
2775 | Sets the client object for this event. The client object is not owned by the | |
2776 | event object and the event object will not delete the client object in its destructor. | |
7c913512 | 2777 | |
42013f4c FM |
2778 | The client object must be owned and deleted by another object (e.g. a control) |
2779 | that has longer life time than the event object. | |
2780 | */ | |
2781 | void SetClientObject(wxClientData* clientObject); | |
7c913512 | 2782 | |
23324ae1 | 2783 | /** |
42013f4c | 2784 | Sets the @b m_extraLong member. |
23324ae1 | 2785 | */ |
42013f4c | 2786 | void SetExtraLong(long extraLong); |
23324ae1 FM |
2787 | |
2788 | /** | |
42013f4c | 2789 | Sets the @b m_commandInt member. |
23324ae1 | 2790 | */ |
42013f4c | 2791 | void SetInt(int intCommand); |
23324ae1 FM |
2792 | |
2793 | /** | |
42013f4c | 2794 | Sets the @b m_commandString member. |
23324ae1 | 2795 | */ |
42013f4c | 2796 | void SetString(const wxString& string); |
23324ae1 FM |
2797 | }; |
2798 | ||
2799 | ||
e54c96f1 | 2800 | |
23324ae1 | 2801 | /** |
42013f4c | 2802 | @class wxActivateEvent |
7c913512 | 2803 | |
42013f4c FM |
2804 | An activate event is sent when a window or application is being activated |
2805 | or deactivated. | |
7c913512 | 2806 | |
42013f4c | 2807 | @beginEventTable{wxActivateEvent} |
8c6791e4 | 2808 | @event{EVT_ACTIVATE(func)} |
3051a44a | 2809 | Process a @c wxEVT_ACTIVATE event. |
8c6791e4 | 2810 | @event{EVT_ACTIVATE_APP(func)} |
3051a44a FM |
2811 | Process a @c wxEVT_ACTIVATE_APP event. |
2812 | This event is received by the wxApp-derived instance only. | |
8c6791e4 | 2813 | @event{EVT_HIBERNATE(func)} |
42013f4c FM |
2814 | Process a hibernate event, supplying the member function. This event applies |
2815 | to wxApp only, and only on Windows SmartPhone and PocketPC. | |
2816 | It is generated when the system is low on memory; the application should free | |
2817 | up as much memory as possible, and restore full working state when it receives | |
3a194bda | 2818 | a @c wxEVT_ACTIVATE or @c wxEVT_ACTIVATE_APP event. |
42013f4c FM |
2819 | @endEventTable |
2820 | ||
42013f4c | 2821 | @library{wxcore} |
23324ae1 | 2822 | @category{events} |
7c913512 | 2823 | |
3e083d65 | 2824 | @see @ref overview_events, wxApp::IsActive |
23324ae1 | 2825 | */ |
42013f4c | 2826 | class wxActivateEvent : public wxEvent |
23324ae1 FM |
2827 | { |
2828 | public: | |
2829 | /** | |
2830 | Constructor. | |
2831 | */ | |
42013f4c FM |
2832 | wxActivateEvent(wxEventType eventType = wxEVT_NULL, bool active = true, |
2833 | int id = 0); | |
23324ae1 FM |
2834 | |
2835 | /** | |
42013f4c | 2836 | Returns @true if the application or window is being activated, @false otherwise. |
23324ae1 | 2837 | */ |
42013f4c | 2838 | bool GetActive() const; |
23324ae1 FM |
2839 | }; |
2840 | ||
2841 | ||
e54c96f1 | 2842 | |
23324ae1 | 2843 | /** |
42013f4c | 2844 | @class wxContextMenuEvent |
7c913512 | 2845 | |
42013f4c | 2846 | This class is used for context menu events, sent to give |
3051a44a | 2847 | the application a chance to show a context (popup) menu for a wxWindow. |
42013f4c FM |
2848 | |
2849 | Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this | |
2850 | means that the event originated from a keyboard context button event, and you | |
2851 | should compute a suitable position yourself, for example by calling wxGetMousePosition(). | |
2852 | ||
2853 | When a keyboard context menu button is pressed on Windows, a right-click event | |
2854 | with default position is sent first, and if this event is not processed, the | |
2855 | context menu event is sent. So if you process mouse events and you find your | |
2856 | context menu event handler is not being called, you could call wxEvent::Skip() | |
2857 | for mouse right-down events. | |
2858 | ||
2859 | @beginEventTable{wxContextMenuEvent} | |
8c6791e4 | 2860 | @event{EVT_CONTEXT_MENU(func)} |
42013f4c FM |
2861 | A right click (or other context menu command depending on platform) has been detected. |
2862 | @endEventTable | |
2863 | ||
7c913512 | 2864 | |
23324ae1 FM |
2865 | @library{wxcore} |
2866 | @category{events} | |
7c913512 | 2867 | |
3e083d65 | 2868 | @see wxCommandEvent, @ref overview_events |
23324ae1 | 2869 | */ |
42013f4c | 2870 | class wxContextMenuEvent : public wxCommandEvent |
23324ae1 FM |
2871 | { |
2872 | public: | |
2873 | /** | |
2874 | Constructor. | |
2875 | */ | |
a90e69f7 | 2876 | wxContextMenuEvent(wxEventType type = wxEVT_NULL, int id = 0, |
42013f4c FM |
2877 | const wxPoint& pos = wxDefaultPosition); |
2878 | ||
2879 | /** | |
2880 | Returns the position in screen coordinates at which the menu should be shown. | |
2881 | Use wxWindow::ScreenToClient to convert to client coordinates. | |
2882 | ||
2883 | You can also omit a position from wxWindow::PopupMenu in order to use | |
2884 | the current mouse pointer position. | |
2885 | ||
2886 | If the event originated from a keyboard event, the value returned from this | |
2887 | function will be wxDefaultPosition. | |
2888 | */ | |
2889 | const wxPoint& GetPosition() const; | |
2890 | ||
2891 | /** | |
2892 | Sets the position at which the menu should be shown. | |
2893 | */ | |
2894 | void SetPosition(const wxPoint& point); | |
23324ae1 FM |
2895 | }; |
2896 | ||
2897 | ||
e54c96f1 | 2898 | |
23324ae1 | 2899 | /** |
42013f4c | 2900 | @class wxEraseEvent |
7c913512 | 2901 | |
42013f4c | 2902 | An erase event is sent when a window's background needs to be repainted. |
7c913512 | 2903 | |
42013f4c FM |
2904 | On some platforms, such as GTK+, this event is simulated (simply generated just |
2905 | before the paint event) and may cause flicker. It is therefore recommended that | |
2906 | you set the text background colour explicitly in order to prevent flicker. | |
2907 | The default background colour under GTK+ is grey. | |
2908 | ||
2909 | To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table | |
2910 | definition. | |
2911 | ||
5fafec4d VZ |
2912 | You must use the device context returned by GetDC() to draw on, don't create |
2913 | a wxPaintDC in the event handler. | |
7c913512 | 2914 | |
42013f4c | 2915 | @beginEventTable{wxEraseEvent} |
8c6791e4 | 2916 | @event{EVT_ERASE_BACKGROUND(func)} |
3051a44a | 2917 | Process a @c wxEVT_ERASE_BACKGROUND event. |
42013f4c | 2918 | @endEventTable |
7c913512 | 2919 | |
23324ae1 FM |
2920 | @library{wxcore} |
2921 | @category{events} | |
7c913512 | 2922 | |
3e083d65 | 2923 | @see @ref overview_events |
23324ae1 | 2924 | */ |
42013f4c | 2925 | class wxEraseEvent : public wxEvent |
23324ae1 FM |
2926 | { |
2927 | public: | |
2928 | /** | |
2929 | Constructor. | |
2930 | */ | |
42013f4c FM |
2931 | wxEraseEvent(int id = 0, wxDC* dc = NULL); |
2932 | ||
2933 | /** | |
2934 | Returns the device context associated with the erase event to draw on. | |
5fafec4d VZ |
2935 | |
2936 | The returned pointer is never @NULL. | |
42013f4c FM |
2937 | */ |
2938 | wxDC* GetDC() const; | |
23324ae1 FM |
2939 | }; |
2940 | ||
2941 | ||
e54c96f1 | 2942 | |
23324ae1 | 2943 | /** |
42013f4c | 2944 | @class wxFocusEvent |
7c913512 | 2945 | |
42013f4c FM |
2946 | A focus event is sent when a window's focus changes. The window losing focus |
2947 | receives a "kill focus" event while the window gaining it gets a "set focus" one. | |
7c913512 | 2948 | |
42013f4c FM |
2949 | Notice that the set focus event happens both when the user gives focus to the |
2950 | window (whether using the mouse or keyboard) and when it is done from the | |
2951 | program itself using wxWindow::SetFocus. | |
2952 | ||
9a25f336 VZ |
2953 | The focus event handlers should almost invariably call wxEvent::Skip() on |
2954 | their event argument to allow the default handling to take place. Failure | |
2955 | to do this may result in incorrect behaviour of the native controls. Also | |
2956 | note that wxEVT_KILL_FOCUS handler must not call wxWindow::SetFocus() as | |
2957 | this, again, is not supported by all native controls. If you need to do | |
2958 | this, consider using the @ref sec_delayed_action described in wxIdleEvent | |
2959 | documentation. | |
2960 | ||
42013f4c | 2961 | @beginEventTable{wxFocusEvent} |
8c6791e4 | 2962 | @event{EVT_SET_FOCUS(func)} |
3051a44a | 2963 | Process a @c wxEVT_SET_FOCUS event. |
8c6791e4 | 2964 | @event{EVT_KILL_FOCUS(func)} |
3051a44a | 2965 | Process a @c wxEVT_KILL_FOCUS event. |
42013f4c | 2966 | @endEventTable |
7c913512 | 2967 | |
23324ae1 FM |
2968 | @library{wxcore} |
2969 | @category{events} | |
7c913512 | 2970 | |
3e083d65 | 2971 | @see @ref overview_events |
23324ae1 | 2972 | */ |
42013f4c | 2973 | class wxFocusEvent : public wxEvent |
23324ae1 FM |
2974 | { |
2975 | public: | |
23324ae1 FM |
2976 | /** |
2977 | Constructor. | |
2978 | */ | |
42013f4c | 2979 | wxFocusEvent(wxEventType eventType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
2980 | |
2981 | /** | |
42013f4c FM |
2982 | Returns the window associated with this event, that is the window which had the |
2983 | focus before for the @c wxEVT_SET_FOCUS event and the window which is | |
2984 | going to receive focus for the @c wxEVT_KILL_FOCUS one. | |
23324ae1 | 2985 | |
42013f4c | 2986 | Warning: the window pointer may be @NULL! |
23324ae1 | 2987 | */ |
42013f4c | 2988 | wxWindow *GetWindow() const; |
a90e69f7 RD |
2989 | |
2990 | void SetWindow(wxWindow *win); | |
42013f4c | 2991 | }; |
23324ae1 | 2992 | |
23324ae1 | 2993 | |
23324ae1 | 2994 | |
42013f4c FM |
2995 | /** |
2996 | @class wxChildFocusEvent | |
23324ae1 | 2997 | |
42013f4c FM |
2998 | A child focus event is sent to a (parent-)window when one of its child windows |
2999 | gains focus, so that the window could restore the focus back to its corresponding | |
3000 | child if it loses it now and regains later. | |
23324ae1 | 3001 | |
42013f4c | 3002 | Notice that child window is the direct child of the window receiving event. |
57ab6f23 | 3003 | Use wxWindow::FindFocus() to retrieve the window which is actually getting focus. |
42013f4c FM |
3004 | |
3005 | @beginEventTable{wxChildFocusEvent} | |
8c6791e4 | 3006 | @event{EVT_CHILD_FOCUS(func)} |
3051a44a | 3007 | Process a @c wxEVT_CHILD_FOCUS event. |
42013f4c FM |
3008 | @endEventTable |
3009 | ||
3010 | @library{wxcore} | |
3011 | @category{events} | |
23324ae1 | 3012 | |
3e083d65 | 3013 | @see @ref overview_events |
42013f4c FM |
3014 | */ |
3015 | class wxChildFocusEvent : public wxCommandEvent | |
3016 | { | |
3017 | public: | |
23324ae1 | 3018 | /** |
42013f4c FM |
3019 | Constructor. |
3020 | ||
3021 | @param win | |
3022 | The direct child which is (or which contains the window which is) receiving | |
3023 | the focus. | |
23324ae1 | 3024 | */ |
42013f4c | 3025 | wxChildFocusEvent(wxWindow* win = NULL); |
23324ae1 FM |
3026 | |
3027 | /** | |
42013f4c FM |
3028 | Returns the direct child which receives the focus, or a (grand-)parent of the |
3029 | control receiving the focus. | |
3030 | ||
3031 | To get the actually focused control use wxWindow::FindFocus. | |
23324ae1 | 3032 | */ |
42013f4c | 3033 | wxWindow *GetWindow() const; |
23324ae1 FM |
3034 | }; |
3035 | ||
3036 | ||
e54c96f1 | 3037 | |
23324ae1 | 3038 | /** |
42013f4c | 3039 | @class wxMouseCaptureLostEvent |
7c913512 | 3040 | |
0af4bd16 VZ |
3041 | A mouse capture lost event is sent to a window that had obtained mouse capture, |
3042 | which was subsequently lost due to an "external" event (for example, when a dialog | |
3043 | box is shown or if another application captures the mouse). | |
42013f4c | 3044 | |
0af4bd16 | 3045 | If this happens, this event is sent to all windows that are on the capture stack |
42013f4c FM |
3046 | (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is |
3047 | not sent if the capture changes because of a call to CaptureMouse or | |
3048 | ReleaseMouse. | |
3049 | ||
3050 | This event is currently emitted under Windows only. | |
3051 | ||
3052 | @beginEventTable{wxMouseCaptureLostEvent} | |
8c6791e4 | 3053 | @event{EVT_MOUSE_CAPTURE_LOST(func)} |
3051a44a | 3054 | Process a @c wxEVT_MOUSE_CAPTURE_LOST event. |
42013f4c | 3055 | @endEventTable |
7c913512 | 3056 | |
42013f4c | 3057 | @onlyfor{wxmsw} |
7c913512 | 3058 | |
23324ae1 FM |
3059 | @library{wxcore} |
3060 | @category{events} | |
7c913512 | 3061 | |
3e083d65 | 3062 | @see wxMouseCaptureChangedEvent, @ref overview_events, |
3051a44a | 3063 | wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture |
23324ae1 | 3064 | */ |
42013f4c | 3065 | class wxMouseCaptureLostEvent : public wxEvent |
23324ae1 FM |
3066 | { |
3067 | public: | |
3068 | /** | |
3069 | Constructor. | |
3070 | */ | |
42013f4c | 3071 | wxMouseCaptureLostEvent(wxWindowID windowId = 0); |
23324ae1 FM |
3072 | }; |
3073 | ||
3074 | ||
e54c96f1 | 3075 | |
a90e69f7 RD |
3076 | class wxDisplayChangedEvent : public wxEvent |
3077 | { | |
3078 | public: | |
3079 | wxDisplayChangedEvent(); | |
3080 | }; | |
3081 | ||
3082 | ||
3083 | class wxPaletteChangedEvent : public wxEvent | |
3084 | { | |
3085 | public: | |
3086 | wxPaletteChangedEvent(wxWindowID winid = 0); | |
3087 | ||
3088 | void SetChangedWindow(wxWindow* win); | |
3089 | wxWindow* GetChangedWindow() const; | |
3090 | }; | |
3091 | ||
3092 | ||
3093 | class wxQueryNewPaletteEvent : public wxEvent | |
3094 | { | |
3095 | public: | |
3096 | wxQueryNewPaletteEvent(wxWindowID winid = 0); | |
3097 | ||
3098 | void SetPaletteRealized(bool realized); | |
3099 | bool GetPaletteRealized(); | |
3100 | }; | |
3101 | ||
3102 | ||
3103 | ||
3104 | ||
23324ae1 | 3105 | /** |
42013f4c | 3106 | @class wxNotifyEvent |
7c913512 | 3107 | |
42013f4c | 3108 | This class is not used by the event handlers by itself, but is a base class |
3e97a905 | 3109 | for other event classes (such as wxBookCtrlEvent). |
7c913512 | 3110 | |
42013f4c FM |
3111 | It (or an object of a derived class) is sent when the controls state is being |
3112 | changed and allows the program to wxNotifyEvent::Veto() this change if it wants | |
3113 | to prevent it from happening. | |
7c913512 | 3114 | |
23324ae1 FM |
3115 | @library{wxcore} |
3116 | @category{events} | |
7c913512 | 3117 | |
3e97a905 | 3118 | @see wxBookCtrlEvent |
23324ae1 | 3119 | */ |
42013f4c | 3120 | class wxNotifyEvent : public wxCommandEvent |
23324ae1 FM |
3121 | { |
3122 | public: | |
3123 | /** | |
42013f4c | 3124 | Constructor (used internally by wxWidgets only). |
23324ae1 | 3125 | */ |
42013f4c | 3126 | wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
3127 | |
3128 | /** | |
42013f4c FM |
3129 | This is the opposite of Veto(): it explicitly allows the event to be processed. |
3130 | For most events it is not necessary to call this method as the events are allowed | |
3131 | anyhow but some are forbidden by default (this will be mentioned in the corresponding | |
3132 | event description). | |
23324ae1 | 3133 | */ |
42013f4c | 3134 | void Allow(); |
23324ae1 FM |
3135 | |
3136 | /** | |
42013f4c FM |
3137 | Returns @true if the change is allowed (Veto() hasn't been called) or @false |
3138 | otherwise (if it was). | |
23324ae1 | 3139 | */ |
42013f4c | 3140 | bool IsAllowed() const; |
23324ae1 FM |
3141 | |
3142 | /** | |
42013f4c | 3143 | Prevents the change announced by this event from happening. |
23324ae1 | 3144 | |
42013f4c FM |
3145 | It is in general a good idea to notify the user about the reasons for vetoing |
3146 | the change because otherwise the applications behaviour (which just refuses to | |
3147 | do what the user wants) might be quite surprising. | |
23324ae1 | 3148 | */ |
42013f4c FM |
3149 | void Veto(); |
3150 | }; | |
3151 | ||
23324ae1 | 3152 | |
d48b06bd FM |
3153 | /** |
3154 | @class wxThreadEvent | |
23324ae1 | 3155 | |
5d4a0504 VZ |
3156 | This class adds some simple functionality to wxEvent to facilitate |
3157 | inter-thread communication. | |
23324ae1 | 3158 | |
5d4a0504 VZ |
3159 | This event is not natively emitted by any control/class: it is just |
3160 | a helper class for the user. | |
3a567740 | 3161 | Its most important feature is the GetEventCategory() implementation which |
5d4a0504 | 3162 | allows thread events @b NOT to be processed by wxEventLoopBase::YieldFor calls |
3a567740 FM |
3163 | (unless the @c wxEVT_CATEGORY_THREAD is specified - which is never in wx code). |
3164 | ||
d48b06bd | 3165 | @library{wxcore} |
3c99e2fd | 3166 | @category{events,threading} |
d48b06bd | 3167 | |
dde19c21 | 3168 | @see @ref overview_thread, wxEventLoopBase::YieldFor |
c1b293bb VS |
3169 | |
3170 | @since 2.9.0 | |
d48b06bd | 3171 | */ |
c1b293bb | 3172 | class wxThreadEvent : public wxEvent |
42013f4c | 3173 | { |
d48b06bd FM |
3174 | public: |
3175 | /** | |
3176 | Constructor. | |
d48b06bd | 3177 | */ |
c1b293bb | 3178 | wxThreadEvent(wxEventType eventType = wxEVT_THREAD, int id = wxID_ANY); |
23324ae1 | 3179 | |
d48b06bd FM |
3180 | /** |
3181 | Clones this event making sure that all internal members which use | |
3182 | COW (only @c m_commandString for now; see @ref overview_refcount) | |
3183 | are unshared (see wxObject::UnShare). | |
3184 | */ | |
3185 | virtual wxEvent *Clone() const; | |
3186 | ||
3187 | /** | |
3188 | Returns @c wxEVT_CATEGORY_THREAD. | |
3189 | ||
74d60f66 | 3190 | This is important to avoid unwanted processing of thread events |
dde19c21 | 3191 | when calling wxEventLoopBase::YieldFor(). |
d48b06bd FM |
3192 | */ |
3193 | virtual wxEventCategory GetEventCategory() const; | |
dae60aee VS |
3194 | |
3195 | /** | |
3196 | Sets custom data payload. | |
3197 | ||
3198 | The @a payload argument may be of any type that wxAny can handle | |
3199 | (i.e. pretty much anything). Note that T's copy constructor must be | |
3200 | thread-safe, i.e. create a copy that doesn't share anything with | |
3201 | the original (see Clone()). | |
3202 | ||
3203 | @note This method is not available with Visual C++ 6. | |
3204 | ||
3205 | @since 2.9.1 | |
3206 | ||
3207 | @see GetPayload(), wxAny | |
3208 | */ | |
3209 | template<typename T> | |
3210 | void SetPayload(const T& payload); | |
3211 | ||
3212 | /** | |
3213 | Get custom data payload. | |
3214 | ||
3215 | Correct type is checked in debug builds. | |
3216 | ||
3217 | @note This method is not available with Visual C++ 6. | |
3218 | ||
3219 | @since 2.9.1 | |
3220 | ||
3221 | @see SetPayload(), wxAny | |
3222 | */ | |
3223 | template<typename T> | |
3224 | T GetPayload() const; | |
c1b293bb VS |
3225 | |
3226 | /** | |
3227 | Returns extra information integer value. | |
3228 | */ | |
3229 | long GetExtraLong() const; | |
3230 | ||
3231 | /** | |
3232 | Returns stored integer value. | |
3233 | */ | |
3234 | int GetInt() const; | |
3235 | ||
3236 | /** | |
3237 | Returns stored string value. | |
3238 | */ | |
3239 | wxString GetString() const; | |
3240 | ||
3241 | ||
3242 | /** | |
3243 | Sets the extra information value. | |
3244 | */ | |
3245 | void SetExtraLong(long extraLong); | |
3246 | ||
3247 | /** | |
3248 | Sets the integer value. | |
3249 | */ | |
3250 | void SetInt(int intCommand); | |
3251 | ||
3252 | /** | |
3253 | Sets the string value. | |
3254 | */ | |
3255 | void SetString(const wxString& string); | |
42013f4c | 3256 | }; |
e54c96f1 | 3257 | |
d48b06bd | 3258 | |
23324ae1 | 3259 | /** |
42013f4c | 3260 | @class wxHelpEvent |
7c913512 | 3261 | |
42013f4c FM |
3262 | A help event is sent when the user has requested context-sensitive help. |
3263 | This can either be caused by the application requesting context-sensitive help mode | |
3264 | via wxContextHelp, or (on MS Windows) by the system generating a WM_HELP message when | |
3265 | the user pressed F1 or clicked on the query button in a dialog caption. | |
7c913512 | 3266 | |
42013f4c FM |
3267 | A help event is sent to the window that the user clicked on, and is propagated |
3268 | up the window hierarchy until the event is processed or there are no more event | |
3269 | handlers. | |
3270 | ||
3271 | The application should call wxEvent::GetId to check the identity of the | |
3272 | clicked-on window, and then either show some suitable help or call wxEvent::Skip() | |
3273 | if the identifier is unrecognised. | |
3274 | ||
3275 | Calling Skip is important because it allows wxWidgets to generate further | |
3276 | events for ancestors of the clicked-on window. Otherwise it would be impossible to | |
3277 | show help for container windows, since processing would stop after the first window | |
3278 | found. | |
3279 | ||
3280 | @beginEventTable{wxHelpEvent} | |
8c6791e4 | 3281 | @event{EVT_HELP(id, func)} |
3051a44a | 3282 | Process a @c wxEVT_HELP event. |
8c6791e4 | 3283 | @event{EVT_HELP_RANGE(id1, id2, func)} |
3051a44a | 3284 | Process a @c wxEVT_HELP event for a range of ids. |
42013f4c | 3285 | @endEventTable |
7c913512 | 3286 | |
23324ae1 FM |
3287 | @library{wxcore} |
3288 | @category{events} | |
7c913512 | 3289 | |
3e083d65 | 3290 | @see wxContextHelp, wxDialog, @ref overview_events |
23324ae1 | 3291 | */ |
42013f4c | 3292 | class wxHelpEvent : public wxCommandEvent |
23324ae1 FM |
3293 | { |
3294 | public: | |
a44f3b5a FM |
3295 | /** |
3296 | Indicates how a wxHelpEvent was generated. | |
3297 | */ | |
3298 | enum Origin | |
3299 | { | |
3300 | Origin_Unknown, /**< unrecognized event source. */ | |
3301 | Origin_Keyboard, /**< event generated from F1 key press. */ | |
3302 | ||
3303 | /** event generated by wxContextHelp or from the [?] button on | |
3304 | the title bar (Windows). */ | |
3305 | Origin_HelpButton | |
3306 | }; | |
3307 | ||
23324ae1 FM |
3308 | /** |
3309 | Constructor. | |
3310 | */ | |
42013f4c FM |
3311 | wxHelpEvent(wxEventType type = wxEVT_NULL, |
3312 | wxWindowID winid = 0, | |
3313 | const wxPoint& pt = wxDefaultPosition, | |
a44f3b5a | 3314 | wxHelpEvent::Origin origin = Origin_Unknown); |
42013f4c FM |
3315 | |
3316 | /** | |
3317 | Returns the origin of the help event which is one of the ::wxHelpEventOrigin | |
3318 | values. | |
3319 | ||
3320 | The application may handle events generated using the keyboard or mouse | |
3321 | differently, e.g. by using wxGetMousePosition() for the mouse events. | |
3322 | ||
3323 | @see SetOrigin() | |
3324 | */ | |
43c48e1e | 3325 | wxHelpEvent::Origin GetOrigin() const; |
23324ae1 FM |
3326 | |
3327 | /** | |
42013f4c FM |
3328 | Returns the left-click position of the mouse, in screen coordinates. |
3329 | This allows the application to position the help appropriately. | |
23324ae1 | 3330 | */ |
42013f4c | 3331 | const wxPoint& GetPosition() const; |
23324ae1 FM |
3332 | |
3333 | /** | |
42013f4c FM |
3334 | Set the help event origin, only used internally by wxWidgets normally. |
3335 | ||
3336 | @see GetOrigin() | |
23324ae1 | 3337 | */ |
43c48e1e | 3338 | void SetOrigin(wxHelpEvent::Origin origin); |
23324ae1 FM |
3339 | |
3340 | /** | |
42013f4c | 3341 | Sets the left-click position of the mouse, in screen coordinates. |
23324ae1 | 3342 | */ |
42013f4c | 3343 | void SetPosition(const wxPoint& pt); |
23324ae1 FM |
3344 | }; |
3345 | ||
3346 | ||
e54c96f1 | 3347 | |
23324ae1 | 3348 | /** |
42013f4c | 3349 | @class wxScrollEvent |
7c913512 | 3350 | |
42013f4c FM |
3351 | A scroll event holds information about events sent from stand-alone |
3352 | scrollbars (see wxScrollBar) and sliders (see wxSlider). | |
7c913512 | 3353 | |
42013f4c FM |
3354 | Note that scrolled windows send the wxScrollWinEvent which does not derive from |
3355 | wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of | |
3356 | events and use the event table macros mentioned below only for the scrollbar-like | |
3357 | controls. | |
7c913512 | 3358 | |
3a74a290 | 3359 | @section scrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED |
7c913512 | 3360 | |
42013f4c FM |
3361 | The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb |
3362 | using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed | |
3363 | by an EVT_SCROLL_CHANGED event). | |
7c913512 | 3364 | |
42013f4c FM |
3365 | The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change the thumb |
3366 | position, and when clicking next to the thumb (In all these cases the EVT_SCROLL_THUMBRELEASE | |
3367 | event does not happen). | |
7c913512 | 3368 | |
42013f4c FM |
3369 | In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving has finished |
3370 | independently of the way it had started. Please see the widgets sample ("Slider" page) | |
3371 | to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action. | |
3372 | ||
3373 | @remarks | |
3374 | Note that unless specifying a scroll control identifier, you will need to test for scrollbar | |
3375 | orientation with wxScrollEvent::GetOrientation, since horizontal and vertical scroll events | |
3376 | are processed using the same event handler. | |
3377 | ||
3378 | @beginEventTable{wxScrollEvent} | |
3379 | You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting | |
3380 | scroll events from controls, or EVT_SCROLL... macros without window IDs for | |
3381 | intercepting scroll events from the receiving window -- except for this, the | |
3382 | macros behave exactly the same. | |
8c6791e4 | 3383 | @event{EVT_SCROLL(func)} |
42013f4c | 3384 | Process all scroll events. |
8c6791e4 | 3385 | @event{EVT_SCROLL_TOP(func)} |
3a194bda | 3386 | Process @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position). |
8c6791e4 | 3387 | @event{EVT_SCROLL_BOTTOM(func)} |
3a194bda | 3388 | Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). |
8c6791e4 | 3389 | @event{EVT_SCROLL_LINEUP(func)} |
3a194bda | 3390 | Process @c wxEVT_SCROLL_LINEUP line up events. |
8c6791e4 | 3391 | @event{EVT_SCROLL_LINEDOWN(func)} |
3a194bda | 3392 | Process @c wxEVT_SCROLL_LINEDOWN line down events. |
8c6791e4 | 3393 | @event{EVT_SCROLL_PAGEUP(func)} |
3a194bda | 3394 | Process @c wxEVT_SCROLL_PAGEUP page up events. |
8c6791e4 | 3395 | @event{EVT_SCROLL_PAGEDOWN(func)} |
3a194bda | 3396 | Process @c wxEVT_SCROLL_PAGEDOWN page down events. |
8c6791e4 | 3397 | @event{EVT_SCROLL_THUMBTRACK(func)} |
3a194bda | 3398 | Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent as the |
42013f4c | 3399 | user drags the thumbtrack). |
8c6791e4 | 3400 | @event{EVT_SCROLL_THUMBRELEASE(func)} |
3a194bda | 3401 | Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events. |
8c6791e4 | 3402 | @event{EVT_SCROLL_CHANGED(func)} |
3a194bda | 3403 | Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). |
8c6791e4 | 3404 | @event{EVT_COMMAND_SCROLL(id, func)} |
42013f4c | 3405 | Process all scroll events. |
8c6791e4 | 3406 | @event{EVT_COMMAND_SCROLL_TOP(id, func)} |
3a194bda | 3407 | Process @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position). |
8c6791e4 | 3408 | @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)} |
3a194bda | 3409 | Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). |
8c6791e4 | 3410 | @event{EVT_COMMAND_SCROLL_LINEUP(id, func)} |
3a194bda | 3411 | Process @c wxEVT_SCROLL_LINEUP line up events. |
8c6791e4 | 3412 | @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)} |
3a194bda | 3413 | Process @c wxEVT_SCROLL_LINEDOWN line down events. |
8c6791e4 | 3414 | @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)} |
3a194bda | 3415 | Process @c wxEVT_SCROLL_PAGEUP page up events. |
8c6791e4 | 3416 | @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)} |
3a194bda | 3417 | Process @c wxEVT_SCROLL_PAGEDOWN page down events. |
8c6791e4 | 3418 | @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)} |
3a194bda | 3419 | Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent |
42013f4c | 3420 | as the user drags the thumbtrack). |
8c6791e4 | 3421 | @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)} |
3a194bda | 3422 | Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events. |
8c6791e4 | 3423 | @event{EVT_COMMAND_SCROLL_CHANGED(func)} |
3a194bda | 3424 | Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). |
42013f4c | 3425 | @endEventTable |
7c913512 | 3426 | |
23324ae1 | 3427 | @library{wxcore} |
1f1d2182 | 3428 | @category{events} |
7c913512 | 3429 | |
3e083d65 | 3430 | @see wxScrollBar, wxSlider, wxSpinButton, wxScrollWinEvent, @ref overview_events |
23324ae1 | 3431 | */ |
42013f4c | 3432 | class wxScrollEvent : public wxCommandEvent |
23324ae1 FM |
3433 | { |
3434 | public: | |
3435 | /** | |
42013f4c | 3436 | Constructor. |
23324ae1 | 3437 | */ |
42013f4c FM |
3438 | wxScrollEvent(wxEventType commandType = wxEVT_NULL, int id = 0, int pos = 0, |
3439 | int orientation = 0); | |
23324ae1 FM |
3440 | |
3441 | /** | |
42013f4c FM |
3442 | Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the |
3443 | scrollbar. | |
23324ae1 | 3444 | */ |
42013f4c | 3445 | int GetOrientation() const; |
23324ae1 FM |
3446 | |
3447 | /** | |
42013f4c | 3448 | Returns the position of the scrollbar. |
23324ae1 | 3449 | */ |
42013f4c | 3450 | int GetPosition() const; |
a90e69f7 RD |
3451 | |
3452 | ||
3453 | void SetOrientation(int orient); | |
3454 | void SetPosition(int pos); | |
23324ae1 FM |
3455 | }; |
3456 | ||
42013f4c FM |
3457 | /** |
3458 | See wxIdleEvent::SetMode() for more info. | |
3459 | */ | |
3460 | enum wxIdleMode | |
3461 | { | |
3462 | /** Send idle events to all windows */ | |
3463 | wxIDLE_PROCESS_ALL, | |
3464 | ||
3465 | /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */ | |
3466 | wxIDLE_PROCESS_SPECIFIED | |
3467 | }; | |
23324ae1 | 3468 | |
e54c96f1 | 3469 | |
23324ae1 | 3470 | /** |
42013f4c | 3471 | @class wxIdleEvent |
7c913512 | 3472 | |
42013f4c FM |
3473 | This class is used for idle events, which are generated when the system becomes |
3474 | idle. Note that, unless you do something specifically, the idle events are not | |
3475 | sent if the system remains idle once it has become it, e.g. only a single idle | |
3476 | event will be generated until something else resulting in more normal events | |
3477 | happens and only then is the next idle event sent again. | |
3478 | ||
3479 | If you need to ensure a continuous stream of idle events, you can either use | |
3480 | wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically | |
3481 | (for example from a timer event handler), but note that both of these approaches | |
3482 | (and especially the first one) increase the system load and so should be avoided | |
3483 | if possible. | |
3484 | ||
06bfd045 VZ |
3485 | By default, idle events are sent to all windows, including even the hidden |
3486 | ones because they may be shown if some condition is met from their @c | |
3487 | wxEVT_IDLE (or related @c wxEVT_UPDATE_UI) handler. The children of hidden | |
3488 | windows do not receive idle events however as they can't change their state | |
3489 | in any way noticeable by the user. Finally, the global wxApp object also | |
3490 | receives these events, as usual, so it can be used for any global idle time | |
3491 | processing. | |
3492 | ||
3493 | If sending idle events to all windows is causing a significant overhead in | |
3494 | your application, you can call wxIdleEvent::SetMode with the value | |
3495 | wxIDLE_PROCESS_SPECIFIED, and set the wxWS_EX_PROCESS_IDLE extra window | |
3496 | style for every window which should receive idle events, all the other ones | |
3497 | will not receive them in this case. | |
42013f4c FM |
3498 | |
3499 | @beginEventTable{wxIdleEvent} | |
8c6791e4 | 3500 | @event{EVT_IDLE(func)} |
3051a44a | 3501 | Process a @c wxEVT_IDLE event. |
42013f4c | 3502 | @endEventTable |
7c913512 | 3503 | |
23324ae1 | 3504 | @library{wxbase} |
1f1d2182 | 3505 | @category{events} |
7c913512 | 3506 | |
9a25f336 VZ |
3507 | @section sec_delayed_action Delayed Action Mechanism |
3508 | ||
3509 | wxIdleEvent can be used to perform some action "at slightly later time". | |
3510 | This can be necessary in several circumstances when, for whatever reason, | |
3511 | something can't be done in the current event handler. For example, if a | |
3512 | mouse event handler is called with the mouse button pressed, the mouse can | |
3513 | be currently captured and some operations with it -- notably capturing it | |
3514 | again -- might be impossible or lead to undesirable results. If you still | |
3515 | want to capture it, you can do it from @c wxEVT_IDLE handler when it is | |
3516 | called the next time instead of doing it immediately. | |
3517 | ||
3518 | This can be achieved in two different ways: when using static event tables, | |
3519 | you will need a flag indicating to the (always connected) idle event | |
3520 | handler whether the desired action should be performed. The originally | |
3521 | called handler would then set it to indicate that it should indeed be done | |
3522 | and the idle handler itself would reset it to prevent it from doing the | |
3523 | same action again. | |
3524 | ||
3525 | Using dynamically connected event handlers things are even simpler as the | |
3526 | original event handler can simply wxEvtHandler::Connect() or | |
3527 | wxEvtHandler::Bind() the idle event handler which would only be executed | |
3528 | then and could wxEvtHandler::Disconnect() or wxEvtHandler::Unbind() itself. | |
3529 | ||
3530 | ||
3e083d65 | 3531 | @see @ref overview_events, wxUpdateUIEvent, wxWindow::OnInternalIdle |
23324ae1 | 3532 | */ |
42013f4c | 3533 | class wxIdleEvent : public wxEvent |
23324ae1 FM |
3534 | { |
3535 | public: | |
3536 | /** | |
3537 | Constructor. | |
3538 | */ | |
42013f4c | 3539 | wxIdleEvent(); |
23324ae1 | 3540 | |
23324ae1 | 3541 | /** |
42013f4c FM |
3542 | Static function returning a value specifying how wxWidgets will send idle |
3543 | events: to all windows, or only to those which specify that they | |
3544 | will process the events. | |
3c4f71cc | 3545 | |
42013f4c | 3546 | @see SetMode(). |
23324ae1 | 3547 | */ |
42013f4c | 3548 | static wxIdleMode GetMode(); |
23324ae1 | 3549 | |
23324ae1 | 3550 | /** |
42013f4c FM |
3551 | Returns @true if the OnIdle function processing this event requested more |
3552 | processing time. | |
3c4f71cc | 3553 | |
42013f4c | 3554 | @see RequestMore() |
23324ae1 | 3555 | */ |
42013f4c | 3556 | bool MoreRequested() const; |
23324ae1 FM |
3557 | |
3558 | /** | |
42013f4c | 3559 | Tells wxWidgets that more processing is required. |
3c4f71cc | 3560 | |
42013f4c FM |
3561 | This function can be called by an OnIdle handler for a window or window event |
3562 | handler to indicate that wxApp::OnIdle should forward the OnIdle event once | |
3563 | more to the application windows. | |
3c4f71cc | 3564 | |
42013f4c FM |
3565 | If no window calls this function during OnIdle, then the application will |
3566 | remain in a passive event loop (not calling OnIdle) until a new event is | |
3567 | posted to the application by the windowing system. | |
3568 | ||
3569 | @see MoreRequested() | |
23324ae1 | 3570 | */ |
42013f4c | 3571 | void RequestMore(bool needMore = true); |
23324ae1 FM |
3572 | |
3573 | /** | |
42013f4c FM |
3574 | Static function for specifying how wxWidgets will send idle events: to |
3575 | all windows, or only to those which specify that they will process the events. | |
3c4f71cc | 3576 | |
42013f4c FM |
3577 | @param mode |
3578 | Can be one of the ::wxIdleMode values. | |
3579 | The default is wxIDLE_PROCESS_ALL. | |
23324ae1 | 3580 | */ |
42013f4c FM |
3581 | static void SetMode(wxIdleMode mode); |
3582 | }; | |
23324ae1 | 3583 | |
3c4f71cc | 3584 | |
23324ae1 | 3585 | |
42013f4c FM |
3586 | /** |
3587 | @class wxInitDialogEvent | |
3c4f71cc | 3588 | |
42013f4c FM |
3589 | A wxInitDialogEvent is sent as a dialog or panel is being initialised. |
3590 | Handlers for this event can transfer data to the window. | |
23324ae1 | 3591 | |
42013f4c | 3592 | The default handler calls wxWindow::TransferDataToWindow. |
3c4f71cc | 3593 | |
42013f4c | 3594 | @beginEventTable{wxInitDialogEvent} |
8c6791e4 | 3595 | @event{EVT_INIT_DIALOG(func)} |
3051a44a | 3596 | Process a @c wxEVT_INIT_DIALOG event. |
42013f4c FM |
3597 | @endEventTable |
3598 | ||
3599 | @library{wxcore} | |
3600 | @category{events} | |
23324ae1 | 3601 | |
3e083d65 | 3602 | @see @ref overview_events |
42013f4c FM |
3603 | */ |
3604 | class wxInitDialogEvent : public wxEvent | |
3605 | { | |
3606 | public: | |
23324ae1 | 3607 | /** |
42013f4c FM |
3608 | Constructor. |
3609 | */ | |
3610 | wxInitDialogEvent(int id = 0); | |
3611 | }; | |
3c4f71cc | 3612 | |
3c4f71cc | 3613 | |
3c4f71cc | 3614 | |
42013f4c FM |
3615 | /** |
3616 | @class wxWindowDestroyEvent | |
3c4f71cc | 3617 | |
a79a6671 VZ |
3618 | This event is sent as early as possible during the window destruction |
3619 | process. | |
3620 | ||
3621 | For the top level windows, as early as possible means that this is done by | |
3622 | wxFrame or wxDialog destructor, i.e. after the destructor of the derived | |
3623 | class was executed and so any methods specific to the derived class can't | |
3624 | be called any more from this event handler. If you need to do this, you | |
3625 | must call wxWindow::SendDestroyEvent() from your derived class destructor. | |
23324ae1 | 3626 | |
a79a6671 VZ |
3627 | For the child windows, this event is generated just before deleting the |
3628 | window from wxWindow::Destroy() (which is also called when the parent | |
3629 | window is deleted) or from the window destructor if operator @c delete was | |
3630 | used directly (which is not recommended for this very reason). | |
3c4f71cc | 3631 | |
a79a6671 VZ |
3632 | It is usually pointless to handle this event in the window itself but it ca |
3633 | be very useful to receive notifications about the window destruction in the | |
3634 | parent window or in any other object interested in this window. | |
3c4f71cc | 3635 | |
42013f4c FM |
3636 | @library{wxcore} |
3637 | @category{events} | |
3c4f71cc | 3638 | |
3e083d65 | 3639 | @see @ref overview_events, wxWindowCreateEvent |
42013f4c FM |
3640 | */ |
3641 | class wxWindowDestroyEvent : public wxCommandEvent | |
3642 | { | |
3643 | public: | |
3644 | /** | |
3645 | Constructor. | |
23324ae1 | 3646 | */ |
42013f4c | 3647 | wxWindowDestroyEvent(wxWindow* win = NULL); |
a79a6671 | 3648 | |
57ab6f23 | 3649 | /// Return the window being destroyed. |
a79a6671 | 3650 | wxWindow *GetWindow() const; |
42013f4c | 3651 | }; |
23324ae1 | 3652 | |
3c4f71cc | 3653 | |
42013f4c FM |
3654 | /** |
3655 | @class wxNavigationKeyEvent | |
3c4f71cc | 3656 | |
42013f4c FM |
3657 | This event class contains information about navigation events, |
3658 | generated by navigation keys such as tab and page down. | |
23324ae1 | 3659 | |
42013f4c FM |
3660 | This event is mainly used by wxWidgets implementations. |
3661 | A wxNavigationKeyEvent handler is automatically provided by wxWidgets | |
90230407 VZ |
3662 | when you enable keyboard navigation inside a window by inheriting it from |
3663 | wxNavigationEnabled<>. | |
3c4f71cc | 3664 | |
42013f4c | 3665 | @beginEventTable{wxNavigationKeyEvent} |
8c6791e4 | 3666 | @event{EVT_NAVIGATION_KEY(func)} |
42013f4c FM |
3667 | Process a navigation key event. |
3668 | @endEventTable | |
3c4f71cc | 3669 | |
42013f4c FM |
3670 | @library{wxcore} |
3671 | @category{events} | |
3c4f71cc | 3672 | |
42013f4c FM |
3673 | @see wxWindow::Navigate, wxWindow::NavigateIn |
3674 | */ | |
3675 | class wxNavigationKeyEvent : public wxEvent | |
3676 | { | |
3677 | public: | |
3051a44a FM |
3678 | /** |
3679 | Flags which can be used with wxNavigationKeyEvent. | |
3680 | */ | |
3681 | enum wxNavigationKeyEventFlags | |
3682 | { | |
3683 | IsBackward = 0x0000, | |
3684 | IsForward = 0x0001, | |
3685 | WinChange = 0x0002, | |
3686 | FromTab = 0x0004 | |
3687 | }; | |
3688 | ||
42013f4c FM |
3689 | wxNavigationKeyEvent(); |
3690 | wxNavigationKeyEvent(const wxNavigationKeyEvent& event); | |
23324ae1 FM |
3691 | |
3692 | /** | |
42013f4c | 3693 | Returns the child that has the focus, or @NULL. |
23324ae1 | 3694 | */ |
42013f4c | 3695 | wxWindow* GetCurrentFocus() const; |
23324ae1 FM |
3696 | |
3697 | /** | |
42013f4c FM |
3698 | Returns @true if the navigation was in the forward direction. |
3699 | */ | |
3700 | bool GetDirection() const; | |
3c4f71cc | 3701 | |
42013f4c FM |
3702 | /** |
3703 | Returns @true if the navigation event was from a tab key. | |
3704 | This is required for proper navigation over radio buttons. | |
3705 | */ | |
3706 | bool IsFromTab() const; | |
3c4f71cc | 3707 | |
42013f4c FM |
3708 | /** |
3709 | Returns @true if the navigation event represents a window change | |
3710 | (for example, from Ctrl-Page Down in a notebook). | |
23324ae1 | 3711 | */ |
42013f4c | 3712 | bool IsWindowChange() const; |
23324ae1 FM |
3713 | |
3714 | /** | |
42013f4c FM |
3715 | Sets the current focus window member. |
3716 | */ | |
3717 | void SetCurrentFocus(wxWindow* currentFocus); | |
3c4f71cc | 3718 | |
42013f4c FM |
3719 | /** |
3720 | Sets the direction to forward if @a direction is @true, or backward | |
3721 | if @false. | |
3722 | */ | |
3723 | void SetDirection(bool direction); | |
3c4f71cc | 3724 | |
42013f4c FM |
3725 | /** |
3726 | Sets the flags for this event. | |
3727 | The @a flags can be a combination of the ::wxNavigationKeyEventFlags values. | |
23324ae1 | 3728 | */ |
42013f4c | 3729 | void SetFlags(long flags); |
23324ae1 FM |
3730 | |
3731 | /** | |
42013f4c FM |
3732 | Marks the navigation event as from a tab key. |
3733 | */ | |
3734 | void SetFromTab(bool fromTab); | |
3c4f71cc | 3735 | |
42013f4c FM |
3736 | /** |
3737 | Marks the event as a window change event. | |
23324ae1 | 3738 | */ |
42013f4c | 3739 | void SetWindowChange(bool windowChange); |
23324ae1 FM |
3740 | }; |
3741 | ||
3742 | ||
e54c96f1 | 3743 | |
23324ae1 | 3744 | /** |
42013f4c | 3745 | @class wxMouseCaptureChangedEvent |
7c913512 | 3746 | |
42013f4c | 3747 | An mouse capture changed event is sent to a window that loses its |
3051a44a | 3748 | mouse capture. This is called even if wxWindow::ReleaseMouse |
42013f4c FM |
3749 | was called by the application code. Handling this event allows |
3750 | an application to cater for unexpected capture releases which | |
3751 | might otherwise confuse mouse handling code. | |
7c913512 | 3752 | |
42013f4c FM |
3753 | @onlyfor{wxmsw} |
3754 | ||
3755 | @beginEventTable{wxMouseCaptureChangedEvent} | |
8c6791e4 | 3756 | @event{EVT_MOUSE_CAPTURE_CHANGED(func)} |
3051a44a | 3757 | Process a @c wxEVT_MOUSE_CAPTURE_CHANGED event. |
42013f4c | 3758 | @endEventTable |
7c913512 | 3759 | |
23324ae1 FM |
3760 | @library{wxcore} |
3761 | @category{events} | |
7c913512 | 3762 | |
3e083d65 | 3763 | @see wxMouseCaptureLostEvent, @ref overview_events, |
3051a44a | 3764 | wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture |
23324ae1 | 3765 | */ |
42013f4c | 3766 | class wxMouseCaptureChangedEvent : public wxEvent |
23324ae1 FM |
3767 | { |
3768 | public: | |
3769 | /** | |
3770 | Constructor. | |
3771 | */ | |
42013f4c FM |
3772 | wxMouseCaptureChangedEvent(wxWindowID windowId = 0, |
3773 | wxWindow* gainedCapture = NULL); | |
23324ae1 FM |
3774 | |
3775 | /** | |
42013f4c FM |
3776 | Returns the window that gained the capture, or @NULL if it was a |
3777 | non-wxWidgets window. | |
23324ae1 | 3778 | */ |
42013f4c | 3779 | wxWindow* GetCapturedWindow() const; |
23324ae1 FM |
3780 | }; |
3781 | ||
3782 | ||
e54c96f1 | 3783 | |
23324ae1 | 3784 | /** |
42013f4c | 3785 | @class wxCloseEvent |
7c913512 | 3786 | |
42013f4c FM |
3787 | This event class contains information about window and session close events. |
3788 | ||
3789 | The handler function for EVT_CLOSE is called when the user has tried to close a | |
3790 | a frame or dialog box using the window manager (X) or system menu (Windows). | |
3791 | It can also be invoked by the application itself programmatically, for example by | |
3792 | calling the wxWindow::Close function. | |
3793 | ||
3794 | You should check whether the application is forcing the deletion of the window | |
3795 | using wxCloseEvent::CanVeto. If this is @false, you @e must destroy the window | |
3796 | using wxWindow::Destroy. | |
3797 | ||
3798 | If the return value is @true, it is up to you whether you respond by destroying | |
3799 | the window. | |
3800 | ||
3801 | If you don't destroy the window, you should call wxCloseEvent::Veto to | |
3802 | let the calling code know that you did not destroy the window. | |
3803 | This allows the wxWindow::Close function to return @true or @false depending | |
3804 | on whether the close instruction was honoured or not. | |
3805 | ||
195be56d FM |
3806 | Example of a wxCloseEvent handler: |
3807 | ||
3808 | @code | |
3809 | void MyFrame::OnClose(wxCloseEvent& event) | |
3810 | { | |
3811 | if ( event.CanVeto() && m_bFileNotSaved ) | |
3812 | { | |
3813 | if ( wxMessageBox("The file has not been saved... continue closing?", | |
3814 | "Please confirm", | |
3815 | wxICON_QUESTION | wxYES_NO) != wxYES ) | |
3816 | { | |
3817 | event.Veto(); | |
3818 | return; | |
3819 | } | |
3820 | } | |
3821 | ||
3822 | Destroy(); // you may also do: event.Skip(); | |
3823 | // since the default event handler does call Destroy(), too | |
3824 | } | |
3825 | @endcode | |
3826 | ||
9fb99466 VZ |
3827 | The EVT_END_SESSION event is slightly different as it is sent by the system |
3828 | when the user session is ending (e.g. because of log out or shutdown) and | |
3829 | so all windows are being forcefully closed. At least under MSW, after the | |
3830 | handler for this event is executed the program is simply killed by the | |
3831 | system. Because of this, the default handler for this event provided by | |
3832 | wxWidgets calls all the usual cleanup code (including wxApp::OnExit()) so | |
3833 | that it could still be executed and exit()s the process itself, without | |
3834 | waiting for being killed. If this behaviour is for some reason undesirable, | |
3835 | make sure that you define a handler for this event in your wxApp-derived | |
3836 | class and do not call @c event.Skip() in it (but be aware that the system | |
3837 | will still kill your application). | |
3838 | ||
42013f4c | 3839 | @beginEventTable{wxCloseEvent} |
8c6791e4 | 3840 | @event{EVT_CLOSE(func)} |
869aa92d | 3841 | Process a @c wxEVT_CLOSE_WINDOW command event, supplying the member function. |
42013f4c | 3842 | This event applies to wxFrame and wxDialog classes. |
8c6791e4 | 3843 | @event{EVT_QUERY_END_SESSION(func)} |
869aa92d | 3844 | Process a @c wxEVT_QUERY_END_SESSION session event, supplying the member function. |
9fb99466 | 3845 | This event can be handled in wxApp-derived class only. |
8c6791e4 | 3846 | @event{EVT_END_SESSION(func)} |
869aa92d | 3847 | Process a @c wxEVT_END_SESSION session event, supplying the member function. |
9fb99466 | 3848 | This event can be handled in wxApp-derived class only. |
42013f4c | 3849 | @endEventTable |
7c913512 | 3850 | |
23324ae1 FM |
3851 | @library{wxcore} |
3852 | @category{events} | |
7c913512 | 3853 | |
42013f4c | 3854 | @see wxWindow::Close, @ref overview_windowdeletion |
23324ae1 | 3855 | */ |
42013f4c | 3856 | class wxCloseEvent : public wxEvent |
23324ae1 FM |
3857 | { |
3858 | public: | |
3859 | /** | |
3860 | Constructor. | |
3861 | */ | |
42013f4c | 3862 | wxCloseEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0); |
23324ae1 FM |
3863 | |
3864 | /** | |
42013f4c FM |
3865 | Returns @true if you can veto a system shutdown or a window close event. |
3866 | Vetoing a window close event is not possible if the calling code wishes to | |
3867 | force the application to exit, and so this function must be called to check this. | |
23324ae1 | 3868 | */ |
42013f4c FM |
3869 | bool CanVeto() const; |
3870 | ||
3871 | /** | |
3872 | Returns @true if the user is just logging off or @false if the system is | |
3873 | shutting down. This method can only be called for end session and query end | |
3874 | session events, it doesn't make sense for close window event. | |
3875 | */ | |
3876 | bool GetLoggingOff() const; | |
3877 | ||
3878 | /** | |
3879 | Sets the 'can veto' flag. | |
3880 | */ | |
3881 | void SetCanVeto(bool canVeto); | |
3882 | ||
42013f4c FM |
3883 | /** |
3884 | Sets the 'logging off' flag. | |
3885 | */ | |
3886 | void SetLoggingOff(bool loggingOff); | |
3887 | ||
3888 | /** | |
3889 | Call this from your event handler to veto a system shutdown or to signal | |
3890 | to the calling application that a window close did not happen. | |
3891 | ||
3892 | You can only veto a shutdown if CanVeto() returns @true. | |
3893 | */ | |
3894 | void Veto(bool veto = true); | |
23324ae1 FM |
3895 | }; |
3896 | ||
3897 | ||
e54c96f1 | 3898 | |
23324ae1 | 3899 | /** |
42013f4c | 3900 | @class wxMenuEvent |
7c913512 | 3901 | |
42013f4c FM |
3902 | This class is used for a variety of menu-related events. Note that |
3903 | these do not include menu command events, which are | |
3904 | handled using wxCommandEvent objects. | |
7c913512 | 3905 | |
b476cde6 | 3906 | The default handler for @c wxEVT_MENU_HIGHLIGHT displays help |
42013f4c | 3907 | text in the first field of the status bar. |
7c913512 | 3908 | |
42013f4c | 3909 | @beginEventTable{wxMenuEvent} |
8c6791e4 | 3910 | @event{EVT_MENU_OPEN(func)} |
42013f4c FM |
3911 | A menu is about to be opened. On Windows, this is only sent once for each |
3912 | navigation of the menubar (up until all menus have closed). | |
8c6791e4 | 3913 | @event{EVT_MENU_CLOSE(func)} |
42013f4c | 3914 | A menu has been just closed. |
8c6791e4 | 3915 | @event{EVT_MENU_HIGHLIGHT(id, func)} |
42013f4c FM |
3916 | The menu item with the specified id has been highlighted: used to show |
3917 | help prompts in the status bar by wxFrame | |
8c6791e4 | 3918 | @event{EVT_MENU_HIGHLIGHT_ALL(func)} |
42013f4c FM |
3919 | A menu item has been highlighted, i.e. the currently selected menu item has changed. |
3920 | @endEventTable | |
7c913512 | 3921 | |
42013f4c | 3922 | @library{wxcore} |
23324ae1 | 3923 | @category{events} |
7c913512 | 3924 | |
3e083d65 | 3925 | @see wxCommandEvent, @ref overview_events |
23324ae1 | 3926 | */ |
42013f4c | 3927 | class wxMenuEvent : public wxEvent |
23324ae1 FM |
3928 | { |
3929 | public: | |
3930 | /** | |
42013f4c | 3931 | Constructor. |
23324ae1 | 3932 | */ |
a90e69f7 | 3933 | wxMenuEvent(wxEventType type = wxEVT_NULL, int id = 0, wxMenu* menu = NULL); |
23324ae1 FM |
3934 | |
3935 | /** | |
7f3f059a VZ |
3936 | Returns the menu which is being opened or closed. |
3937 | ||
3938 | This method can only be used with the @c OPEN and @c CLOSE events. | |
3939 | ||
3940 | The returned value is never @NULL in the ports implementing this | |
3941 | function, which currently includes all the major ones. | |
23324ae1 | 3942 | */ |
42013f4c | 3943 | wxMenu* GetMenu() const; |
23324ae1 FM |
3944 | |
3945 | /** | |
42013f4c FM |
3946 | Returns the menu identifier associated with the event. |
3947 | This method should be only used with the @c HIGHLIGHT events. | |
23324ae1 | 3948 | */ |
42013f4c | 3949 | int GetMenuId() const; |
23324ae1 FM |
3950 | |
3951 | /** | |
42013f4c FM |
3952 | Returns @true if the menu which is being opened or closed is a popup menu, |
3953 | @false if it is a normal one. | |
23324ae1 | 3954 | |
42013f4c | 3955 | This method should only be used with the @c OPEN and @c CLOSE events. |
23324ae1 | 3956 | */ |
42013f4c FM |
3957 | bool IsPopup() const; |
3958 | }; | |
23324ae1 | 3959 | |
d317fdeb VZ |
3960 | /** |
3961 | @class wxShowEvent | |
d317fdeb VZ |
3962 | |
3963 | An event being sent when the window is shown or hidden. | |
a183ec70 VZ |
3964 | The event is triggered by calls to wxWindow::Show(), and any user |
3965 | action showing a previously hidden window or vice versa (if allowed by | |
3966 | the current platform and/or window manager). | |
3967 | Notice that the event is not triggered when the application is iconized | |
3968 | (minimized) or restored under wxMSW. | |
d317fdeb | 3969 | |
d317fdeb VZ |
3970 | @onlyfor{wxmsw,wxgtk,wxos2} |
3971 | ||
3972 | @beginEventTable{wxShowEvent} | |
3973 | @event{EVT_SHOW(func)} | |
3051a44a | 3974 | Process a @c wxEVT_SHOW event. |
d317fdeb VZ |
3975 | @endEventTable |
3976 | ||
3977 | @library{wxcore} | |
3978 | @category{events} | |
3979 | ||
3e083d65 | 3980 | @see @ref overview_events, wxWindow::Show, |
d317fdeb VZ |
3981 | wxWindow::IsShown |
3982 | */ | |
3983 | ||
3984 | class wxShowEvent : public wxEvent | |
3985 | { | |
3986 | public: | |
3987 | /** | |
3988 | Constructor. | |
3989 | */ | |
3990 | wxShowEvent(int winid = 0, bool show = false); | |
3991 | ||
3992 | /** | |
3993 | Set whether the windows was shown or hidden. | |
3994 | */ | |
3995 | void SetShow(bool show); | |
3996 | ||
3997 | /** | |
3998 | Return @true if the window has been shown, @false if it has been | |
3999 | hidden. | |
4000 | */ | |
4001 | bool IsShown() const; | |
4002 | ||
4003 | /** | |
4004 | @deprecated This function is deprecated in favour of IsShown(). | |
4005 | */ | |
4006 | bool GetShow() const; | |
4007 | }; | |
4008 | ||
4009 | ||
23324ae1 | 4010 | |
42013f4c FM |
4011 | /** |
4012 | @class wxIconizeEvent | |
23324ae1 | 4013 | |
42013f4c | 4014 | An event being sent when the frame is iconized (minimized) or restored. |
23324ae1 | 4015 | |
42013f4c | 4016 | Currently only wxMSW and wxGTK generate such events. |
23324ae1 | 4017 | |
42013f4c | 4018 | @onlyfor{wxmsw,wxgtk} |
23324ae1 | 4019 | |
42013f4c | 4020 | @beginEventTable{wxIconizeEvent} |
8c6791e4 | 4021 | @event{EVT_ICONIZE(func)} |
3051a44a | 4022 | Process a @c wxEVT_ICONIZE event. |
42013f4c | 4023 | @endEventTable |
23324ae1 | 4024 | |
42013f4c FM |
4025 | @library{wxcore} |
4026 | @category{events} | |
23324ae1 | 4027 | |
3e083d65 | 4028 | @see @ref overview_events, wxTopLevelWindow::Iconize, |
42013f4c FM |
4029 | wxTopLevelWindow::IsIconized |
4030 | */ | |
4031 | class wxIconizeEvent : public wxEvent | |
4032 | { | |
4033 | public: | |
23324ae1 | 4034 | /** |
42013f4c | 4035 | Constructor. |
23324ae1 | 4036 | */ |
42013f4c | 4037 | wxIconizeEvent(int id = 0, bool iconized = true); |
23324ae1 FM |
4038 | |
4039 | /** | |
42013f4c FM |
4040 | Returns @true if the frame has been iconized, @false if it has been |
4041 | restored. | |
23324ae1 | 4042 | */ |
d317fdeb VZ |
4043 | bool IsIconized() const; |
4044 | ||
4045 | /** | |
4046 | @deprecated This function is deprecated in favour of IsIconized(). | |
4047 | */ | |
42013f4c FM |
4048 | bool Iconized() const; |
4049 | }; | |
23324ae1 | 4050 | |
23324ae1 | 4051 | |
42013f4c FM |
4052 | |
4053 | /** | |
4054 | @class wxMoveEvent | |
42013f4c | 4055 | |
3051a44a | 4056 | A move event holds information about wxTopLevelWindow move change events. |
42013f4c | 4057 | |
77211166 VZ |
4058 | These events are currently only generated by wxMSW port. |
4059 | ||
42013f4c | 4060 | @beginEventTable{wxMoveEvent} |
8c6791e4 | 4061 | @event{EVT_MOVE(func)} |
3051a44a | 4062 | Process a @c wxEVT_MOVE event, which is generated when a window is moved. |
8c6791e4 | 4063 | @event{EVT_MOVE_START(func)} |
3051a44a | 4064 | Process a @c wxEVT_MOVE_START event, which is generated when the user starts |
42013f4c | 4065 | to move or size a window. wxMSW only. |
37fff49c VZ |
4066 | @event{EVT_MOVING(func)} |
4067 | Process a @c wxEVT_MOVING event, which is generated while the user is | |
4068 | moving the window. wxMSW only. | |
8c6791e4 | 4069 | @event{EVT_MOVE_END(func)} |
3051a44a | 4070 | Process a @c wxEVT_MOVE_END event, which is generated when the user stops |
42013f4c FM |
4071 | moving or sizing a window. wxMSW only. |
4072 | @endEventTable | |
4073 | ||
4074 | @library{wxcore} | |
4075 | @category{events} | |
4076 | ||
3e083d65 | 4077 | @see wxPoint, @ref overview_events |
42013f4c FM |
4078 | */ |
4079 | class wxMoveEvent : public wxEvent | |
4080 | { | |
4081 | public: | |
23324ae1 | 4082 | /** |
42013f4c | 4083 | Constructor. |
23324ae1 | 4084 | */ |
42013f4c | 4085 | wxMoveEvent(const wxPoint& pt, int id = 0); |
23324ae1 FM |
4086 | |
4087 | /** | |
42013f4c | 4088 | Returns the position of the window generating the move change event. |
23324ae1 | 4089 | */ |
42013f4c | 4090 | wxPoint GetPosition() const; |
a90e69f7 RD |
4091 | |
4092 | wxRect GetRect() const; | |
4093 | void SetRect(const wxRect& rect); | |
4094 | void SetPosition(const wxPoint& pos); | |
23324ae1 FM |
4095 | }; |
4096 | ||
4097 | ||
4098 | /** | |
4099 | @class wxSizeEvent | |
7c913512 | 4100 | |
3051a44a | 4101 | A size event holds information about size change events of wxWindow. |
7c913512 | 4102 | |
23324ae1 | 4103 | The EVT_SIZE handler function will be called when the window has been resized. |
7c913512 | 4104 | |
42013f4c | 4105 | You may wish to use this for frames to resize their child windows as appropriate. |
7c913512 | 4106 | |
0ddf0ac6 | 4107 | Note that the size passed is of the whole window: call wxWindow::GetClientSize() |
42013f4c | 4108 | for the area which may be used by the application. |
7c913512 | 4109 | |
23324ae1 | 4110 | When a window is resized, usually only a small part of the window is damaged |
42013f4c FM |
4111 | and you may only need to repaint that area. However, if your drawing depends on the |
4112 | size of the window, you may need to clear the DC explicitly and repaint the whole window. | |
4113 | In which case, you may need to call wxWindow::Refresh to invalidate the entire window. | |
4114 | ||
b0162e32 SC |
4115 | @b Important : Sizers ( see @ref overview_sizer ) rely on size events to function |
4116 | correctly. Therefore, in a sizer-based layout, do not forget to call Skip on all | |
4117 | size events you catch (and don't catch size events at all when you don't need to). | |
4118 | ||
42013f4c | 4119 | @beginEventTable{wxSizeEvent} |
8c6791e4 | 4120 | @event{EVT_SIZE(func)} |
3051a44a | 4121 | Process a @c wxEVT_SIZE event. |
42013f4c | 4122 | @endEventTable |
7c913512 | 4123 | |
23324ae1 FM |
4124 | @library{wxcore} |
4125 | @category{events} | |
7c913512 | 4126 | |
3e083d65 | 4127 | @see wxSize, @ref overview_events |
23324ae1 FM |
4128 | */ |
4129 | class wxSizeEvent : public wxEvent | |
4130 | { | |
4131 | public: | |
4132 | /** | |
4133 | Constructor. | |
4134 | */ | |
4135 | wxSizeEvent(const wxSize& sz, int id = 0); | |
4136 | ||
4137 | /** | |
4138 | Returns the entire size of the window generating the size change event. | |
0ddf0ac6 VZ |
4139 | |
4140 | This is the new total size of the window, i.e. the same size as would | |
4141 | be returned by wxWindow::GetSize() if it were called now. Use | |
4142 | wxWindow::GetClientSize() if you catch this event in a top level window | |
4143 | such as wxFrame to find the size available for the window contents. | |
23324ae1 | 4144 | */ |
328f5751 | 4145 | wxSize GetSize() const; |
a90e69f7 RD |
4146 | void SetSize(wxSize size); |
4147 | ||
4148 | wxRect GetRect() const; | |
4149 | void SetRect(wxRect rect); | |
23324ae1 FM |
4150 | }; |
4151 | ||
4152 | ||
e54c96f1 | 4153 | |
23324ae1 FM |
4154 | /** |
4155 | @class wxSetCursorEvent | |
7c913512 | 4156 | |
3051a44a FM |
4157 | A wxSetCursorEvent is generated from wxWindow when the mouse cursor is about |
4158 | to be set as a result of mouse motion. | |
42013f4c FM |
4159 | |
4160 | This event gives the application the chance to perform specific mouse cursor | |
4161 | processing based on the current position of the mouse within the window. | |
4162 | Use wxSetCursorEvent::SetCursor to specify the cursor you want to be displayed. | |
4163 | ||
4164 | @beginEventTable{wxSetCursorEvent} | |
8c6791e4 | 4165 | @event{EVT_SET_CURSOR(func)} |
3051a44a | 4166 | Process a @c wxEVT_SET_CURSOR event. |
42013f4c | 4167 | @endEventTable |
7c913512 | 4168 | |
23324ae1 | 4169 | @library{wxcore} |
1f1d2182 | 4170 | @category{events} |
7c913512 | 4171 | |
e54c96f1 | 4172 | @see ::wxSetCursor, wxWindow::wxSetCursor |
23324ae1 FM |
4173 | */ |
4174 | class wxSetCursorEvent : public wxEvent | |
4175 | { | |
4176 | public: | |
4177 | /** | |
4178 | Constructor, used by the library itself internally to initialize the event | |
4179 | object. | |
4180 | */ | |
4181 | wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0); | |
4182 | ||
4183 | /** | |
4184 | Returns a reference to the cursor specified by this event. | |
4185 | */ | |
a6052817 | 4186 | const wxCursor& GetCursor() const; |
23324ae1 FM |
4187 | |
4188 | /** | |
4189 | Returns the X coordinate of the mouse in client coordinates. | |
4190 | */ | |
328f5751 | 4191 | wxCoord GetX() const; |
23324ae1 FM |
4192 | |
4193 | /** | |
4194 | Returns the Y coordinate of the mouse in client coordinates. | |
4195 | */ | |
328f5751 | 4196 | wxCoord GetY() const; |
23324ae1 FM |
4197 | |
4198 | /** | |
4199 | Returns @true if the cursor specified by this event is a valid cursor. | |
3c4f71cc | 4200 | |
23324ae1 | 4201 | @remarks You cannot specify wxNullCursor with this event, as it is not |
4cc4bfaf | 4202 | considered a valid cursor. |
23324ae1 | 4203 | */ |
328f5751 | 4204 | bool HasCursor() const; |
23324ae1 FM |
4205 | |
4206 | /** | |
4207 | Sets the cursor associated with this event. | |
4208 | */ | |
4209 | void SetCursor(const wxCursor& cursor); | |
4210 | }; | |
e54c96f1 | 4211 | |
39fb8056 FM |
4212 | |
4213 | ||
7fa7088e BP |
4214 | // ============================================================================ |
4215 | // Global functions/macros | |
4216 | // ============================================================================ | |
4217 | ||
b21126db | 4218 | /** @addtogroup group_funcmacro_events */ |
7fa7088e BP |
4219 | //@{ |
4220 | ||
c0c5bfad | 4221 | /** |
3e083d65 VZ |
4222 | A value uniquely identifying the type of the event. |
4223 | ||
4224 | The values of this type should only be created using wxNewEventType(). | |
c0c5bfad | 4225 | |
6496345c FM |
4226 | See the macro DEFINE_EVENT_TYPE() for more info. |
4227 | ||
3e083d65 | 4228 | @see @ref overview_events_introduction |
6496345c FM |
4229 | */ |
4230 | typedef int wxEventType; | |
4231 | ||
3e083d65 VZ |
4232 | /** |
4233 | A special event type usually used to indicate that some wxEvent has yet | |
4234 | no type assigned. | |
4235 | */ | |
4236 | wxEventType wxEVT_NULL; | |
4237 | ||
a90e69f7 RD |
4238 | wxEventType wxEVT_ANY; |
4239 | ||
6496345c FM |
4240 | /** |
4241 | Generates a new unique event type. | |
4475b410 VZ |
4242 | |
4243 | Usually this function is only used by wxDEFINE_EVENT() and not called | |
4244 | directly. | |
6496345c FM |
4245 | */ |
4246 | wxEventType wxNewEventType(); | |
4247 | ||
4475b410 VZ |
4248 | /** |
4249 | Define a new event type associated with the specified event class. | |
4250 | ||
4251 | This macro defines a new unique event type @a name associated with the | |
4252 | event class @a cls. | |
4253 | ||
4254 | For example: | |
4255 | @code | |
4256 | wxDEFINE_EVENT(MY_COMMAND_EVENT, wxCommandEvent); | |
4257 | ||
4258 | class MyCustomEvent : public wxEvent { ... }; | |
4259 | wxDEFINE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent); | |
4260 | @endcode | |
4261 | ||
4262 | @see wxDECLARE_EVENT(), @ref overview_events_custom | |
4263 | */ | |
4264 | #define wxDEFINE_EVENT(name, cls) \ | |
4265 | const wxEventTypeTag< cls > name(wxNewEventType()) | |
4266 | ||
4267 | /** | |
4268 | Declares a custom event type. | |
4269 | ||
4270 | This macro declares a variable called @a name which must be defined | |
4271 | elsewhere using wxDEFINE_EVENT(). | |
4272 | ||
4273 | The class @a cls must be the wxEvent-derived class associated with the | |
4274 | events of this type and its full declaration must be visible from the point | |
4275 | of use of this macro. | |
ff3fd98a VZ |
4276 | |
4277 | For example: | |
4278 | @code | |
4279 | wxDECLARE_EVENT(MY_COMMAND_EVENT, wxCommandEvent); | |
4280 | ||
4281 | class MyCustomEvent : public wxEvent { ... }; | |
4282 | wxDECLARE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent); | |
4283 | @endcode | |
4475b410 VZ |
4284 | */ |
4285 | #define wxDECLARE_EVENT(name, cls) \ | |
4286 | wxDECLARE_EXPORTED_EVENT(wxEMPTY_PARAMETER_VALUE, name, cls) | |
4287 | ||
4288 | /** | |
4289 | Variant of wxDECLARE_EVENT() used for event types defined inside a shared | |
4290 | library. | |
4291 | ||
4292 | This is mostly used by wxWidgets internally, e.g. | |
4293 | @code | |
4294 | wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_CORE, wxEVT_COMMAND_BUTTON_CLICKED, wxCommandEvent) | |
4295 | @endcode | |
4296 | */ | |
4297 | #define wxDECLARE_EXPORTED_EVENT( expdecl, name, cls ) \ | |
4298 | extern const expdecl wxEventTypeTag< cls > name; | |
4299 | ||
4300 | /** | |
4301 | Helper macro for definition of custom event table macros. | |
4302 | ||
4303 | This macro must only be used if wxEVENTS_COMPATIBILITY_2_8 is 1, otherwise | |
4304 | it is better and more clear to just use the address of the function | |
4305 | directly as this is all this macro does in this case. However it needs to | |
4306 | explicitly cast @a func to @a functype, which is the type of wxEvtHandler | |
4307 | member function taking the custom event argument when | |
4308 | wxEVENTS_COMPATIBILITY_2_8 is 0. | |
4309 | ||
4310 | See wx__DECLARE_EVT0 for an example of use. | |
4311 | ||
4312 | @see @ref overview_events_custom_ownclass | |
4313 | */ | |
4314 | #define wxEVENT_HANDLER_CAST(functype, func) (&func) | |
4315 | ||
4475b410 | 4316 | /** |
d455444a | 4317 | This macro is used to define event table macros for handling custom |
4475b410 VZ |
4318 | events. |
4319 | ||
4320 | Example of use: | |
4321 | @code | |
4322 | class MyEvent : public wxEvent { ... }; | |
4323 | ||
4324 | // note that this is not necessary unless using old compilers: for the | |
4325 | // reasonably new ones just use &func instead of MyEventHandler(func) | |
4326 | typedef void (wxEvtHandler::*MyEventFunction)(MyEvent&); | |
4327 | #define MyEventHandler(func) wxEVENT_HANDLER_CAST(MyEventFunction, func) | |
4328 | ||
4329 | wxDEFINE_EVENT(MY_EVENT_TYPE, MyEvent); | |
4330 | ||
4331 | #define EVT_MY(id, func) \ | |
4332 | wx__DECLARE_EVT1(MY_EVENT_TYPE, id, MyEventHandler(func)) | |
4333 | ||
4334 | ... | |
4335 | ||
a0e9a5df | 4336 | wxBEGIN_EVENT_TABLE(MyFrame, wxFrame) |
4475b410 | 4337 | EVT_MY(wxID_ANY, MyFrame::OnMyEvent) |
a0e9a5df | 4338 | wxEND_EVENT_TABLE() |
4475b410 VZ |
4339 | @endcode |
4340 | ||
4341 | @param evt | |
4342 | The event type to handle. | |
4343 | @param id | |
4344 | The identifier of events to handle. | |
4475b410 VZ |
4345 | @param fn |
4346 | The event handler method. | |
4347 | */ | |
4475b410 VZ |
4348 | #define wx__DECLARE_EVT1(evt, id, fn) \ |
4349 | wx__DECLARE_EVT2(evt, id, wxID_ANY, fn) | |
d455444a FM |
4350 | |
4351 | /** | |
4352 | Generalized version of the wx__DECLARE_EVT1() macro taking a range of | |
4353 | IDs instead of a single one. | |
4354 | Argument @a id1 is the first identifier of the range, @a id2 is the | |
4355 | second identifier of the range. | |
4356 | */ | |
4357 | #define wx__DECLARE_EVT2(evt, id1, id2, fn) \ | |
4358 | DECLARE_EVENT_TABLE_ENTRY(evt, id1, id2, fn, NULL), | |
4359 | ||
4360 | /** | |
4361 | Simplified version of the wx__DECLARE_EVT1() macro, to be used when the | |
4362 | event type must be handled regardless of the ID associated with the | |
4363 | specific event instances. | |
4364 | */ | |
4475b410 VZ |
4365 | #define wx__DECLARE_EVT0(evt, fn) \ |
4366 | wx__DECLARE_EVT1(evt, wxID_ANY, fn) | |
4475b410 | 4367 | |
6496345c FM |
4368 | /** |
4369 | Use this macro inside a class declaration to declare a @e static event table | |
4370 | for that class. | |
4371 | ||
a0e9a5df FM |
4372 | In the implementation file you'll need to use the wxBEGIN_EVENT_TABLE() |
4373 | and the wxEND_EVENT_TABLE() macros, plus some additional @c EVT_xxx macro | |
6496345c | 4374 | to capture events. |
a0e9a5df FM |
4375 | |
4376 | Note that this macro requires a final semicolon. | |
6496345c | 4377 | |
3e083d65 | 4378 | @see @ref overview_events_eventtables |
6496345c | 4379 | */ |
a0e9a5df | 4380 | #define wxDECLARE_EVENT_TABLE() |
6496345c FM |
4381 | |
4382 | /** | |
4383 | Use this macro in a source file to start listing @e static event handlers | |
4384 | for a specific class. | |
4385 | ||
a0e9a5df | 4386 | Use wxEND_EVENT_TABLE() to terminate the event-declaration block. |
6496345c | 4387 | |
3e083d65 | 4388 | @see @ref overview_events_eventtables |
6496345c | 4389 | */ |
a0e9a5df | 4390 | #define wxBEGIN_EVENT_TABLE(theClass, baseClass) |
6496345c FM |
4391 | |
4392 | /** | |
4393 | Use this macro in a source file to end listing @e static event handlers | |
4394 | for a specific class. | |
4395 | ||
a0e9a5df | 4396 | Use wxBEGIN_EVENT_TABLE() to start the event-declaration block. |
6496345c | 4397 | |
3e083d65 | 4398 | @see @ref overview_events_eventtables |
6496345c | 4399 | */ |
a0e9a5df | 4400 | #define wxEND_EVENT_TABLE() |
6496345c | 4401 | |
39fb8056 FM |
4402 | /** |
4403 | In a GUI application, this function posts @a event to the specified @e dest | |
7fa7088e BP |
4404 | object using wxEvtHandler::AddPendingEvent(). |
4405 | ||
4406 | Otherwise, it dispatches @a event immediately using | |
4407 | wxEvtHandler::ProcessEvent(). See the respective documentation for details | |
c3f94162 VZ |
4408 | (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent() |
4409 | this function is not thread-safe for event objects having wxString fields, | |
4410 | use wxQueueEvent() instead. | |
39fb8056 | 4411 | |
7fa7088e | 4412 | @header{wx/event.h} |
39fb8056 | 4413 | */ |
c3f94162 VZ |
4414 | void wxPostEvent(wxEvtHandler* dest, const wxEvent& event); |
4415 | ||
4416 | /** | |
4417 | Queue an event for processing on the given object. | |
4418 | ||
4419 | This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation | |
4420 | for more details. | |
4421 | ||
4422 | @header{wx/event.h} | |
4423 | ||
4424 | @param dest | |
4425 | The object to queue the event on, can't be @c NULL. | |
4426 | @param event | |
4427 | The heap-allocated and non-@c NULL event to queue, the function takes | |
4428 | ownership of it. | |
4429 | */ | |
4430 | void wxQueueEvent(wxEvtHandler* dest, wxEvent *event); | |
7fa7088e | 4431 | |
a90e69f7 RD |
4432 | |
4433 | ||
4434 | wxEventType wxEVT_COMMAND_BUTTON_CLICKED; | |
4435 | wxEventType wxEVT_COMMAND_CHECKBOX_CLICKED; | |
4436 | wxEventType wxEVT_COMMAND_CHOICE_SELECTED; | |
4437 | wxEventType wxEVT_COMMAND_LISTBOX_SELECTED; | |
4438 | wxEventType wxEVT_COMMAND_LISTBOX_DOUBLECLICKED; | |
4439 | wxEventType wxEVT_COMMAND_CHECKLISTBOX_TOGGLED; | |
4440 | wxEventType wxEVT_COMMAND_MENU_SELECTED; | |
4441 | wxEventType wxEVT_COMMAND_SLIDER_UPDATED; | |
4442 | wxEventType wxEVT_COMMAND_RADIOBOX_SELECTED; | |
4443 | wxEventType wxEVT_COMMAND_RADIOBUTTON_SELECTED; | |
4444 | wxEventType wxEVT_COMMAND_SCROLLBAR_UPDATED; | |
4445 | wxEventType wxEVT_COMMAND_VLBOX_SELECTED; | |
4446 | wxEventType wxEVT_COMMAND_COMBOBOX_SELECTED; | |
4447 | wxEventType wxEVT_COMMAND_TOOL_RCLICKED; | |
4448 | wxEventType wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED; | |
4449 | wxEventType wxEVT_COMMAND_TOOL_ENTER; | |
4450 | wxEventType wxEVT_COMMAND_COMBOBOX_DROPDOWN; | |
4451 | wxEventType wxEVT_COMMAND_COMBOBOX_CLOSEUP; | |
c1b293bb | 4452 | wxEventType wxEVT_THREAD; |
a90e69f7 RD |
4453 | wxEventType wxEVT_LEFT_DOWN; |
4454 | wxEventType wxEVT_LEFT_UP; | |
4455 | wxEventType wxEVT_MIDDLE_DOWN; | |
4456 | wxEventType wxEVT_MIDDLE_UP; | |
4457 | wxEventType wxEVT_RIGHT_DOWN; | |
4458 | wxEventType wxEVT_RIGHT_UP; | |
4459 | wxEventType wxEVT_MOTION; | |
4460 | wxEventType wxEVT_ENTER_WINDOW; | |
4461 | wxEventType wxEVT_LEAVE_WINDOW; | |
4462 | wxEventType wxEVT_LEFT_DCLICK; | |
4463 | wxEventType wxEVT_MIDDLE_DCLICK; | |
4464 | wxEventType wxEVT_RIGHT_DCLICK; | |
4465 | wxEventType wxEVT_SET_FOCUS; | |
4466 | wxEventType wxEVT_KILL_FOCUS; | |
4467 | wxEventType wxEVT_CHILD_FOCUS; | |
4468 | wxEventType wxEVT_MOUSEWHEEL; | |
4469 | wxEventType wxEVT_AUX1_DOWN; | |
4470 | wxEventType wxEVT_AUX1_UP; | |
4471 | wxEventType wxEVT_AUX1_DCLICK; | |
4472 | wxEventType wxEVT_AUX2_DOWN; | |
4473 | wxEventType wxEVT_AUX2_UP; | |
4474 | wxEventType wxEVT_AUX2_DCLICK; | |
4475 | wxEventType wxEVT_CHAR; | |
4476 | wxEventType wxEVT_CHAR_HOOK; | |
4477 | wxEventType wxEVT_NAVIGATION_KEY; | |
4478 | wxEventType wxEVT_KEY_DOWN; | |
4479 | wxEventType wxEVT_KEY_UP; | |
4480 | wxEventType wxEVT_HOTKEY; | |
4481 | wxEventType wxEVT_SET_CURSOR; | |
4482 | wxEventType wxEVT_SCROLL_TOP; | |
4483 | wxEventType wxEVT_SCROLL_BOTTOM; | |
4484 | wxEventType wxEVT_SCROLL_LINEUP; | |
4485 | wxEventType wxEVT_SCROLL_LINEDOWN; | |
4486 | wxEventType wxEVT_SCROLL_PAGEUP; | |
4487 | wxEventType wxEVT_SCROLL_PAGEDOWN; | |
4488 | wxEventType wxEVT_SCROLL_THUMBTRACK; | |
4489 | wxEventType wxEVT_SCROLL_THUMBRELEASE; | |
4490 | wxEventType wxEVT_SCROLL_CHANGED; | |
4491 | wxEventType wxEVT_SPIN_UP; | |
4492 | wxEventType wxEVT_SPIN_DOWN; | |
4493 | wxEventType wxEVT_SPIN; | |
4494 | wxEventType wxEVT_SCROLLWIN_TOP; | |
4495 | wxEventType wxEVT_SCROLLWIN_BOTTOM; | |
4496 | wxEventType wxEVT_SCROLLWIN_LINEUP; | |
4497 | wxEventType wxEVT_SCROLLWIN_LINEDOWN; | |
4498 | wxEventType wxEVT_SCROLLWIN_PAGEUP; | |
4499 | wxEventType wxEVT_SCROLLWIN_PAGEDOWN; | |
4500 | wxEventType wxEVT_SCROLLWIN_THUMBTRACK; | |
4501 | wxEventType wxEVT_SCROLLWIN_THUMBRELEASE; | |
4502 | wxEventType wxEVT_SIZE; | |
4503 | wxEventType wxEVT_MOVE; | |
4504 | wxEventType wxEVT_CLOSE_WINDOW; | |
4505 | wxEventType wxEVT_END_SESSION; | |
4506 | wxEventType wxEVT_QUERY_END_SESSION; | |
4507 | wxEventType wxEVT_ACTIVATE_APP; | |
4508 | wxEventType wxEVT_ACTIVATE; | |
4509 | wxEventType wxEVT_CREATE; | |
4510 | wxEventType wxEVT_DESTROY; | |
4511 | wxEventType wxEVT_SHOW; | |
4512 | wxEventType wxEVT_ICONIZE; | |
4513 | wxEventType wxEVT_MAXIMIZE; | |
4514 | wxEventType wxEVT_MOUSE_CAPTURE_CHANGED; | |
4515 | wxEventType wxEVT_MOUSE_CAPTURE_LOST; | |
4516 | wxEventType wxEVT_PAINT; | |
4517 | wxEventType wxEVT_ERASE_BACKGROUND; | |
4518 | wxEventType wxEVT_NC_PAINT; | |
4519 | wxEventType wxEVT_MENU_OPEN; | |
4520 | wxEventType wxEVT_MENU_CLOSE; | |
4521 | wxEventType wxEVT_MENU_HIGHLIGHT; | |
4522 | wxEventType wxEVT_CONTEXT_MENU; | |
4523 | wxEventType wxEVT_SYS_COLOUR_CHANGED; | |
4524 | wxEventType wxEVT_DISPLAY_CHANGED; | |
4525 | wxEventType wxEVT_QUERY_NEW_PALETTE; | |
4526 | wxEventType wxEVT_PALETTE_CHANGED; | |
4527 | wxEventType wxEVT_JOY_BUTTON_DOWN; | |
4528 | wxEventType wxEVT_JOY_BUTTON_UP; | |
4529 | wxEventType wxEVT_JOY_MOVE; | |
4530 | wxEventType wxEVT_JOY_ZMOVE; | |
4531 | wxEventType wxEVT_DROP_FILES; | |
4532 | wxEventType wxEVT_INIT_DIALOG; | |
4533 | wxEventType wxEVT_IDLE; | |
4534 | wxEventType wxEVT_UPDATE_UI; | |
4535 | wxEventType wxEVT_SIZING; | |
4536 | wxEventType wxEVT_MOVING; | |
4537 | wxEventType wxEVT_MOVE_START; | |
4538 | wxEventType wxEVT_MOVE_END; | |
4539 | wxEventType wxEVT_HIBERNATE; | |
4540 | wxEventType wxEVT_COMMAND_TEXT_COPY; | |
4541 | wxEventType wxEVT_COMMAND_TEXT_CUT; | |
4542 | wxEventType wxEVT_COMMAND_TEXT_PASTE; | |
4543 | wxEventType wxEVT_COMMAND_LEFT_CLICK; | |
4544 | wxEventType wxEVT_COMMAND_LEFT_DCLICK; | |
4545 | wxEventType wxEVT_COMMAND_RIGHT_CLICK; | |
4546 | wxEventType wxEVT_COMMAND_RIGHT_DCLICK; | |
4547 | wxEventType wxEVT_COMMAND_SET_FOCUS; | |
4548 | wxEventType wxEVT_COMMAND_KILL_FOCUS; | |
4549 | wxEventType wxEVT_COMMAND_ENTER; | |
4550 | wxEventType wxEVT_HELP; | |
4551 | wxEventType wxEVT_DETAILED_HELP; | |
4552 | wxEventType wxEVT_COMMAND_TEXT_UPDATED; | |
e83c4d40 | 4553 | wxEventType wxEVT_COMMAND_TEXT_ENTER; |
a90e69f7 | 4554 | wxEventType wxEVT_COMMAND_TOOL_CLICKED; |
ea8fa3c4 | 4555 | wxEventType wxEVT_WINDOW_MODAL_DIALOG_CLOSED; |
a90e69f7 RD |
4556 | |
4557 | ||
4558 | ||
7fa7088e BP |
4559 | //@} |
4560 |