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