]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/event.h
run tests on the wxMSW port again
[wxWidgets.git] / interface / wx / event.h
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 license
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. wxEVT_PAINT, wxEVT_SIZE or
114 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
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 -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
467 the function skips to step (7).
468 -# TryBefore() is called (this is where wxValidator are taken into
469 account for wxWindow objects). If this returns @true, the function exits.
470 -# Dynamic event table of the handlers connected using Connect() 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 connected using event table
475 macros is searched for this event handler. If this fails, the base
476 class event table 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 ProcessEventHere() which is
493 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 event handler.
507
508 This method is called from ProcessEvent(), please see the detailed
509 description of the event processing logic there.
510
511 It is @em not virtual and so may not be overridden but it does call
512 virtual TryBefore() which may be overridden.
513
514 @param event
515 Event to process.
516 @return
517 @true if this object itself defines a handler for this event and
518 the handler didn't skip the event.
519 */
520 bool ProcessEventHere(wxEvent& event);
521
522 /**
523 Processes an event by calling ProcessEvent() and handles any exceptions
524 that occur in the process.
525 If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
526
527 @param event
528 Event to process.
529
530 @return @true if the event was processed, @false if no handler was found
531 or an exception was thrown.
532
533 @see wxWindow::HandleWindowEvent
534 */
535 bool SafelyProcessEvent(wxEvent& event);
536
537 /**
538 Processes the pending events previously queued using QueueEvent() or
539 AddPendingEvent(); you must call this function only if you are sure
540 there are pending events for this handler, otherwise a @c wxCHECK
541 will fail.
542
543 The real processing still happens in ProcessEvent() which is called by this
544 function.
545
546 Note that this function needs a valid application object (see
547 wxAppConsole::GetInstance()) because wxApp holds the list of the event
548 handlers with pending events and this function manipulates that list.
549 */
550 void ProcessPendingEvents();
551
552 /**
553 Deletes all events queued on this event handler using QueueEvent() or
554 AddPendingEvent().
555
556 Use with care because the events which are deleted are (obviously) not
557 processed and this may have unwanted consequences (e.g. user actions events
558 will be lost).
559 */
560 void DeletePendingEvents();
561
562 /**
563 Searches the event table, executing an event handler function if an appropriate
564 one is found.
565
566 @param table
567 Event table to be searched.
568 @param event
569 Event to be matched against an event table entry.
570
571 @return @true if a suitable event handler function was found and
572 executed, and the function did not call wxEvent::Skip.
573
574 @remarks This function looks through the object's event table and tries
575 to find an entry that will match the event.
576 An entry will match if:
577 @li The event type matches, and
578 @li the identifier or identifier range matches, or the event table
579 entry's identifier is zero.
580
581 If a suitable function is called but calls wxEvent::Skip, this
582 function will fail, and searching will continue.
583
584 @todo this function in the header is listed as an "implementation only" function;
585 are we sure we want to document it?
586
587 @see ProcessEvent()
588 */
589 virtual bool SearchEventTable(wxEventTable& table,
590 wxEvent& event);
591
592 //@}
593
594
595 /**
596 @name Connecting and disconnecting
597 */
598 //@{
599
600 /**
601 Connects the given function dynamically with the event handler, id and
602 event type.
603
604 This is an alternative to the use of static event tables. It is more
605 flexible as it allows to connect events generated by some object to an
606 event handler defined in a different object of a different class (which
607 is impossible to do directly with the event tables -- the events can be
608 only handled in another object if they are propagated upwards to it).
609 Do make sure to specify the correct @a eventSink when connecting to an
610 event of a different object.
611
612 See @ref overview_events_connect for more detailed explanation
613 of this function and the @ref page_samples_event sample for usage
614 examples.
615
616 This specific overload allows you to connect an event handler to a @e range
617 of @e source IDs.
618 Do not confuse @e source IDs with event @e types: source IDs identify the
619 event generator objects (typically wxMenuItem or wxWindow objects) while the
620 event @e type identify which type of events should be handled by the
621 given @e function (an event generator object may generate many different
622 types of events!).
623
624 @param id
625 The first ID of the identifier range to be associated with the event
626 handler function.
627 @param lastId
628 The last ID of the identifier range to be associated with the event
629 handler function.
630 @param eventType
631 The event type to be associated with this event handler.
632 @param function
633 The event handler function. Note that this function should
634 be explicitly converted to the correct type which can be done using a macro
635 called @c wxFooEventHandler for the handler for any @c wxFooEvent.
636 @param userData
637 Data to be associated with the event table entry.
638 @param eventSink
639 Object whose member function should be called. It must be specified
640 when connecting an event generated by one object to a member
641 function of a different object. If it is omitted, @c this is used.
642 */
643 void Connect(int id, int lastId, wxEventType eventType,
644 wxObjectEventFunction function,
645 wxObject* userData = NULL,
646 wxEvtHandler* eventSink = NULL);
647
648 /**
649 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
650 overload for more info.
651
652 This overload can be used to attach an event handler to a single source ID:
653
654 Example:
655 @code
656 frame->Connect( wxID_EXIT,
657 wxEVT_COMMAND_MENU_SELECTED,
658 wxCommandEventHandler(MyFrame::OnQuit) );
659 @endcode
660 */
661 void Connect(int id, wxEventType eventType,
662 wxObjectEventFunction function,
663 wxObject* userData = NULL,
664 wxEvtHandler* eventSink = NULL);
665
666 /**
667 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
668 overload for more info.
669
670 This overload will connect the given event handler so that regardless of the
671 ID of the event source, the handler will be called.
672 */
673 void Connect(wxEventType eventType,
674 wxObjectEventFunction function,
675 wxObject* userData = NULL,
676 wxEvtHandler* eventSink = NULL);
677
678 /**
679 Disconnects the given function dynamically from the event handler, using the
680 specified parameters as search criteria and returning @true if a matching
681 function has been found and removed.
682
683 This method can only disconnect functions which have been added using the
684 Connect() method. There is no way to disconnect functions connected using
685 the (static) event tables.
686
687 @param eventType
688 The event type associated with this event handler.
689 @param function
690 The event handler function.
691 @param userData
692 Data associated with the event table entry.
693 @param eventSink
694 Object whose member function should be called.
695 */
696 bool Disconnect(wxEventType eventType,
697 wxObjectEventFunction function,
698 wxObject* userData = NULL,
699 wxEvtHandler* eventSink = NULL);
700
701 /**
702 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
703 overload for more info.
704
705 This overload takes the additional @a id parameter.
706 */
707 bool Disconnect(int id = wxID_ANY,
708 wxEventType eventType = wxEVT_NULL,
709 wxObjectEventFunction function = NULL,
710 wxObject* userData = NULL,
711 wxEvtHandler* eventSink = NULL);
712
713 /**
714 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
715 overload for more info.
716
717 This overload takes an additional range of source IDs.
718 */
719 bool Disconnect(int id, int lastId,
720 wxEventType eventType,
721 wxObjectEventFunction function = NULL,
722 wxObject* userData = NULL,
723 wxEvtHandler* eventSink = NULL);
724 //@}
725
726
727 /**
728 @name User-supplied data
729 */
730 //@{
731
732 /**
733 Returns user-supplied client data.
734
735 @remarks Normally, any extra data the programmer wishes to associate with
736 the object should be made available by deriving a new class with
737 new data members.
738
739 @see SetClientData()
740 */
741 void* GetClientData() const;
742
743 /**
744 Returns a pointer to the user-supplied client data object.
745
746 @see SetClientObject(), wxClientData
747 */
748 wxClientData* GetClientObject() const;
749
750 /**
751 Sets user-supplied client data.
752
753 @param data
754 Data to be associated with the event handler.
755
756 @remarks Normally, any extra data the programmer wishes to associate
757 with the object should be made available by deriving a new
758 class with new data members. You must not call this method
759 and SetClientObject on the same class - only one of them.
760
761 @see GetClientData()
762 */
763 void SetClientData(void* data);
764
765 /**
766 Set the client data object. Any previous object will be deleted.
767
768 @see GetClientObject(), wxClientData
769 */
770 void SetClientObject(wxClientData* data);
771
772 //@}
773
774
775 /**
776 @name Event handler chaining
777
778 wxEvtHandler can be arranged in a double-linked list of handlers
779 which is automatically iterated by ProcessEvent() if needed.
780 */
781 //@{
782
783 /**
784 Returns @true if the event handler is enabled, @false otherwise.
785
786 @see SetEvtHandlerEnabled()
787 */
788 bool GetEvtHandlerEnabled() const;
789
790 /**
791 Returns the pointer to the next handler in the chain.
792
793 @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
794 wxWindow::PushEventHandler, wxWindow::PopEventHandler
795 */
796 wxEvtHandler* GetNextHandler() const;
797
798 /**
799 Returns the pointer to the previous handler in the chain.
800
801 @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
802 wxWindow::PushEventHandler, wxWindow::PopEventHandler
803 */
804 wxEvtHandler* GetPreviousHandler() const;
805
806 /**
807 Enables or disables the event handler.
808
809 @param enabled
810 @true if the event handler is to be enabled, @false if it is to be disabled.
811
812 @remarks You can use this function to avoid having to remove the event
813 handler from the chain, for example when implementing a
814 dialog editor and changing from edit to test mode.
815
816 @see GetEvtHandlerEnabled()
817 */
818 void SetEvtHandlerEnabled(bool enabled);
819
820 /**
821 Sets the pointer to the next handler.
822
823 @remarks
824 See ProcessEvent() for more info about how the chains of event handlers
825 are internally used.
826 Also remember that wxEvtHandler uses double-linked lists and thus if you
827 use this function, you should also call SetPreviousHandler() on the
828 argument passed to this function:
829 @code
830 handlerA->SetNextHandler(handlerB);
831 handlerB->SetPreviousHandler(handlerA);
832 @endcode
833
834 @param handler
835 The event handler to be set as the next handler.
836 Cannot be @NULL.
837
838 @see @ref overview_events_processing
839 */
840 virtual void SetNextHandler(wxEvtHandler* handler);
841
842 /**
843 Sets the pointer to the previous handler.
844 All remarks about SetNextHandler() apply to this function as well.
845
846 @param handler
847 The event handler to be set as the previous handler.
848 Cannot be @NULL.
849
850 @see @ref overview_events_processing
851 */
852 virtual void SetPreviousHandler(wxEvtHandler* handler);
853
854 /**
855 Unlinks this event handler from the chain it's part of (if any);
856 then links the "previous" event handler to the "next" one
857 (so that the chain won't be interrupted).
858
859 E.g. if before calling Unlink() you have the following chain:
860 @image html evthandler_unlink_before.png
861 then after calling @c B->Unlink() you'll have:
862 @image html evthandler_unlink_after.png
863
864 @since 2.9.0
865 */
866 void Unlink();
867
868 /**
869 Returns @true if the next and the previous handler pointers of this
870 event handler instance are @NULL.
871
872 @since 2.9.0
873
874 @see SetPreviousHandler(), SetNextHandler()
875 */
876 bool IsUnlinked() const;
877
878 //@}
879
880 protected:
881 /**
882 Method called by ProcessEvent() before examining this object event
883 tables.
884
885 This method can be overridden to hook into the event processing logic
886 as early as possible. You should usually call the base class version
887 when overriding this method, even if wxEvtHandler itself does nothing
888 here, some derived classes do use this method, e.g. wxWindow implements
889 support for wxValidator in it.
890
891 Example:
892 @code
893 class MyClass : public BaseClass // inheriting from wxEvtHandler
894 {
895 ...
896 protected:
897 virtual bool TryBefore(wxEvent& event)
898 {
899 if ( MyPreProcess(event) )
900 return true;
901
902 return BaseClass::TryBefore(event);
903 }
904 };
905 @endcode
906
907 @see ProcessEvent(), ProcessEventHere()
908 */
909 virtual bool TryBefore(wxEvent& event);
910
911 /**
912 Method called by ProcessEvent() as last resort.
913
914 This method can be overridden to implement post-processing for the
915 events which were not processed anywhere else.
916
917 The base class version handles forwarding the unprocessed events to
918 wxApp at wxEvtHandler level and propagating them upwards the window
919 child-parent chain at wxWindow level and so should usually be called
920 when overriding this method:
921 @code
922 class MyClass : public BaseClass // inheriting from wxEvtHandler
923 {
924 ...
925 protected:
926 virtual bool TryAfter(wxEvent& event)
927 {
928 if ( BaseClass::TryAfter(event) )
929 return true;
930
931 return MyPostProcess(event);
932 }
933 };
934 @endcode
935
936 @see ProcessEvent(), ProcessEventHere()
937 */
938 virtual bool TryAfter(wxEvent& event);
939 };
940
941
942 /**
943 @class wxKeyEvent
944
945 This event class contains information about keypress (character) events.
946
947 Notice that there are three different kinds of keyboard events in wxWidgets:
948 key down and up events and char events. The difference between the first two
949 is clear - the first corresponds to a key press and the second to a key
950 release - otherwise they are identical. Just note that if the key is
951 maintained in a pressed state you will typically get a lot of (automatically
952 generated) down events but only one up so it is wrong to assume that there is
953 one up event corresponding to each down one.
954
955 Both key events provide untranslated key codes while the char event carries
956 the translated one. The untranslated code for alphanumeric keys is always
957 an upper case value. For the other keys it is one of @c WXK_XXX values
958 from the ::wxKeyCode enumeration.
959 The translated key is, in general, the character the user expects to appear
960 as the result of the key combination when typing the text into a text entry
961 zone, for example.
962
963 A few examples to clarify this (all assume that CAPS LOCK is unpressed
964 and the standard US keyboard): when the @c 'A' key is pressed, the key down
965 event key code is equal to @c ASCII A == 65. But the char event key code
966 is @c ASCII a == 97. On the other hand, if you press both SHIFT and
967 @c 'A' keys simultaneously , the key code in key down event will still be
968 just @c 'A' while the char event key code parameter will now be @c 'A'
969 as well.
970
971 Although in this simple case it is clear that the correct key code could be
972 found in the key down event handler by checking the value returned by
973 wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as
974 for non-alphanumeric keys the translation is keyboard-layout dependent and
975 can only be done properly by the system itself.
976
977 Another kind of translation is done when the control key is pressed: for
978 example, for CTRL-A key press the key down event still carries the
979 same key code @c 'a' as usual but the char event will have key code of 1,
980 the ASCII value of this key combination.
981
982 You may discover how the other keys on your system behave interactively by
983 running the @ref page_samples_text wxWidgets sample and pressing some keys
984 in any of the text controls shown in it.
985
986 @b Tip: be sure to call @c event.Skip() for events that you don't process in
987 key event function, otherwise menu shortcuts may cease to work under Windows.
988
989 @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler
990 does not call @c event.Skip() then the corresponding char event
991 (@c EVT_CHAR) will not happen.
992 This is by design and enables the programs that handle both types of
993 events to be a bit simpler.
994
995 @note For Windows programmers: The key and char events in wxWidgets are
996 similar to but slightly different from Windows @c WM_KEYDOWN and
997 @c WM_CHAR events. In particular, Alt-x combination will generate a
998 char event in wxWidgets (unless it is used as an accelerator).
999
1000
1001 @beginEventTable{wxKeyEvent}
1002 @event{EVT_KEY_DOWN(func)}
1003 Process a @c wxEVT_KEY_DOWN event (any key has been pressed).
1004 @event{EVT_KEY_UP(func)}
1005 Process a @c wxEVT_KEY_UP event (any key has been released).
1006 @event{EVT_CHAR(func)}
1007 Process a @c wxEVT_CHAR event.
1008 @endEventTable
1009
1010 @see wxKeyboardState
1011
1012 @library{wxcore}
1013 @category{events}
1014 */
1015 class wxKeyEvent : public wxEvent,
1016 public wxKeyboardState
1017 {
1018 public:
1019 /**
1020 Constructor.
1021 Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK.
1022 */
1023 wxKeyEvent(wxEventType keyEventType = wxEVT_NULL);
1024
1025 /**
1026 Returns the virtual key code. ASCII events return normal ASCII values,
1027 while non-ASCII events return values such as @b WXK_LEFT for the left cursor
1028 key. See ::wxKeyCode for a full list of the virtual key codes.
1029
1030 Note that in Unicode build, the returned value is meaningful only if the
1031 user entered a character that can be represented in current locale's default
1032 charset. You can obtain the corresponding Unicode character using GetUnicodeKey().
1033 */
1034 int GetKeyCode() const;
1035
1036 //@{
1037 /**
1038 Obtains the position (in client coordinates) at which the key was pressed.
1039 */
1040 wxPoint GetPosition() const;
1041 void GetPosition(long* x, long* y) const;
1042 //@}
1043
1044 /**
1045 Returns the raw key code for this event. This is a platform-dependent scan code
1046 which should only be used in advanced applications.
1047
1048 @note Currently the raw key codes are not supported by all ports, use
1049 @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
1050 */
1051 wxUint32 GetRawKeyCode() const;
1052
1053 /**
1054 Returns the low level key flags for this event. The flags are
1055 platform-dependent and should only be used in advanced applications.
1056
1057 @note Currently the raw key flags are not supported by all ports, use
1058 @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available.
1059 */
1060 wxUint32 GetRawKeyFlags() const;
1061
1062 /**
1063 Returns the Unicode character corresponding to this key event.
1064
1065 This function is only available in Unicode build, i.e. when
1066 @c wxUSE_UNICODE is 1.
1067 */
1068 wxChar GetUnicodeKey() const;
1069
1070 /**
1071 Returns the X position (in client coordinates) of the event.
1072 */
1073 wxCoord GetX() const;
1074
1075 /**
1076 Returns the Y position (in client coordinates) of the event.
1077 */
1078 wxCoord GetY() const;
1079 };
1080
1081
1082
1083 /**
1084 @class wxJoystickEvent
1085
1086 This event class contains information about joystick events, particularly
1087 events received by windows.
1088
1089 @beginEventTable{wxJoystickEvent}
1090 @event{EVT_JOY_BUTTON_DOWN(func)}
1091 Process a @c wxEVT_JOY_BUTTON_DOWN event.
1092 @event{EVT_JOY_BUTTON_UP(func)}
1093 Process a @c wxEVT_JOY_BUTTON_UP event.
1094 @event{EVT_JOY_MOVE(func)}
1095 Process a @c wxEVT_JOY_MOVE event.
1096 @event{EVT_JOY_ZMOVE(func)}
1097 Process a @c wxEVT_JOY_ZMOVE event.
1098 @event{EVT_JOYSTICK_EVENTS(func)}
1099 Processes all joystick events.
1100 @endEventTable
1101
1102 @library{wxcore}
1103 @category{events}
1104
1105 @see wxJoystick
1106 */
1107 class wxJoystickEvent : public wxEvent
1108 {
1109 public:
1110 /**
1111 Constructor.
1112 */
1113 wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0,
1114 int joystick = wxJOYSTICK1,
1115 int change = 0);
1116
1117 /**
1118 Returns @true if the event was a down event from the specified button
1119 (or any button).
1120
1121 @param button
1122 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
1123 indicate any button down event.
1124 */
1125 bool ButtonDown(int button = wxJOY_BUTTON_ANY) const;
1126
1127 /**
1128 Returns @true if the specified button (or any button) was in a down state.
1129
1130 @param button
1131 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
1132 indicate any button down event.
1133 */
1134 bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const;
1135
1136 /**
1137 Returns @true if the event was an up event from the specified button
1138 (or any button).
1139
1140 @param button
1141 Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to
1142 indicate any button down event.
1143 */
1144 bool ButtonUp(int button = wxJOY_BUTTON_ANY) const;
1145
1146 /**
1147 Returns the identifier of the button changing state.
1148
1149 This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
1150 */
1151 int GetButtonChange() const;
1152
1153 /**
1154 Returns the down state of the buttons.
1155
1156 This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
1157 */
1158 int GetButtonState() const;
1159
1160 /**
1161 Returns the identifier of the joystick generating the event - one of
1162 wxJOYSTICK1 and wxJOYSTICK2.
1163 */
1164 int GetJoystick() const;
1165
1166 /**
1167 Returns the x, y position of the joystick event.
1168 */
1169 wxPoint GetPosition() const;
1170
1171 /**
1172 Returns the z position of the joystick event.
1173 */
1174 int GetZPosition() const;
1175
1176 /**
1177 Returns @true if this was a button up or down event
1178 (@e not 'is any button down?').
1179 */
1180 bool IsButton() const;
1181
1182 /**
1183 Returns @true if this was an x, y move event.
1184 */
1185 bool IsMove() const;
1186
1187 /**
1188 Returns @true if this was a z move event.
1189 */
1190 bool IsZMove() const;
1191 };
1192
1193
1194
1195 /**
1196 @class wxScrollWinEvent
1197
1198 A scroll event holds information about events sent from scrolling windows.
1199
1200 Note that you can use the EVT_SCROLLWIN* macros for intercepting scroll window events
1201 from the receiving window.
1202
1203 @beginEventTable{wxScrollWinEvent}
1204 @event{EVT_SCROLLWIN(func)}
1205 Process all scroll events.
1206 @event{EVT_SCROLLWIN_TOP(func)}
1207 Process wxEVT_SCROLLWIN_TOP scroll-to-top events.
1208 @event{EVT_SCROLLWIN_BOTTOM(func)}
1209 Process wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events.
1210 @event{EVT_SCROLLWIN_LINEUP(func)}
1211 Process wxEVT_SCROLLWIN_LINEUP line up events.
1212 @event{EVT_SCROLLWIN_LINEDOWN(func)}
1213 Process wxEVT_SCROLLWIN_LINEDOWN line down events.
1214 @event{EVT_SCROLLWIN_PAGEUP(func)}
1215 Process wxEVT_SCROLLWIN_PAGEUP page up events.
1216 @event{EVT_SCROLLWIN_PAGEDOWN(func)}
1217 Process wxEVT_SCROLLWIN_PAGEDOWN page down events.
1218 @event{EVT_SCROLLWIN_THUMBTRACK(func)}
1219 Process wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events
1220 (frequent events sent as the user drags the thumbtrack).
1221 @event{EVT_SCROLLWIN_THUMBRELEASE(func)}
1222 Process wxEVT_SCROLLWIN_THUMBRELEASE thumb release events.
1223 @endEventTable
1224
1225
1226 @library{wxcore}
1227 @category{events}
1228
1229 @see wxScrollEvent, @ref overview_events
1230 */
1231 class wxScrollWinEvent : public wxEvent
1232 {
1233 public:
1234 /**
1235 Constructor.
1236 */
1237 wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0,
1238 int orientation = 0);
1239
1240 /**
1241 Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
1242 scrollbar.
1243
1244 @todo wxHORIZONTAL and wxVERTICAL should go in their own enum
1245 */
1246 int GetOrientation() const;
1247
1248 /**
1249 Returns the position of the scrollbar for the thumb track and release events.
1250
1251 Note that this field can't be used for the other events, you need to query
1252 the window itself for the current position in that case.
1253 */
1254 int GetPosition() const;
1255 };
1256
1257
1258
1259 /**
1260 @class wxSysColourChangedEvent
1261
1262 This class is used for system colour change events, which are generated
1263 when the user changes the colour settings using the control panel.
1264 This is only appropriate under Windows.
1265
1266 @remarks
1267 The default event handler for this event propagates the event to child windows,
1268 since Windows only sends the events to top-level windows.
1269 If intercepting this event for a top-level window, remember to call the base
1270 class handler, or to pass the event on to the window's children explicitly.
1271
1272 @beginEventTable{wxSysColourChangedEvent}
1273 @event{EVT_SYS_COLOUR_CHANGED(func)}
1274 Process a @c wxEVT_SYS_COLOUR_CHANGED event.
1275 @endEventTable
1276
1277 @library{wxcore}
1278 @category{events}
1279
1280 @see @ref overview_events
1281 */
1282 class wxSysColourChangedEvent : public wxEvent
1283 {
1284 public:
1285 /**
1286 Constructor.
1287 */
1288 wxSysColourChangedEvent();
1289 };
1290
1291
1292
1293 /**
1294 @class wxWindowCreateEvent
1295
1296 This event is sent just after the actual window associated with a wxWindow
1297 object has been created.
1298
1299 Since it is derived from wxCommandEvent, the event propagates up
1300 the window hierarchy.
1301
1302 @beginEventTable{wxWindowCreateEvent}
1303 @event{EVT_WINDOW_CREATE(func)}
1304 Process a @c wxEVT_CREATE event.
1305 @endEventTable
1306
1307 @library{wxcore}
1308 @category{events}
1309
1310 @see @ref overview_events, wxWindowDestroyEvent
1311 */
1312 class wxWindowCreateEvent : public wxCommandEvent
1313 {
1314 public:
1315 /**
1316 Constructor.
1317 */
1318 wxWindowCreateEvent(wxWindow* win = NULL);
1319
1320 /// Retutn the window being created.
1321 wxWindow *GetWindow() const;
1322 };
1323
1324
1325
1326 /**
1327 @class wxPaintEvent
1328
1329 A paint event is sent when a window's contents needs to be repainted.
1330
1331 Please notice that in general it is impossible to change the drawing of a
1332 standard control (such as wxButton) and so you shouldn't attempt to handle
1333 paint events for them as even if it might work on some platforms, this is
1334 inherently not portable and won't work everywhere.
1335
1336 @remarks
1337 Note that in a paint event handler, the application must always create a
1338 wxPaintDC object, even if you do not use it. Otherwise, under MS Windows,
1339 refreshing for this and other windows will go wrong.
1340 For example:
1341 @code
1342 void MyWindow::OnPaint(wxPaintEvent& event)
1343 {
1344 wxPaintDC dc(this);
1345
1346 DrawMyDocument(dc);
1347 }
1348 @endcode
1349 You can optimize painting by retrieving the rectangles that have been damaged
1350 and only repainting these. The rectangles are in terms of the client area,
1351 and are unscrolled, so you will need to do some calculations using the current
1352 view position to obtain logical, scrolled units.
1353 Here is an example of using the wxRegionIterator class:
1354 @code
1355 // Called when window needs to be repainted.
1356 void MyWindow::OnPaint(wxPaintEvent& event)
1357 {
1358 wxPaintDC dc(this);
1359
1360 // Find Out where the window is scrolled to
1361 int vbX,vbY; // Top left corner of client
1362 GetViewStart(&vbX,&vbY);
1363
1364 int vX,vY,vW,vH; // Dimensions of client area in pixels
1365 wxRegionIterator upd(GetUpdateRegion()); // get the update rect list
1366
1367 while (upd)
1368 {
1369 vX = upd.GetX();
1370 vY = upd.GetY();
1371 vW = upd.GetW();
1372 vH = upd.GetH();
1373
1374 // Alternatively we can do this:
1375 // wxRect rect(upd.GetRect());
1376
1377 // Repaint this rectangle
1378 ...some code...
1379
1380 upd ++ ;
1381 }
1382 }
1383 @endcode
1384
1385
1386 @beginEventTable{wxPaintEvent}
1387 @event{EVT_PAINT(func)}
1388 Process a @c wxEVT_PAINT event.
1389 @endEventTable
1390
1391 @library{wxcore}
1392 @category{events}
1393
1394 @see @ref overview_events
1395 */
1396 class wxPaintEvent : public wxEvent
1397 {
1398 public:
1399 /**
1400 Constructor.
1401 */
1402 wxPaintEvent(int id = 0);
1403 };
1404
1405
1406
1407 /**
1408 @class wxMaximizeEvent
1409
1410 An event being sent when a top level window is maximized. Notice that it is
1411 not sent when the window is restored to its original size after it had been
1412 maximized, only a normal wxSizeEvent is generated in this case.
1413
1414 @beginEventTable{wxMaximizeEvent}
1415 @event{EVT_MAXIMIZE(func)}
1416 Process a @c wxEVT_MAXIMIZE event.
1417 @endEventTable
1418
1419 @library{wxcore}
1420 @category{events}
1421
1422 @see @ref overview_events, wxTopLevelWindow::Maximize,
1423 wxTopLevelWindow::IsMaximized
1424 */
1425 class wxMaximizeEvent : public wxEvent
1426 {
1427 public:
1428 /**
1429 Constructor. Only used by wxWidgets internally.
1430 */
1431 wxMaximizeEvent(int id = 0);
1432 };
1433
1434 /**
1435 The possibles modes to pass to wxUpdateUIEvent::SetMode().
1436 */
1437 enum wxUpdateUIMode
1438 {
1439 /** Send UI update events to all windows. */
1440 wxUPDATE_UI_PROCESS_ALL,
1441
1442 /** Send UI update events to windows that have
1443 the wxWS_EX_PROCESS_UI_UPDATES flag specified. */
1444 wxUPDATE_UI_PROCESS_SPECIFIED
1445 };
1446
1447
1448 /**
1449 @class wxUpdateUIEvent
1450
1451 This class is used for pseudo-events which are called by wxWidgets
1452 to give an application the chance to update various user interface elements.
1453
1454 Without update UI events, an application has to work hard to check/uncheck,
1455 enable/disable, show/hide, and set the text for elements such as menu items
1456 and toolbar buttons. The code for doing this has to be mixed up with the code
1457 that is invoked when an action is invoked for a menu item or button.
1458
1459 With update UI events, you define an event handler to look at the state of the
1460 application and change UI elements accordingly. wxWidgets will call your member
1461 functions in idle time, so you don't have to worry where to call this code.
1462
1463 In addition to being a clearer and more declarative method, it also means you don't
1464 have to worry whether you're updating a toolbar or menubar identifier. The same
1465 handler can update a menu item and toolbar button, if the identifier is the same.
1466 Instead of directly manipulating the menu or button, you call functions in the event
1467 object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a
1468 call has been made, and which UI element to update.
1469
1470 These events will work for popup menus as well as menubars. Just before a menu is
1471 popped up, wxMenu::UpdateUI is called to process any UI events for the window that
1472 owns the menu.
1473
1474 If you find that the overhead of UI update processing is affecting your application,
1475 you can do one or both of the following:
1476 @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED,
1477 and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should
1478 receive update events. No other windows will receive update events.
1479 @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay
1480 between updates. You may need to call wxWindow::UpdateWindowUI at critical points,
1481 for example when a dialog is about to be shown, in case the user sees a slight
1482 delay before windows are updated.
1483
1484 Note that although events are sent in idle time, defining a wxIdleEvent handler
1485 for a window does not affect this because the events are sent from wxWindow::OnInternalIdle
1486 which is always called in idle time.
1487
1488 wxWidgets tries to optimize update events on some platforms.
1489 On Windows and GTK+, events for menubar items are only sent when the menu is about
1490 to be shown, and not in idle time.
1491
1492
1493 @beginEventTable{wxUpdateUIEvent}
1494 @event{EVT_UPDATE_UI(id, func)}
1495 Process a @c wxEVT_UPDATE_UI event for the command with the given id.
1496 @event{EVT_UPDATE_UI_RANGE(id1, id2, func)}
1497 Process a @c wxEVT_UPDATE_UI event for any command with id included in the given range.
1498 @endEventTable
1499
1500 @library{wxcore}
1501 @category{events}
1502
1503 @see @ref overview_events
1504 */
1505 class wxUpdateUIEvent : public wxCommandEvent
1506 {
1507 public:
1508 /**
1509 Constructor.
1510 */
1511 wxUpdateUIEvent(wxWindowID commandId = 0);
1512
1513 /**
1514 Returns @true if it is appropriate to update (send UI update events to)
1515 this window.
1516
1517 This function looks at the mode used (see wxUpdateUIEvent::SetMode),
1518 the wxWS_EX_PROCESS_UI_UPDATES flag in @a window, the time update events
1519 were last sent in idle time, and the update interval, to determine whether
1520 events should be sent to this window now. By default this will always
1521 return @true because the update mode is initially wxUPDATE_UI_PROCESS_ALL
1522 and the interval is set to 0; so update events will be sent as often as
1523 possible. You can reduce the frequency that events are sent by changing the
1524 mode and/or setting an update interval.
1525
1526 @see ResetUpdateTime(), SetUpdateInterval(), SetMode()
1527 */
1528 static bool CanUpdate(wxWindow* window);
1529
1530 /**
1531 Check or uncheck the UI element.
1532 */
1533 void Check(bool check);
1534
1535 /**
1536 Enable or disable the UI element.
1537 */
1538 void Enable(bool enable);
1539
1540 /**
1541 Returns @true if the UI element should be checked.
1542 */
1543 bool GetChecked() const;
1544
1545 /**
1546 Returns @true if the UI element should be enabled.
1547 */
1548 bool GetEnabled() const;
1549
1550 /**
1551 Static function returning a value specifying how wxWidgets will send update
1552 events: to all windows, or only to those which specify that they will process
1553 the events.
1554
1555 @see SetMode()
1556 */
1557 static wxUpdateUIMode GetMode();
1558
1559 /**
1560 Returns @true if the application has called Check().
1561 For wxWidgets internal use only.
1562 */
1563 bool GetSetChecked() const;
1564
1565 /**
1566 Returns @true if the application has called Enable().
1567 For wxWidgets internal use only.
1568 */
1569 bool GetSetEnabled() const;
1570
1571 /**
1572 Returns @true if the application has called Show().
1573 For wxWidgets internal use only.
1574 */
1575 bool GetSetShown() const;
1576
1577 /**
1578 Returns @true if the application has called SetText().
1579 For wxWidgets internal use only.
1580 */
1581 bool GetSetText() const;
1582
1583 /**
1584 Returns @true if the UI element should be shown.
1585 */
1586 bool GetShown() const;
1587
1588 /**
1589 Returns the text that should be set for the UI element.
1590 */
1591 wxString GetText() const;
1592
1593 /**
1594 Returns the current interval between updates in milliseconds.
1595 The value -1 disables updates, 0 updates as frequently as possible.
1596
1597 @see SetUpdateInterval().
1598 */
1599 static long GetUpdateInterval();
1600
1601 /**
1602 Used internally to reset the last-updated time to the current time.
1603
1604 It is assumed that update events are normally sent in idle time, so this
1605 is called at the end of idle processing.
1606
1607 @see CanUpdate(), SetUpdateInterval(), SetMode()
1608 */
1609 static void ResetUpdateTime();
1610
1611 /**
1612 Specify how wxWidgets will send update events: to all windows, or only to
1613 those which specify that they will process the events.
1614
1615 @param mode
1616 this parameter may be one of the ::wxUpdateUIMode enumeration values.
1617 The default mode is wxUPDATE_UI_PROCESS_ALL.
1618 */
1619 static void SetMode(wxUpdateUIMode mode);
1620
1621 /**
1622 Sets the text for this UI element.
1623 */
1624 void SetText(const wxString& text);
1625
1626 /**
1627 Sets the interval between updates in milliseconds.
1628
1629 Set to -1 to disable updates, or to 0 to update as frequently as possible.
1630 The default is 0.
1631
1632 Use this to reduce the overhead of UI update events if your application
1633 has a lot of windows. If you set the value to -1 or greater than 0,
1634 you may also need to call wxWindow::UpdateWindowUI at appropriate points
1635 in your application, such as when a dialog is about to be shown.
1636 */
1637 static void SetUpdateInterval(long updateInterval);
1638
1639 /**
1640 Show or hide the UI element.
1641 */
1642 void Show(bool show);
1643 };
1644
1645
1646
1647 /**
1648 @class wxClipboardTextEvent
1649
1650 This class represents the events generated by a control (typically a
1651 wxTextCtrl but other windows can generate these events as well) when its
1652 content gets copied or cut to, or pasted from the clipboard.
1653
1654 There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY,
1655 wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE.
1656
1657 If any of these events is processed (without being skipped) by an event
1658 handler, the corresponding operation doesn't take place which allows to
1659 prevent the text from being copied from or pasted to a control. It is also
1660 possible to examine the clipboard contents in the PASTE event handler and
1661 transform it in some way before inserting in a control -- for example,
1662 changing its case or removing invalid characters.
1663
1664 Finally notice that a CUT event is always preceded by the COPY event which
1665 makes it possible to only process the latter if it doesn't matter if the
1666 text was copied or cut.
1667
1668 @note
1669 These events are currently only generated by wxTextCtrl under GTK+.
1670 They are generated by all controls under Windows.
1671
1672 @beginEventTable{wxClipboardTextEvent}
1673 @event{EVT_TEXT_COPY(id, func)}
1674 Some or all of the controls content was copied to the clipboard.
1675 @event{EVT_TEXT_CUT(id, func)}
1676 Some or all of the controls content was cut (i.e. copied and
1677 deleted).
1678 @event{EVT_TEXT_PASTE(id, func)}
1679 Clipboard content was pasted into the control.
1680 @endEventTable
1681
1682
1683 @library{wxcore}
1684 @category{events}
1685
1686 @see wxClipboard
1687 */
1688 class wxClipboardTextEvent : public wxCommandEvent
1689 {
1690 public:
1691 /**
1692 Constructor.
1693 */
1694 wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
1695 };
1696
1697
1698
1699 /**
1700 @class wxMouseEvent
1701
1702 This event class contains information about the events generated by the mouse:
1703 they include mouse buttons press and release events and mouse move events.
1704
1705 All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the
1706 left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and
1707 @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more
1708 buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events
1709 can also be generated. Note that not all mice have even a middle button so a
1710 portable application should avoid relying on the events from it (but the right
1711 button click can be emulated using the left mouse button with the control key
1712 under Mac platforms with a single button mouse).
1713
1714 For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events
1715 purposes, the mouse is considered to be inside the window if it is in the
1716 window client area and not inside one of its children. In other words, the
1717 parent window receives @c wxEVT_LEAVE_WINDOW event not only when the
1718 mouse leaves the window entirely but also when it enters one of its children.
1719
1720 The position associated with a mouse event is expressed in the window
1721 coordinates of the window which generated the event, you can use
1722 wxWindow::ClientToScreen() to convert it to screen coordinates and possibly
1723 call wxWindow::ScreenToClient() next to convert it to window coordinates of
1724 another window.
1725
1726 @note Note that under Windows CE mouse enter and leave events are not natively
1727 supported by the system but are generated by wxWidgets itself. This has several
1728 drawbacks: the LEAVE_WINDOW event might be received some time after the mouse
1729 left the window and the state variables for it may have changed during this time.
1730
1731 @note Note the difference between methods like wxMouseEvent::LeftDown and
1732 wxMouseEvent::LeftIsDown: the former returns @true when the event corresponds
1733 to the left mouse button click while the latter returns @true if the left
1734 mouse button is currently being pressed. For example, when the user is dragging
1735 the mouse you can use wxMouseEvent::LeftIsDown to test whether the left mouse
1736 button is (still) depressed. Also, by convention, if wxMouseEvent::LeftDown
1737 returns @true, wxMouseEvent::LeftIsDown will also return @true in wxWidgets
1738 whatever the underlying GUI behaviour is (which is platform-dependent).
1739 The same applies, of course, to other mouse buttons as well.
1740
1741
1742 @beginEventTable{wxMouseEvent}
1743 @event{EVT_LEFT_DOWN(func)}
1744 Process a @c wxEVT_LEFT_DOWN event. The handler of this event should normally
1745 call event.Skip() to allow the default processing to take place as otherwise
1746 the window under mouse wouldn't get the focus.
1747 @event{EVT_LEFT_UP(func)}
1748 Process a @c wxEVT_LEFT_UP event.
1749 @event{EVT_LEFT_DCLICK(func)}
1750 Process a @c wxEVT_LEFT_DCLICK event.
1751 @event{EVT_MIDDLE_DOWN(func)}
1752 Process a @c wxEVT_MIDDLE_DOWN event.
1753 @event{EVT_MIDDLE_UP(func)}
1754 Process a @c wxEVT_MIDDLE_UP event.
1755 @event{EVT_MIDDLE_DCLICK(func)}
1756 Process a @c wxEVT_MIDDLE_DCLICK event.
1757 @event{EVT_RIGHT_DOWN(func)}
1758 Process a @c wxEVT_RIGHT_DOWN event.
1759 @event{EVT_RIGHT_UP(func)}
1760 Process a @c wxEVT_RIGHT_UP event.
1761 @event{EVT_RIGHT_DCLICK(func)}
1762 Process a @c wxEVT_RIGHT_DCLICK event.
1763 @event{EVT_MOUSE_AUX1_DOWN(func)}
1764 Process a @c wxEVT_MOUSE_AUX1_DOWN event.
1765 @event{EVT_MOUSE_AUX1_UP(func)}
1766 Process a @c wxEVT_MOUSE_AUX1_UP event.
1767 @event{EVT_MOUSE_AUX1_DCLICK(func)}
1768 Process a @c wxEVT_MOUSE_AUX1_DCLICK event.
1769 @event{EVT_MOUSE_AUX2_DOWN(func)}
1770 Process a @c wxEVT_MOUSE_AUX2_DOWN event.
1771 @event{EVT_MOUSE_AUX2_UP(func)}
1772 Process a @c wxEVT_MOUSE_AUX2_UP event.
1773 @event{EVT_MOUSE_AUX2_DCLICK(func)}
1774 Process a @c wxEVT_MOUSE_AUX2_DCLICK event.
1775 @event{EVT_MOTION(func)}
1776 Process a @c wxEVT_MOTION event.
1777 @event{EVT_ENTER_WINDOW(func)}
1778 Process a @c wxEVT_ENTER_WINDOW event.
1779 @event{EVT_LEAVE_WINDOW(func)}
1780 Process a @c wxEVT_LEAVE_WINDOW event.
1781 @event{EVT_MOUSEWHEEL(func)}
1782 Process a @c wxEVT_MOUSEWHEEL event.
1783 @event{EVT_MOUSE_EVENTS(func)}
1784 Process all mouse events.
1785 @endEventTable
1786
1787 @library{wxcore}
1788 @category{events}
1789
1790 @see wxKeyEvent
1791 */
1792 class wxMouseEvent : public wxEvent,
1793 public wxMouseState
1794 {
1795 public:
1796 /**
1797 Constructor. Valid event types are:
1798
1799 @li wxEVT_ENTER_WINDOW
1800 @li wxEVT_LEAVE_WINDOW
1801 @li wxEVT_LEFT_DOWN
1802 @li wxEVT_LEFT_UP
1803 @li wxEVT_LEFT_DCLICK
1804 @li wxEVT_MIDDLE_DOWN
1805 @li wxEVT_MIDDLE_UP
1806 @li wxEVT_MIDDLE_DCLICK
1807 @li wxEVT_RIGHT_DOWN
1808 @li wxEVT_RIGHT_UP
1809 @li wxEVT_RIGHT_DCLICK
1810 @li wxEVT_MOUSE_AUX1_DOWN
1811 @li wxEVT_MOUSE_AUX1_UP
1812 @li wxEVT_MOUSE_AUX1_DCLICK
1813 @li wxEVT_MOUSE_AUX2_DOWN
1814 @li wxEVT_MOUSE_AUX2_UP
1815 @li wxEVT_MOUSE_AUX2_DCLICK
1816 @li wxEVT_MOTION
1817 @li wxEVT_MOUSEWHEEL
1818 */
1819 wxMouseEvent(wxEventType mouseEventType = wxEVT_NULL);
1820
1821 /**
1822 Returns @true if the event was a first extra button double click.
1823 */
1824 bool Aux1DClick() const;
1825
1826 /**
1827 Returns @true if the first extra button mouse button changed to down.
1828 */
1829 bool Aux1Down() const;
1830
1831 /**
1832 Returns @true if the first extra button mouse button is currently down,
1833 independent of the current event type.
1834 */
1835 bool Aux1IsDown() const;
1836
1837 /**
1838 Returns @true if the first extra button mouse button changed to up.
1839 */
1840 bool Aux1Up() const;
1841
1842 /**
1843 Returns @true if the event was a second extra button double click.
1844 */
1845 bool Aux2DClick() const;
1846
1847 /**
1848 Returns @true if the second extra button mouse button changed to down.
1849 */
1850 bool Aux2Down() const;
1851
1852 /**
1853 Returns @true if the second extra button mouse button is currently down,
1854 independent of the current event type.
1855 */
1856 bool Aux2IsDown() const;
1857
1858 /**
1859 Returns @true if the second extra button mouse button changed to up.
1860 */
1861 bool Aux2Up() const;
1862
1863 /**
1864 Returns @true if the identified mouse button is changing state.
1865 Valid values of @a button are:
1866
1867 @li @c wxMOUSE_BTN_LEFT: check if left button was pressed
1868 @li @c wxMOUSE_BTN_MIDDLE: check if middle button was pressed
1869 @li @c wxMOUSE_BTN_RIGHT: check if right button was pressed
1870 @li @c wxMOUSE_BTN_AUX1: check if the first extra button was pressed
1871 @li @c wxMOUSE_BTN_AUX2: check if the second extra button was pressed
1872 @li @c wxMOUSE_BTN_ANY: check if any button was pressed
1873
1874 @todo introduce wxMouseButton enum
1875 */
1876 bool Button(int button) const;
1877
1878 /**
1879 If the argument is omitted, this returns @true if the event was a mouse
1880 double click event. Otherwise the argument specifies which double click event
1881 was generated (see Button() for the possible values).
1882 */
1883 bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const;
1884
1885 /**
1886 If the argument is omitted, this returns @true if the event was a mouse
1887 button down event. Otherwise the argument specifies which button-down event
1888 was generated (see Button() for the possible values).
1889 */
1890 bool ButtonDown(int = wxMOUSE_BTN_ANY) const;
1891
1892 /**
1893 If the argument is omitted, this returns @true if the event was a mouse
1894 button up event. Otherwise the argument specifies which button-up event
1895 was generated (see Button() for the possible values).
1896 */
1897 bool ButtonUp(int = wxMOUSE_BTN_ANY) const;
1898
1899 /**
1900 Returns @true if this was a dragging event (motion while a button is depressed).
1901
1902 @see Moving()
1903 */
1904 bool Dragging() const;
1905
1906 /**
1907 Returns @true if the mouse was entering the window.
1908
1909 @see Leaving()
1910 */
1911 bool Entering() const;
1912
1913 /**
1914 Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE
1915 if no button is involved (for mouse move, enter or leave event, for example).
1916 Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and
1917 double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT
1918 for the same events for the middle and the right buttons respectively.
1919 */
1920 int GetButton() const;
1921
1922 /**
1923 Returns the number of mouse clicks for this event: 1 for a simple click, 2
1924 for a double-click, 3 for a triple-click and so on.
1925
1926 Currently this function is implemented only in wxMac and returns -1 for the
1927 other platforms (you can still distinguish simple clicks from double-clicks as
1928 they generate different kinds of events however).
1929
1930 @since 2.9.0
1931 */
1932 int GetClickCount() const;
1933
1934 /**
1935 Returns the configured number of lines (or whatever) to be scrolled per
1936 wheel action. Defaults to three.
1937 */
1938 int GetLinesPerAction() const;
1939
1940 /**
1941 Returns the logical mouse position in pixels (i.e. translated according to the
1942 translation set for the DC, which usually indicates that the window has been
1943 scrolled).
1944 */
1945 wxPoint GetLogicalPosition(const wxDC& dc) const;
1946
1947 //@{
1948 /**
1949 Sets *x and *y to the position at which the event occurred.
1950 Returns the physical mouse position in pixels.
1951
1952 Note that if the mouse event has been artificially generated from a special
1953 keyboard combination (e.g. under Windows when the "menu" key is pressed), the
1954 returned position is ::wxDefaultPosition.
1955 */
1956 wxPoint GetPosition() const;
1957 void GetPosition(wxCoord* x, wxCoord* y) const;
1958 void GetPosition(long* x, long* y) const;
1959 //@}
1960
1961 /**
1962 Get wheel delta, normally 120.
1963
1964 This is the threshold for action to be taken, and one such action
1965 (for example, scrolling one increment) should occur for each delta.
1966 */
1967 int GetWheelDelta() const;
1968
1969 /**
1970 Get wheel rotation, positive or negative indicates direction of rotation.
1971
1972 Current devices all send an event when rotation is at least +/-WheelDelta, but
1973 finer resolution devices can be created in the future.
1974
1975 Because of this you shouldn't assume that one event is equal to 1 line, but you
1976 should be able to either do partial line scrolling or wait until several
1977 events accumulate before scrolling.
1978 */
1979 int GetWheelRotation() const;
1980
1981 /**
1982 Gets the axis the wheel operation concerns; @c 0 is the Y axis as on
1983 most mouse wheels, @c 1 is the X axis.
1984
1985 Note that only some models of mouse have horizontal wheel axis.
1986 */
1987 int GetWheelAxis() const;
1988
1989 /**
1990 Returns X coordinate of the physical mouse event position.
1991 */
1992 wxCoord GetX() const;
1993
1994 /**
1995 Returns Y coordinate of the physical mouse event position.
1996 */
1997 wxCoord GetY() const;
1998
1999 /**
2000 Returns @true if the event was a mouse button event (not necessarily a button
2001 down event - that may be tested using ButtonDown()).
2002 */
2003 bool IsButton() const;
2004
2005 /**
2006 Returns @true if the system has been setup to do page scrolling with
2007 the mouse wheel instead of line scrolling.
2008 */
2009 bool IsPageScroll() const;
2010
2011 /**
2012 Returns @true if the mouse was leaving the window.
2013
2014 @see Entering().
2015 */
2016 bool Leaving() const;
2017
2018 /**
2019 Returns @true if the event was a left double click.
2020 */
2021 bool LeftDClick() const;
2022
2023 /**
2024 Returns @true if the left mouse button changed to down.
2025 */
2026 bool LeftDown() const;
2027
2028 /**
2029 Returns @true if the left mouse button is currently down, independent
2030 of the current event type.
2031
2032 Please notice that it is not the same as LeftDown() which returns @true if the
2033 event was generated by the left mouse button being pressed. Rather, it simply
2034 describes the state of the left mouse button at the time when the event was
2035 generated (so while it will be @true for a left click event, it can also be @true
2036 for a right click if it happened while the left mouse button was pressed).
2037
2038 This event is usually used in the mouse event handlers which process "move
2039 mouse" messages to determine whether the user is (still) dragging the mouse.
2040 */
2041 bool LeftIsDown() const;
2042
2043 /**
2044 Returns @true if the left mouse button changed to up.
2045 */
2046 bool LeftUp() const;
2047
2048 /**
2049 Returns @true if the Meta key was down at the time of the event.
2050 */
2051 bool MetaDown() const;
2052
2053 /**
2054 Returns @true if the event was a middle double click.
2055 */
2056 bool MiddleDClick() const;
2057
2058 /**
2059 Returns @true if the middle mouse button changed to down.
2060 */
2061 bool MiddleDown() const;
2062
2063 /**
2064 Returns @true if the middle mouse button is currently down, independent
2065 of the current event type.
2066 */
2067 bool MiddleIsDown() const;
2068
2069 /**
2070 Returns @true if the middle mouse button changed to up.
2071 */
2072 bool MiddleUp() const;
2073
2074 /**
2075 Returns @true if this was a motion event and no mouse buttons were pressed.
2076 If any mouse button is held pressed, then this method returns @false and
2077 Dragging() returns @true.
2078 */
2079 bool Moving() const;
2080
2081 /**
2082 Returns @true if the event was a right double click.
2083 */
2084 bool RightDClick() const;
2085
2086 /**
2087 Returns @true if the right mouse button changed to down.
2088 */
2089 bool RightDown() const;
2090
2091 /**
2092 Returns @true if the right mouse button is currently down, independent
2093 of the current event type.
2094 */
2095 bool RightIsDown() const;
2096
2097 /**
2098 Returns @true if the right mouse button changed to up.
2099 */
2100 bool RightUp() const;
2101 };
2102
2103
2104
2105 /**
2106 @class wxDropFilesEvent
2107
2108 This class is used for drop files events, that is, when files have been dropped
2109 onto the window. This functionality is currently only available under Windows.
2110
2111 The window must have previously been enabled for dropping by calling
2112 wxWindow::DragAcceptFiles().
2113
2114 Important note: this is a separate implementation to the more general drag and drop
2115 implementation documented in the @ref overview_dnd. It uses the older, Windows
2116 message-based approach of dropping files.
2117
2118 @beginEventTable{wxDropFilesEvent}
2119 @event{EVT_DROP_FILES(func)}
2120 Process a @c wxEVT_DROP_FILES event.
2121 @endEventTable
2122
2123 @onlyfor{wxmsw}
2124
2125 @library{wxcore}
2126 @category{events}
2127
2128 @see @ref overview_events
2129 */
2130 class wxDropFilesEvent : public wxEvent
2131 {
2132 public:
2133 /**
2134 Constructor.
2135 */
2136 wxDropFilesEvent(wxEventType id = 0, int noFiles = 0,
2137 wxString* files = NULL);
2138
2139 /**
2140 Returns an array of filenames.
2141 */
2142 wxString* GetFiles() const;
2143
2144 /**
2145 Returns the number of files dropped.
2146 */
2147 int GetNumberOfFiles() const;
2148
2149 /**
2150 Returns the position at which the files were dropped.
2151 Returns an array of filenames.
2152 */
2153 wxPoint GetPosition() const;
2154 };
2155
2156
2157
2158 /**
2159 @class wxCommandEvent
2160
2161 This event class contains information about command events, which originate
2162 from a variety of simple controls.
2163
2164 Note that wxCommandEvents and wxCommandEvent-derived event classes by default
2165 and unlike other wxEvent-derived classes propagate upward from the source
2166 window (the window which emits the event) up to the first parent which processes
2167 the event. Be sure to read @ref overview_events_propagation.
2168
2169 More complex controls, such as wxTreeCtrl, have separate command event classes.
2170
2171 @beginEventTable{wxCommandEvent}
2172 @event{EVT_COMMAND(id, event, func)}
2173 Process a command, supplying the window identifier, command event identifier,
2174 and member function.
2175 @event{EVT_COMMAND_RANGE(id1, id2, event, func)}
2176 Process a command for a range of window identifiers, supplying the minimum and
2177 maximum window identifiers, command event identifier, and member function.
2178 @event{EVT_BUTTON(id, func)}
2179 Process a @c wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control.
2180 @event{EVT_CHECKBOX(id, func)}
2181 Process a @c wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control.
2182 @event{EVT_CHOICE(id, func)}
2183 Process a @c wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control.
2184 @event{EVT_COMBOBOX(id, func)}
2185 Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control.
2186 @event{EVT_LISTBOX(id, func)}
2187 Process a @c wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control.
2188 @event{EVT_LISTBOX_DCLICK(id, func)}
2189 Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control.
2190 @event{EVT_CHECKLISTBOX(id, func)}
2191 Process a @c wxEVT_COMMAND_CHECKLISTBOX_TOGGLED command, which is generated by a wxCheckListBox control.
2192 @event{EVT_MENU(id, func)}
2193 Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
2194 @event{EVT_MENU_RANGE(id1, id2, func)}
2195 Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
2196 @event{EVT_CONTEXT_MENU(func)}
2197 Process the event generated when the user has requested a popup menu to appear by
2198 pressing a special keyboard key (under Windows) or by right clicking the mouse.
2199 @event{EVT_RADIOBOX(id, func)}
2200 Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control.
2201 @event{EVT_RADIOBUTTON(id, func)}
2202 Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control.
2203 @event{EVT_SCROLLBAR(id, func)}
2204 Process a @c wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar
2205 control. This is provided for compatibility only; more specific scrollbar event macros
2206 should be used instead (see wxScrollEvent).
2207 @event{EVT_SLIDER(id, func)}
2208 Process a @c wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control.
2209 @event{EVT_TEXT(id, func)}
2210 Process a @c wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control.
2211 @event{EVT_TEXT_ENTER(id, func)}
2212 Process a @c wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control.
2213 Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it
2214 to generate such events.
2215 @event{EVT_TEXT_MAXLEN(id, func)}
2216 Process a @c wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control
2217 when the user tries to enter more characters into it than the limit previously set
2218 with SetMaxLength().
2219 @event{EVT_TOGGLEBUTTON(id, func)}
2220 Process a @c wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event.
2221 @event{EVT_TOOL(id, func)}
2222 Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c wxEVT_COMMAND_MENU_SELECTED).
2223 Pass the id of the tool.
2224 @event{EVT_TOOL_RANGE(id1, id2, func)}
2225 Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools.
2226 @event{EVT_TOOL_RCLICKED(id, func)}
2227 Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool.
2228 @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
2229 Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools.
2230 @event{EVT_TOOL_ENTER(id, func)}
2231 Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself.
2232 The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor
2233 has moved off a tool.
2234 @event{EVT_COMMAND_LEFT_CLICK(id, func)}
2235 Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
2236 @event{EVT_COMMAND_LEFT_DCLICK(id, func)}
2237 Process a @c wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only).
2238 @event{EVT_COMMAND_RIGHT_CLICK(id, func)}
2239 Process a @c wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only).
2240 @event{EVT_COMMAND_SET_FOCUS(id, func)}
2241 Process a @c wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only).
2242 @event{EVT_COMMAND_KILL_FOCUS(id, func)}
2243 Process a @c wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only).
2244 @event{EVT_COMMAND_ENTER(id, func)}
2245 Process a @c wxEVT_COMMAND_ENTER command, which is generated by a control.
2246 @endEventTable
2247
2248 @library{wxcore}
2249 @category{events}
2250 */
2251 class wxCommandEvent : public wxEvent
2252 {
2253 public:
2254 /**
2255 Constructor.
2256 */
2257 wxCommandEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0);
2258
2259 /**
2260 Returns client data pointer for a listbox or choice selection event
2261 (not valid for a deselection).
2262 */
2263 void* GetClientData() const;
2264
2265 /**
2266 Returns client object pointer for a listbox or choice selection event
2267 (not valid for a deselection).
2268 */
2269 wxClientData* GetClientObject() const;
2270
2271 /**
2272 Returns extra information dependant on the event objects type.
2273
2274 If the event comes from a listbox selection, it is a boolean
2275 determining whether the event was a selection (@true) or a
2276 deselection (@false). A listbox deselection only occurs for
2277 multiple-selection boxes, and in this case the index and string values
2278 are indeterminate and the listbox must be examined by the application.
2279 */
2280 long GetExtraLong() const;
2281
2282 /**
2283 Returns the integer identifier corresponding to a listbox, choice or
2284 radiobox selection (only if the event was a selection, not a deselection),
2285 or a boolean value representing the value of a checkbox.
2286 */
2287 int GetInt() const;
2288
2289 /**
2290 Returns item index for a listbox or choice selection event (not valid for
2291 a deselection).
2292 */
2293 int GetSelection() const;
2294
2295 /**
2296 Returns item string for a listbox or choice selection event. If one
2297 or several items have been deselected, returns the index of the first
2298 deselected item. If some items have been selected and others deselected
2299 at the same time, it will return the index of the first selected item.
2300 */
2301 wxString GetString() const;
2302
2303 /**
2304 This method can be used with checkbox and menu events: for the checkboxes, the
2305 method returns @true for a selection event and @false for a deselection one.
2306 For the menu events, this method indicates if the menu item just has become
2307 checked or unchecked (and thus only makes sense for checkable menu items).
2308
2309 Notice that this method can not be used with wxCheckListBox currently.
2310 */
2311 bool IsChecked() const;
2312
2313 /**
2314 For a listbox or similar event, returns @true if it is a selection, @false
2315 if it is a deselection. If some items have been selected and others deselected
2316 at the same time, it will return @true.
2317 */
2318 bool IsSelection() const;
2319
2320 /**
2321 Sets the client data for this event.
2322 */
2323 void SetClientData(void* clientData);
2324
2325 /**
2326 Sets the client object for this event. The client object is not owned by the
2327 event object and the event object will not delete the client object in its destructor.
2328
2329 The client object must be owned and deleted by another object (e.g. a control)
2330 that has longer life time than the event object.
2331 */
2332 void SetClientObject(wxClientData* clientObject);
2333
2334 /**
2335 Sets the @b m_extraLong member.
2336 */
2337 void SetExtraLong(long extraLong);
2338
2339 /**
2340 Sets the @b m_commandInt member.
2341 */
2342 void SetInt(int intCommand);
2343
2344 /**
2345 Sets the @b m_commandString member.
2346 */
2347 void SetString(const wxString& string);
2348 };
2349
2350
2351
2352 /**
2353 @class wxActivateEvent
2354
2355 An activate event is sent when a window or application is being activated
2356 or deactivated.
2357
2358 @beginEventTable{wxActivateEvent}
2359 @event{EVT_ACTIVATE(func)}
2360 Process a @c wxEVT_ACTIVATE event.
2361 @event{EVT_ACTIVATE_APP(func)}
2362 Process a @c wxEVT_ACTIVATE_APP event.
2363 This event is received by the wxApp-derived instance only.
2364 @event{EVT_HIBERNATE(func)}
2365 Process a hibernate event, supplying the member function. This event applies
2366 to wxApp only, and only on Windows SmartPhone and PocketPC.
2367 It is generated when the system is low on memory; the application should free
2368 up as much memory as possible, and restore full working state when it receives
2369 a wxEVT_ACTIVATE or wxEVT_ACTIVATE_APP event.
2370 @endEventTable
2371
2372 @library{wxcore}
2373 @category{events}
2374
2375 @see @ref overview_events, wxApp::IsActive
2376 */
2377 class wxActivateEvent : public wxEvent
2378 {
2379 public:
2380 /**
2381 Constructor.
2382 */
2383 wxActivateEvent(wxEventType eventType = wxEVT_NULL, bool active = true,
2384 int id = 0);
2385
2386 /**
2387 Returns @true if the application or window is being activated, @false otherwise.
2388 */
2389 bool GetActive() const;
2390 };
2391
2392
2393
2394 /**
2395 @class wxContextMenuEvent
2396
2397 This class is used for context menu events, sent to give
2398 the application a chance to show a context (popup) menu for a wxWindow.
2399
2400 Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this
2401 means that the event originated from a keyboard context button event, and you
2402 should compute a suitable position yourself, for example by calling wxGetMousePosition().
2403
2404 When a keyboard context menu button is pressed on Windows, a right-click event
2405 with default position is sent first, and if this event is not processed, the
2406 context menu event is sent. So if you process mouse events and you find your
2407 context menu event handler is not being called, you could call wxEvent::Skip()
2408 for mouse right-down events.
2409
2410 @beginEventTable{wxContextMenuEvent}
2411 @event{EVT_CONTEXT_MENU(func)}
2412 A right click (or other context menu command depending on platform) has been detected.
2413 @endEventTable
2414
2415
2416 @library{wxcore}
2417 @category{events}
2418
2419 @see wxCommandEvent, @ref overview_events
2420 */
2421 class wxContextMenuEvent : public wxCommandEvent
2422 {
2423 public:
2424 /**
2425 Constructor.
2426 */
2427 wxContextMenuEvent(wxEventType id = wxEVT_NULL, int id = 0,
2428 const wxPoint& pos = wxDefaultPosition);
2429
2430 /**
2431 Returns the position in screen coordinates at which the menu should be shown.
2432 Use wxWindow::ScreenToClient to convert to client coordinates.
2433
2434 You can also omit a position from wxWindow::PopupMenu in order to use
2435 the current mouse pointer position.
2436
2437 If the event originated from a keyboard event, the value returned from this
2438 function will be wxDefaultPosition.
2439 */
2440 const wxPoint& GetPosition() const;
2441
2442 /**
2443 Sets the position at which the menu should be shown.
2444 */
2445 void SetPosition(const wxPoint& point);
2446 };
2447
2448
2449
2450 /**
2451 @class wxEraseEvent
2452
2453 An erase event is sent when a window's background needs to be repainted.
2454
2455 On some platforms, such as GTK+, this event is simulated (simply generated just
2456 before the paint event) and may cause flicker. It is therefore recommended that
2457 you set the text background colour explicitly in order to prevent flicker.
2458 The default background colour under GTK+ is grey.
2459
2460 To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table
2461 definition.
2462
2463 You must call wxEraseEvent::GetDC and use the returned device context if it is
2464 non-@NULL. If it is @NULL, create your own temporary wxClientDC object.
2465
2466 @remarks
2467 Use the device context returned by GetDC to draw on, don't create
2468 a wxPaintDC in the event handler.
2469
2470 @beginEventTable{wxEraseEvent}
2471 @event{EVT_ERASE_BACKGROUND(func)}
2472 Process a @c wxEVT_ERASE_BACKGROUND event.
2473 @endEventTable
2474
2475 @library{wxcore}
2476 @category{events}
2477
2478 @see @ref overview_events
2479 */
2480 class wxEraseEvent : public wxEvent
2481 {
2482 public:
2483 /**
2484 Constructor.
2485 */
2486 wxEraseEvent(int id = 0, wxDC* dc = NULL);
2487
2488 /**
2489 Returns the device context associated with the erase event to draw on.
2490 */
2491 wxDC* GetDC() const;
2492 };
2493
2494
2495
2496 /**
2497 @class wxFocusEvent
2498
2499 A focus event is sent when a window's focus changes. The window losing focus
2500 receives a "kill focus" event while the window gaining it gets a "set focus" one.
2501
2502 Notice that the set focus event happens both when the user gives focus to the
2503 window (whether using the mouse or keyboard) and when it is done from the
2504 program itself using wxWindow::SetFocus.
2505
2506 @beginEventTable{wxFocusEvent}
2507 @event{EVT_SET_FOCUS(func)}
2508 Process a @c wxEVT_SET_FOCUS event.
2509 @event{EVT_KILL_FOCUS(func)}
2510 Process a @c wxEVT_KILL_FOCUS event.
2511 @endEventTable
2512
2513 @library{wxcore}
2514 @category{events}
2515
2516 @see @ref overview_events
2517 */
2518 class wxFocusEvent : public wxEvent
2519 {
2520 public:
2521 /**
2522 Constructor.
2523 */
2524 wxFocusEvent(wxEventType eventType = wxEVT_NULL, int id = 0);
2525
2526 /**
2527 Returns the window associated with this event, that is the window which had the
2528 focus before for the @c wxEVT_SET_FOCUS event and the window which is
2529 going to receive focus for the @c wxEVT_KILL_FOCUS one.
2530
2531 Warning: the window pointer may be @NULL!
2532 */
2533 wxWindow *GetWindow() const;
2534 };
2535
2536
2537
2538 /**
2539 @class wxChildFocusEvent
2540
2541 A child focus event is sent to a (parent-)window when one of its child windows
2542 gains focus, so that the window could restore the focus back to its corresponding
2543 child if it loses it now and regains later.
2544
2545 Notice that child window is the direct child of the window receiving event.
2546 Use wxWindow::FindFocus() to retreive the window which is actually getting focus.
2547
2548 @beginEventTable{wxChildFocusEvent}
2549 @event{EVT_CHILD_FOCUS(func)}
2550 Process a @c wxEVT_CHILD_FOCUS event.
2551 @endEventTable
2552
2553 @library{wxcore}
2554 @category{events}
2555
2556 @see @ref overview_events
2557 */
2558 class wxChildFocusEvent : public wxCommandEvent
2559 {
2560 public:
2561 /**
2562 Constructor.
2563
2564 @param win
2565 The direct child which is (or which contains the window which is) receiving
2566 the focus.
2567 */
2568 wxChildFocusEvent(wxWindow* win = NULL);
2569
2570 /**
2571 Returns the direct child which receives the focus, or a (grand-)parent of the
2572 control receiving the focus.
2573
2574 To get the actually focused control use wxWindow::FindFocus.
2575 */
2576 wxWindow *GetWindow() const;
2577 };
2578
2579
2580
2581 /**
2582 @class wxMouseCaptureLostEvent
2583
2584 An mouse capture lost event is sent to a window that obtained mouse capture,
2585 which was subsequently loss due to "external" event, for example when a dialog
2586 box is shown or if another application captures the mouse.
2587
2588 If this happens, this event is sent to all windows that are on capture stack
2589 (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is
2590 not sent if the capture changes because of a call to CaptureMouse or
2591 ReleaseMouse.
2592
2593 This event is currently emitted under Windows only.
2594
2595 @beginEventTable{wxMouseCaptureLostEvent}
2596 @event{EVT_MOUSE_CAPTURE_LOST(func)}
2597 Process a @c wxEVT_MOUSE_CAPTURE_LOST event.
2598 @endEventTable
2599
2600 @onlyfor{wxmsw}
2601
2602 @library{wxcore}
2603 @category{events}
2604
2605 @see wxMouseCaptureChangedEvent, @ref overview_events,
2606 wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
2607 */
2608 class wxMouseCaptureLostEvent : public wxEvent
2609 {
2610 public:
2611 /**
2612 Constructor.
2613 */
2614 wxMouseCaptureLostEvent(wxWindowID windowId = 0);
2615 };
2616
2617
2618
2619 /**
2620 @class wxNotifyEvent
2621
2622 This class is not used by the event handlers by itself, but is a base class
2623 for other event classes (such as wxBookCtrlEvent).
2624
2625 It (or an object of a derived class) is sent when the controls state is being
2626 changed and allows the program to wxNotifyEvent::Veto() this change if it wants
2627 to prevent it from happening.
2628
2629 @library{wxcore}
2630 @category{events}
2631
2632 @see wxBookCtrlEvent
2633 */
2634 class wxNotifyEvent : public wxCommandEvent
2635 {
2636 public:
2637 /**
2638 Constructor (used internally by wxWidgets only).
2639 */
2640 wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0);
2641
2642 /**
2643 This is the opposite of Veto(): it explicitly allows the event to be processed.
2644 For most events it is not necessary to call this method as the events are allowed
2645 anyhow but some are forbidden by default (this will be mentioned in the corresponding
2646 event description).
2647 */
2648 void Allow();
2649
2650 /**
2651 Returns @true if the change is allowed (Veto() hasn't been called) or @false
2652 otherwise (if it was).
2653 */
2654 bool IsAllowed() const;
2655
2656 /**
2657 Prevents the change announced by this event from happening.
2658
2659 It is in general a good idea to notify the user about the reasons for vetoing
2660 the change because otherwise the applications behaviour (which just refuses to
2661 do what the user wants) might be quite surprising.
2662 */
2663 void Veto();
2664 };
2665
2666
2667 /**
2668 @class wxThreadEvent
2669
2670 This class adds some simple functionalities to wxCommandEvent coinceived
2671 for inter-threads communications.
2672
2673 This event is not natively emitted by any control/class: this is just
2674 an helper class for the user.
2675 Its most important feature is the GetEventCategory() implementation which
2676 allows thread events to @b NOT be processed by wxEventLoopBase::YieldFor calls
2677 (unless the @c wxEVT_CATEGORY_THREAD is specified - which is never in wx code).
2678
2679 @library{wxcore}
2680 @category{events,threading}
2681
2682 @see @ref overview_thread, wxEventLoopBase::YieldFor
2683 */
2684 class wxThreadEvent : public wxCommandEvent
2685 {
2686 public:
2687 /**
2688 Constructor.
2689 */
2690 wxThreadEvent(wxEventType eventType = wxEVT_COMMAND_THREAD, int id = wxID_ANY);
2691
2692 /**
2693 Clones this event making sure that all internal members which use
2694 COW (only @c m_commandString for now; see @ref overview_refcount)
2695 are unshared (see wxObject::UnShare).
2696 */
2697 virtual wxEvent *Clone() const;
2698
2699 /**
2700 Returns @c wxEVT_CATEGORY_THREAD.
2701
2702 This is important to avoid unwanted processing of thread events
2703 when calling wxEventLoopBase::YieldFor().
2704 */
2705 virtual wxEventCategory GetEventCategory() const;
2706 };
2707
2708
2709 /**
2710 @class wxHelpEvent
2711
2712 A help event is sent when the user has requested context-sensitive help.
2713 This can either be caused by the application requesting context-sensitive help mode
2714 via wxContextHelp, or (on MS Windows) by the system generating a WM_HELP message when
2715 the user pressed F1 or clicked on the query button in a dialog caption.
2716
2717 A help event is sent to the window that the user clicked on, and is propagated
2718 up the window hierarchy until the event is processed or there are no more event
2719 handlers.
2720
2721 The application should call wxEvent::GetId to check the identity of the
2722 clicked-on window, and then either show some suitable help or call wxEvent::Skip()
2723 if the identifier is unrecognised.
2724
2725 Calling Skip is important because it allows wxWidgets to generate further
2726 events for ancestors of the clicked-on window. Otherwise it would be impossible to
2727 show help for container windows, since processing would stop after the first window
2728 found.
2729
2730 @beginEventTable{wxHelpEvent}
2731 @event{EVT_HELP(id, func)}
2732 Process a @c wxEVT_HELP event.
2733 @event{EVT_HELP_RANGE(id1, id2, func)}
2734 Process a @c wxEVT_HELP event for a range of ids.
2735 @endEventTable
2736
2737 @library{wxcore}
2738 @category{events}
2739
2740 @see wxContextHelp, wxDialog, @ref overview_events
2741 */
2742 class wxHelpEvent : public wxCommandEvent
2743 {
2744 public:
2745 /**
2746 Indicates how a wxHelpEvent was generated.
2747 */
2748 enum Origin
2749 {
2750 Origin_Unknown, /**< unrecognized event source. */
2751 Origin_Keyboard, /**< event generated from F1 key press. */
2752
2753 /** event generated by wxContextHelp or from the [?] button on
2754 the title bar (Windows). */
2755 Origin_HelpButton
2756 };
2757
2758 /**
2759 Constructor.
2760 */
2761 wxHelpEvent(wxEventType type = wxEVT_NULL,
2762 wxWindowID winid = 0,
2763 const wxPoint& pt = wxDefaultPosition,
2764 wxHelpEvent::Origin origin = Origin_Unknown);
2765
2766 /**
2767 Returns the origin of the help event which is one of the ::wxHelpEventOrigin
2768 values.
2769
2770 The application may handle events generated using the keyboard or mouse
2771 differently, e.g. by using wxGetMousePosition() for the mouse events.
2772
2773 @see SetOrigin()
2774 */
2775 wxHelpEvent::Origin GetOrigin() const;
2776
2777 /**
2778 Returns the left-click position of the mouse, in screen coordinates.
2779 This allows the application to position the help appropriately.
2780 */
2781 const wxPoint& GetPosition() const;
2782
2783 /**
2784 Set the help event origin, only used internally by wxWidgets normally.
2785
2786 @see GetOrigin()
2787 */
2788 void SetOrigin(wxHelpEvent::Origin origin);
2789
2790 /**
2791 Sets the left-click position of the mouse, in screen coordinates.
2792 */
2793 void SetPosition(const wxPoint& pt);
2794 };
2795
2796
2797
2798 /**
2799 @class wxScrollEvent
2800
2801 A scroll event holds information about events sent from stand-alone
2802 scrollbars (see wxScrollBar) and sliders (see wxSlider).
2803
2804 Note that scrolled windows send the wxScrollWinEvent which does not derive from
2805 wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of
2806 events and use the event table macros mentioned below only for the scrollbar-like
2807 controls.
2808
2809 @section scrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
2810
2811 The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb
2812 using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed
2813 by an EVT_SCROLL_CHANGED event).
2814
2815 The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change the thumb
2816 position, and when clicking next to the thumb (In all these cases the EVT_SCROLL_THUMBRELEASE
2817 event does not happen).
2818
2819 In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving has finished
2820 independently of the way it had started. Please see the widgets sample ("Slider" page)
2821 to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action.
2822
2823 @remarks
2824 Note that unless specifying a scroll control identifier, you will need to test for scrollbar
2825 orientation with wxScrollEvent::GetOrientation, since horizontal and vertical scroll events
2826 are processed using the same event handler.
2827
2828 @beginEventTable{wxScrollEvent}
2829 You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting
2830 scroll events from controls, or EVT_SCROLL... macros without window IDs for
2831 intercepting scroll events from the receiving window -- except for this, the
2832 macros behave exactly the same.
2833 @event{EVT_SCROLL(func)}
2834 Process all scroll events.
2835 @event{EVT_SCROLL_TOP(func)}
2836 Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
2837 @event{EVT_SCROLL_BOTTOM(func)}
2838 Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
2839 @event{EVT_SCROLL_LINEUP(func)}
2840 Process wxEVT_SCROLL_LINEUP line up events.
2841 @event{EVT_SCROLL_LINEDOWN(func)}
2842 Process wxEVT_SCROLL_LINEDOWN line down events.
2843 @event{EVT_SCROLL_PAGEUP(func)}
2844 Process wxEVT_SCROLL_PAGEUP page up events.
2845 @event{EVT_SCROLL_PAGEDOWN(func)}
2846 Process wxEVT_SCROLL_PAGEDOWN page down events.
2847 @event{EVT_SCROLL_THUMBTRACK(func)}
2848 Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent as the
2849 user drags the thumbtrack).
2850 @event{EVT_SCROLL_THUMBRELEASE(func)}
2851 Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
2852 @event{EVT_SCROLL_CHANGED(func)}
2853 Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
2854 @event{EVT_COMMAND_SCROLL(id, func)}
2855 Process all scroll events.
2856 @event{EVT_COMMAND_SCROLL_TOP(id, func)}
2857 Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
2858 @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)}
2859 Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
2860 @event{EVT_COMMAND_SCROLL_LINEUP(id, func)}
2861 Process wxEVT_SCROLL_LINEUP line up events.
2862 @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)}
2863 Process wxEVT_SCROLL_LINEDOWN line down events.
2864 @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)}
2865 Process wxEVT_SCROLL_PAGEUP page up events.
2866 @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)}
2867 Process wxEVT_SCROLL_PAGEDOWN page down events.
2868 @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)}
2869 Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent
2870 as the user drags the thumbtrack).
2871 @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)}
2872 Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
2873 @event{EVT_COMMAND_SCROLL_CHANGED(func)}
2874 Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
2875 @endEventTable
2876
2877 @library{wxcore}
2878 @category{events}
2879
2880 @see wxScrollBar, wxSlider, wxSpinButton, wxScrollWinEvent, @ref overview_events
2881 */
2882 class wxScrollEvent : public wxCommandEvent
2883 {
2884 public:
2885 /**
2886 Constructor.
2887 */
2888 wxScrollEvent(wxEventType commandType = wxEVT_NULL, int id = 0, int pos = 0,
2889 int orientation = 0);
2890
2891 /**
2892 Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
2893 scrollbar.
2894 */
2895 int GetOrientation() const;
2896
2897 /**
2898 Returns the position of the scrollbar.
2899 */
2900 int GetPosition() const;
2901 };
2902
2903 /**
2904 See wxIdleEvent::SetMode() for more info.
2905 */
2906 enum wxIdleMode
2907 {
2908 /** Send idle events to all windows */
2909 wxIDLE_PROCESS_ALL,
2910
2911 /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */
2912 wxIDLE_PROCESS_SPECIFIED
2913 };
2914
2915
2916 /**
2917 @class wxIdleEvent
2918
2919 This class is used for idle events, which are generated when the system becomes
2920 idle. Note that, unless you do something specifically, the idle events are not
2921 sent if the system remains idle once it has become it, e.g. only a single idle
2922 event will be generated until something else resulting in more normal events
2923 happens and only then is the next idle event sent again.
2924
2925 If you need to ensure a continuous stream of idle events, you can either use
2926 wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically
2927 (for example from a timer event handler), but note that both of these approaches
2928 (and especially the first one) increase the system load and so should be avoided
2929 if possible.
2930
2931 By default, idle events are sent to all windows (and also wxApp, as usual).
2932 If this is causing a significant overhead in your application, you can call
2933 wxIdleEvent::SetMode with the value wxIDLE_PROCESS_SPECIFIED, and set the
2934 wxWS_EX_PROCESS_IDLE extra window style for every window which should receive
2935 idle events.
2936
2937 @beginEventTable{wxIdleEvent}
2938 @event{EVT_IDLE(func)}
2939 Process a @c wxEVT_IDLE event.
2940 @endEventTable
2941
2942 @library{wxbase}
2943 @category{events}
2944
2945 @see @ref overview_events, wxUpdateUIEvent, wxWindow::OnInternalIdle
2946 */
2947 class wxIdleEvent : public wxEvent
2948 {
2949 public:
2950 /**
2951 Constructor.
2952 */
2953 wxIdleEvent();
2954
2955 /**
2956 Returns @true if it is appropriate to send idle events to this window.
2957
2958 This function looks at the mode used (see wxIdleEvent::SetMode),
2959 and the wxWS_EX_PROCESS_IDLE style in @a window to determine whether idle
2960 events should be sent to this window now.
2961
2962 By default this will always return @true because the update mode is initially
2963 wxIDLE_PROCESS_ALL. You can change the mode to only send idle events to
2964 windows with the wxWS_EX_PROCESS_IDLE extra window style set.
2965
2966 @see SetMode()
2967 */
2968 static bool CanSend(wxWindow* window);
2969
2970 /**
2971 Static function returning a value specifying how wxWidgets will send idle
2972 events: to all windows, or only to those which specify that they
2973 will process the events.
2974
2975 @see SetMode().
2976 */
2977 static wxIdleMode GetMode();
2978
2979 /**
2980 Returns @true if the OnIdle function processing this event requested more
2981 processing time.
2982
2983 @see RequestMore()
2984 */
2985 bool MoreRequested() const;
2986
2987 /**
2988 Tells wxWidgets that more processing is required.
2989
2990 This function can be called by an OnIdle handler for a window or window event
2991 handler to indicate that wxApp::OnIdle should forward the OnIdle event once
2992 more to the application windows.
2993
2994 If no window calls this function during OnIdle, then the application will
2995 remain in a passive event loop (not calling OnIdle) until a new event is
2996 posted to the application by the windowing system.
2997
2998 @see MoreRequested()
2999 */
3000 void RequestMore(bool needMore = true);
3001
3002 /**
3003 Static function for specifying how wxWidgets will send idle events: to
3004 all windows, or only to those which specify that they will process the events.
3005
3006 @param mode
3007 Can be one of the ::wxIdleMode values.
3008 The default is wxIDLE_PROCESS_ALL.
3009 */
3010 static void SetMode(wxIdleMode mode);
3011 };
3012
3013
3014
3015 /**
3016 @class wxInitDialogEvent
3017
3018 A wxInitDialogEvent is sent as a dialog or panel is being initialised.
3019 Handlers for this event can transfer data to the window.
3020
3021 The default handler calls wxWindow::TransferDataToWindow.
3022
3023 @beginEventTable{wxInitDialogEvent}
3024 @event{EVT_INIT_DIALOG(func)}
3025 Process a @c wxEVT_INIT_DIALOG event.
3026 @endEventTable
3027
3028 @library{wxcore}
3029 @category{events}
3030
3031 @see @ref overview_events
3032 */
3033 class wxInitDialogEvent : public wxEvent
3034 {
3035 public:
3036 /**
3037 Constructor.
3038 */
3039 wxInitDialogEvent(int id = 0);
3040 };
3041
3042
3043
3044 /**
3045 @class wxWindowDestroyEvent
3046
3047 This event is sent as early as possible during the window destruction
3048 process.
3049
3050 For the top level windows, as early as possible means that this is done by
3051 wxFrame or wxDialog destructor, i.e. after the destructor of the derived
3052 class was executed and so any methods specific to the derived class can't
3053 be called any more from this event handler. If you need to do this, you
3054 must call wxWindow::SendDestroyEvent() from your derived class destructor.
3055
3056 For the child windows, this event is generated just before deleting the
3057 window from wxWindow::Destroy() (which is also called when the parent
3058 window is deleted) or from the window destructor if operator @c delete was
3059 used directly (which is not recommended for this very reason).
3060
3061 It is usually pointless to handle this event in the window itself but it ca
3062 be very useful to receive notifications about the window destruction in the
3063 parent window or in any other object interested in this window.
3064
3065 @library{wxcore}
3066 @category{events}
3067
3068 @see @ref overview_events, wxWindowCreateEvent
3069 */
3070 class wxWindowDestroyEvent : public wxCommandEvent
3071 {
3072 public:
3073 /**
3074 Constructor.
3075 */
3076 wxWindowDestroyEvent(wxWindow* win = NULL);
3077
3078 /// Retutn the window being destroyed.
3079 wxWindow *GetWindow() const;
3080 };
3081
3082
3083 /**
3084 @class wxNavigationKeyEvent
3085
3086 This event class contains information about navigation events,
3087 generated by navigation keys such as tab and page down.
3088
3089 This event is mainly used by wxWidgets implementations.
3090 A wxNavigationKeyEvent handler is automatically provided by wxWidgets
3091 when you make a class into a control container with the macro
3092 WX_DECLARE_CONTROL_CONTAINER.
3093
3094 @beginEventTable{wxNavigationKeyEvent}
3095 @event{EVT_NAVIGATION_KEY(func)}
3096 Process a navigation key event.
3097 @endEventTable
3098
3099 @library{wxcore}
3100 @category{events}
3101
3102 @see wxWindow::Navigate, wxWindow::NavigateIn
3103 */
3104 class wxNavigationKeyEvent : public wxEvent
3105 {
3106 public:
3107 /**
3108 Flags which can be used with wxNavigationKeyEvent.
3109 */
3110 enum wxNavigationKeyEventFlags
3111 {
3112 IsBackward = 0x0000,
3113 IsForward = 0x0001,
3114 WinChange = 0x0002,
3115 FromTab = 0x0004
3116 };
3117
3118 wxNavigationKeyEvent();
3119 wxNavigationKeyEvent(const wxNavigationKeyEvent& event);
3120
3121 /**
3122 Returns the child that has the focus, or @NULL.
3123 */
3124 wxWindow* GetCurrentFocus() const;
3125
3126 /**
3127 Returns @true if the navigation was in the forward direction.
3128 */
3129 bool GetDirection() const;
3130
3131 /**
3132 Returns @true if the navigation event was from a tab key.
3133 This is required for proper navigation over radio buttons.
3134 */
3135 bool IsFromTab() const;
3136
3137 /**
3138 Returns @true if the navigation event represents a window change
3139 (for example, from Ctrl-Page Down in a notebook).
3140 */
3141 bool IsWindowChange() const;
3142
3143 /**
3144 Sets the current focus window member.
3145 */
3146 void SetCurrentFocus(wxWindow* currentFocus);
3147
3148 /**
3149 Sets the direction to forward if @a direction is @true, or backward
3150 if @false.
3151 */
3152 void SetDirection(bool direction);
3153
3154 /**
3155 Sets the flags for this event.
3156 The @a flags can be a combination of the ::wxNavigationKeyEventFlags values.
3157 */
3158 void SetFlags(long flags);
3159
3160 /**
3161 Marks the navigation event as from a tab key.
3162 */
3163 void SetFromTab(bool fromTab);
3164
3165 /**
3166 Marks the event as a window change event.
3167 */
3168 void SetWindowChange(bool windowChange);
3169 };
3170
3171
3172
3173 /**
3174 @class wxMouseCaptureChangedEvent
3175
3176 An mouse capture changed event is sent to a window that loses its
3177 mouse capture. This is called even if wxWindow::ReleaseMouse
3178 was called by the application code. Handling this event allows
3179 an application to cater for unexpected capture releases which
3180 might otherwise confuse mouse handling code.
3181
3182 @onlyfor{wxmsw}
3183
3184 @beginEventTable{wxMouseCaptureChangedEvent}
3185 @event{EVT_MOUSE_CAPTURE_CHANGED(func)}
3186 Process a @c wxEVT_MOUSE_CAPTURE_CHANGED event.
3187 @endEventTable
3188
3189 @library{wxcore}
3190 @category{events}
3191
3192 @see wxMouseCaptureLostEvent, @ref overview_events,
3193 wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
3194 */
3195 class wxMouseCaptureChangedEvent : public wxEvent
3196 {
3197 public:
3198 /**
3199 Constructor.
3200 */
3201 wxMouseCaptureChangedEvent(wxWindowID windowId = 0,
3202 wxWindow* gainedCapture = NULL);
3203
3204 /**
3205 Returns the window that gained the capture, or @NULL if it was a
3206 non-wxWidgets window.
3207 */
3208 wxWindow* GetCapturedWindow() const;
3209 };
3210
3211
3212
3213 /**
3214 @class wxCloseEvent
3215
3216 This event class contains information about window and session close events.
3217
3218 The handler function for EVT_CLOSE is called when the user has tried to close a
3219 a frame or dialog box using the window manager (X) or system menu (Windows).
3220 It can also be invoked by the application itself programmatically, for example by
3221 calling the wxWindow::Close function.
3222
3223 You should check whether the application is forcing the deletion of the window
3224 using wxCloseEvent::CanVeto. If this is @false, you @e must destroy the window
3225 using wxWindow::Destroy.
3226
3227 If the return value is @true, it is up to you whether you respond by destroying
3228 the window.
3229
3230 If you don't destroy the window, you should call wxCloseEvent::Veto to
3231 let the calling code know that you did not destroy the window.
3232 This allows the wxWindow::Close function to return @true or @false depending
3233 on whether the close instruction was honoured or not.
3234
3235 Example of a wxCloseEvent handler:
3236
3237 @code
3238 void MyFrame::OnClose(wxCloseEvent& event)
3239 {
3240 if ( event.CanVeto() && m_bFileNotSaved )
3241 {
3242 if ( wxMessageBox("The file has not been saved... continue closing?",
3243 "Please confirm",
3244 wxICON_QUESTION | wxYES_NO) != wxYES )
3245 {
3246 event.Veto();
3247 return;
3248 }
3249 }
3250
3251 Destroy(); // you may also do: event.Skip();
3252 // since the default event handler does call Destroy(), too
3253 }
3254 @endcode
3255
3256 The EVT_END_SESSION event is slightly different as it is sent by the system
3257 when the user session is ending (e.g. because of log out or shutdown) and
3258 so all windows are being forcefully closed. At least under MSW, after the
3259 handler for this event is executed the program is simply killed by the
3260 system. Because of this, the default handler for this event provided by
3261 wxWidgets calls all the usual cleanup code (including wxApp::OnExit()) so
3262 that it could still be executed and exit()s the process itself, without
3263 waiting for being killed. If this behaviour is for some reason undesirable,
3264 make sure that you define a handler for this event in your wxApp-derived
3265 class and do not call @c event.Skip() in it (but be aware that the system
3266 will still kill your application).
3267
3268 @beginEventTable{wxCloseEvent}
3269 @event{EVT_CLOSE(func)}
3270 Process a close event, supplying the member function.
3271 This event applies to wxFrame and wxDialog classes.
3272 @event{EVT_QUERY_END_SESSION(func)}
3273 Process a query end session event, supplying the member function.
3274 This event can be handled in wxApp-derived class only.
3275 @event{EVT_END_SESSION(func)}
3276 Process an end session event, supplying the member function.
3277 This event can be handled in wxApp-derived class only.
3278 @endEventTable
3279
3280 @library{wxcore}
3281 @category{events}
3282
3283 @see wxWindow::Close, @ref overview_windowdeletion
3284 */
3285 class wxCloseEvent : public wxEvent
3286 {
3287 public:
3288 /**
3289 Constructor.
3290 */
3291 wxCloseEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0);
3292
3293 /**
3294 Returns @true if you can veto a system shutdown or a window close event.
3295 Vetoing a window close event is not possible if the calling code wishes to
3296 force the application to exit, and so this function must be called to check this.
3297 */
3298 bool CanVeto() const;
3299
3300 /**
3301 Returns @true if the user is just logging off or @false if the system is
3302 shutting down. This method can only be called for end session and query end
3303 session events, it doesn't make sense for close window event.
3304 */
3305 bool GetLoggingOff() const;
3306
3307 /**
3308 Sets the 'can veto' flag.
3309 */
3310 void SetCanVeto(bool canVeto);
3311
3312 /**
3313 Sets the 'logging off' flag.
3314 */
3315 void SetLoggingOff(bool loggingOff);
3316
3317 /**
3318 Call this from your event handler to veto a system shutdown or to signal
3319 to the calling application that a window close did not happen.
3320
3321 You can only veto a shutdown if CanVeto() returns @true.
3322 */
3323 void Veto(bool veto = true);
3324 };
3325
3326
3327
3328 /**
3329 @class wxMenuEvent
3330
3331 This class is used for a variety of menu-related events. Note that
3332 these do not include menu command events, which are
3333 handled using wxCommandEvent objects.
3334
3335 The default handler for @c wxEVT_MENU_HIGHLIGHT displays help
3336 text in the first field of the status bar.
3337
3338 @beginEventTable{wxMenuEvent}
3339 @event{EVT_MENU_OPEN(func)}
3340 A menu is about to be opened. On Windows, this is only sent once for each
3341 navigation of the menubar (up until all menus have closed).
3342 @event{EVT_MENU_CLOSE(func)}
3343 A menu has been just closed.
3344 @event{EVT_MENU_HIGHLIGHT(id, func)}
3345 The menu item with the specified id has been highlighted: used to show
3346 help prompts in the status bar by wxFrame
3347 @event{EVT_MENU_HIGHLIGHT_ALL(func)}
3348 A menu item has been highlighted, i.e. the currently selected menu item has changed.
3349 @endEventTable
3350
3351 @library{wxcore}
3352 @category{events}
3353
3354 @see wxCommandEvent, @ref overview_events
3355 */
3356 class wxMenuEvent : public wxEvent
3357 {
3358 public:
3359 /**
3360 Constructor.
3361 */
3362 wxMenuEvent(wxEventType id = wxEVT_NULL, int id = 0, wxMenu* menu = NULL);
3363
3364 /**
3365 Returns the menu which is being opened or closed. This method should only be
3366 used with the @c OPEN and @c CLOSE events and even for them the
3367 returned pointer may be @NULL in some ports.
3368 */
3369 wxMenu* GetMenu() const;
3370
3371 /**
3372 Returns the menu identifier associated with the event.
3373 This method should be only used with the @c HIGHLIGHT events.
3374 */
3375 int GetMenuId() const;
3376
3377 /**
3378 Returns @true if the menu which is being opened or closed is a popup menu,
3379 @false if it is a normal one.
3380
3381 This method should only be used with the @c OPEN and @c CLOSE events.
3382 */
3383 bool IsPopup() const;
3384 };
3385
3386 /**
3387 @class wxShowEvent
3388
3389 An event being sent when the window is shown or hidden.
3390
3391 Currently only wxMSW, wxGTK and wxOS2 generate such events.
3392
3393 @onlyfor{wxmsw,wxgtk,wxos2}
3394
3395 @beginEventTable{wxShowEvent}
3396 @event{EVT_SHOW(func)}
3397 Process a @c wxEVT_SHOW event.
3398 @endEventTable
3399
3400 @library{wxcore}
3401 @category{events}
3402
3403 @see @ref overview_events, wxWindow::Show,
3404 wxWindow::IsShown
3405 */
3406
3407 class wxShowEvent : public wxEvent
3408 {
3409 public:
3410 /**
3411 Constructor.
3412 */
3413 wxShowEvent(int winid = 0, bool show = false);
3414
3415 /**
3416 Set whether the windows was shown or hidden.
3417 */
3418 void SetShow(bool show);
3419
3420 /**
3421 Return @true if the window has been shown, @false if it has been
3422 hidden.
3423 */
3424 bool IsShown() const;
3425
3426 /**
3427 @deprecated This function is deprecated in favour of IsShown().
3428 */
3429 bool GetShow() const;
3430 };
3431
3432
3433
3434 /**
3435 @class wxIconizeEvent
3436
3437 An event being sent when the frame is iconized (minimized) or restored.
3438
3439 Currently only wxMSW and wxGTK generate such events.
3440
3441 @onlyfor{wxmsw,wxgtk}
3442
3443 @beginEventTable{wxIconizeEvent}
3444 @event{EVT_ICONIZE(func)}
3445 Process a @c wxEVT_ICONIZE event.
3446 @endEventTable
3447
3448 @library{wxcore}
3449 @category{events}
3450
3451 @see @ref overview_events, wxTopLevelWindow::Iconize,
3452 wxTopLevelWindow::IsIconized
3453 */
3454 class wxIconizeEvent : public wxEvent
3455 {
3456 public:
3457 /**
3458 Constructor.
3459 */
3460 wxIconizeEvent(int id = 0, bool iconized = true);
3461
3462 /**
3463 Returns @true if the frame has been iconized, @false if it has been
3464 restored.
3465 */
3466 bool IsIconized() const;
3467
3468 /**
3469 @deprecated This function is deprecated in favour of IsIconized().
3470 */
3471 bool Iconized() const;
3472 };
3473
3474
3475
3476 /**
3477 @class wxMoveEvent
3478
3479 A move event holds information about wxTopLevelWindow move change events.
3480
3481 @beginEventTable{wxMoveEvent}
3482 @event{EVT_MOVE(func)}
3483 Process a @c wxEVT_MOVE event, which is generated when a window is moved.
3484 @event{EVT_MOVE_START(func)}
3485 Process a @c wxEVT_MOVE_START event, which is generated when the user starts
3486 to move or size a window. wxMSW only.
3487 @event{EVT_MOVE_END(func)}
3488 Process a @c wxEVT_MOVE_END event, which is generated when the user stops
3489 moving or sizing a window. wxMSW only.
3490 @endEventTable
3491
3492 @library{wxcore}
3493 @category{events}
3494
3495 @see wxPoint, @ref overview_events
3496 */
3497 class wxMoveEvent : public wxEvent
3498 {
3499 public:
3500 /**
3501 Constructor.
3502 */
3503 wxMoveEvent(const wxPoint& pt, int id = 0);
3504
3505 /**
3506 Returns the position of the window generating the move change event.
3507 */
3508 wxPoint GetPosition() const;
3509 };
3510
3511
3512 /**
3513 @class wxSizeEvent
3514
3515 A size event holds information about size change events of wxWindow.
3516
3517 The EVT_SIZE handler function will be called when the window has been resized.
3518
3519 You may wish to use this for frames to resize their child windows as appropriate.
3520
3521 Note that the size passed is of the whole window: call wxWindow::GetClientSize
3522 for the area which may be used by the application.
3523
3524 When a window is resized, usually only a small part of the window is damaged
3525 and you may only need to repaint that area. However, if your drawing depends on the
3526 size of the window, you may need to clear the DC explicitly and repaint the whole window.
3527 In which case, you may need to call wxWindow::Refresh to invalidate the entire window.
3528
3529 @beginEventTable{wxSizeEvent}
3530 @event{EVT_SIZE(func)}
3531 Process a @c wxEVT_SIZE event.
3532 @endEventTable
3533
3534 @library{wxcore}
3535 @category{events}
3536
3537 @see wxSize, @ref overview_events
3538 */
3539 class wxSizeEvent : public wxEvent
3540 {
3541 public:
3542 /**
3543 Constructor.
3544 */
3545 wxSizeEvent(const wxSize& sz, int id = 0);
3546
3547 /**
3548 Returns the entire size of the window generating the size change event.
3549 */
3550 wxSize GetSize() const;
3551 };
3552
3553
3554
3555 /**
3556 @class wxSetCursorEvent
3557
3558 A wxSetCursorEvent is generated from wxWindow when the mouse cursor is about
3559 to be set as a result of mouse motion.
3560
3561 This event gives the application the chance to perform specific mouse cursor
3562 processing based on the current position of the mouse within the window.
3563 Use wxSetCursorEvent::SetCursor to specify the cursor you want to be displayed.
3564
3565 @beginEventTable{wxSetCursorEvent}
3566 @event{EVT_SET_CURSOR(func)}
3567 Process a @c wxEVT_SET_CURSOR event.
3568 @endEventTable
3569
3570 @library{wxcore}
3571 @category{events}
3572
3573 @see ::wxSetCursor, wxWindow::wxSetCursor
3574 */
3575 class wxSetCursorEvent : public wxEvent
3576 {
3577 public:
3578 /**
3579 Constructor, used by the library itself internally to initialize the event
3580 object.
3581 */
3582 wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0);
3583
3584 /**
3585 Returns a reference to the cursor specified by this event.
3586 */
3587 const wxCursor& GetCursor() const;
3588
3589 /**
3590 Returns the X coordinate of the mouse in client coordinates.
3591 */
3592 wxCoord GetX() const;
3593
3594 /**
3595 Returns the Y coordinate of the mouse in client coordinates.
3596 */
3597 wxCoord GetY() const;
3598
3599 /**
3600 Returns @true if the cursor specified by this event is a valid cursor.
3601
3602 @remarks You cannot specify wxNullCursor with this event, as it is not
3603 considered a valid cursor.
3604 */
3605 bool HasCursor() const;
3606
3607 /**
3608 Sets the cursor associated with this event.
3609 */
3610 void SetCursor(const wxCursor& cursor);
3611 };
3612
3613
3614
3615 // ============================================================================
3616 // Global functions/macros
3617 // ============================================================================
3618
3619 /** @addtogroup group_funcmacro_events */
3620 //@{
3621
3622 /**
3623 A value uniquely identifying the type of the event.
3624
3625 The values of this type should only be created using wxNewEventType().
3626
3627 See the macro DEFINE_EVENT_TYPE() for more info.
3628
3629 @see @ref overview_events_introduction
3630 */
3631 typedef int wxEventType;
3632
3633 /**
3634 A special event type usually used to indicate that some wxEvent has yet
3635 no type assigned.
3636 */
3637 wxEventType wxEVT_NULL;
3638
3639 /**
3640 Initializes a new event type using wxNewEventType().
3641
3642 @deprecated Use wxDEFINE_EVENT() instead
3643 */
3644 #define DEFINE_EVENT_TYPE(name) const wxEventType name = wxNewEventType();
3645
3646 /**
3647 Generates a new unique event type.
3648
3649 Usually this function is only used by wxDEFINE_EVENT() and not called
3650 directly.
3651 */
3652 wxEventType wxNewEventType();
3653
3654 /**
3655 Define a new event type associated with the specified event class.
3656
3657 This macro defines a new unique event type @a name associated with the
3658 event class @a cls.
3659
3660 For example:
3661 @code
3662 wxDEFINE_EVENT(MY_COMMAND_EVENT, wxCommandEvent);
3663
3664 class MyCustomEvent : public wxEvent { ... };
3665 wxDEFINE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent);
3666 @endcode
3667
3668 @see wxDECLARE_EVENT(), @ref overview_events_custom
3669 */
3670 #define wxDEFINE_EVENT(name, cls) \
3671 const wxEventTypeTag< cls > name(wxNewEventType())
3672
3673 /**
3674 Declares a custom event type.
3675
3676 This macro declares a variable called @a name which must be defined
3677 elsewhere using wxDEFINE_EVENT().
3678
3679 The class @a cls must be the wxEvent-derived class associated with the
3680 events of this type and its full declaration must be visible from the point
3681 of use of this macro.
3682 */
3683 #define wxDECLARE_EVENT(name, cls) \
3684 wxDECLARE_EXPORTED_EVENT(wxEMPTY_PARAMETER_VALUE, name, cls)
3685
3686 /**
3687 Variant of wxDECLARE_EVENT() used for event types defined inside a shared
3688 library.
3689
3690 This is mostly used by wxWidgets internally, e.g.
3691 @code
3692 wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_CORE, wxEVT_COMMAND_BUTTON_CLICKED, wxCommandEvent)
3693 @endcode
3694 */
3695 #define wxDECLARE_EXPORTED_EVENT( expdecl, name, cls ) \
3696 extern const expdecl wxEventTypeTag< cls > name;
3697
3698 /**
3699 Helper macro for definition of custom event table macros.
3700
3701 This macro must only be used if wxEVENTS_COMPATIBILITY_2_8 is 1, otherwise
3702 it is better and more clear to just use the address of the function
3703 directly as this is all this macro does in this case. However it needs to
3704 explicitly cast @a func to @a functype, which is the type of wxEvtHandler
3705 member function taking the custom event argument when
3706 wxEVENTS_COMPATIBILITY_2_8 is 0.
3707
3708 See wx__DECLARE_EVT0 for an example of use.
3709
3710 @see @ref overview_events_custom_ownclass
3711 */
3712 #define wxEVENT_HANDLER_CAST(functype, func) (&func)
3713
3714 /**
3715 This macro is used to define event table macros for handling custom
3716 events.
3717
3718 Example of use:
3719 @code
3720 class MyEvent : public wxEvent { ... };
3721
3722 // note that this is not necessary unless using old compilers: for the
3723 // reasonably new ones just use &func instead of MyEventHandler(func)
3724 typedef void (wxEvtHandler::*MyEventFunction)(MyEvent&);
3725 #define MyEventHandler(func) wxEVENT_HANDLER_CAST(MyEventFunction, func)
3726
3727 wxDEFINE_EVENT(MY_EVENT_TYPE, MyEvent);
3728
3729 #define EVT_MY(id, func) \
3730 wx__DECLARE_EVT1(MY_EVENT_TYPE, id, MyEventHandler(func))
3731
3732 ...
3733
3734 BEGIN_EVENT_TABLE(MyFrame, wxFrame)
3735 EVT_MY(wxID_ANY, MyFrame::OnMyEvent)
3736 END_EVENT_TABLE()
3737 @endcode
3738
3739 @param evt
3740 The event type to handle.
3741 @param id
3742 The identifier of events to handle.
3743 @param fn
3744 The event handler method.
3745 */
3746 #define wx__DECLARE_EVT1(evt, id, fn) \
3747 wx__DECLARE_EVT2(evt, id, wxID_ANY, fn)
3748
3749 /**
3750 Generalized version of the wx__DECLARE_EVT1() macro taking a range of
3751 IDs instead of a single one.
3752 Argument @a id1 is the first identifier of the range, @a id2 is the
3753 second identifier of the range.
3754 */
3755 #define wx__DECLARE_EVT2(evt, id1, id2, fn) \
3756 DECLARE_EVENT_TABLE_ENTRY(evt, id1, id2, fn, NULL),
3757
3758 /**
3759 Simplified version of the wx__DECLARE_EVT1() macro, to be used when the
3760 event type must be handled regardless of the ID associated with the
3761 specific event instances.
3762 */
3763 #define wx__DECLARE_EVT0(evt, fn) \
3764 wx__DECLARE_EVT1(evt, wxID_ANY, fn)
3765
3766
3767 /**
3768 Use this macro inside a class declaration to declare a @e static event table
3769 for that class.
3770
3771 In the implementation file you'll need to use the BEGIN_EVENT_TABLE()
3772 and the END_EVENT_TABLE() macros, plus some additional @c EVT_xxx macro
3773 to capture events.
3774
3775 @see @ref overview_events_eventtables
3776 */
3777 #define DECLARE_EVENT_TABLE()
3778
3779 /**
3780 Use this macro in a source file to start listing @e static event handlers
3781 for a specific class.
3782
3783 Use END_EVENT_TABLE() to terminate the event-declaration block.
3784
3785 @see @ref overview_events_eventtables
3786 */
3787 #define BEGIN_EVENT_TABLE(theClass, baseClass)
3788
3789 /**
3790 Use this macro in a source file to end listing @e static event handlers
3791 for a specific class.
3792
3793 Use BEGIN_EVENT_TABLE() to start the event-declaration block.
3794
3795 @see @ref overview_events_eventtables
3796 */
3797 #define END_EVENT_TABLE()
3798
3799 /**
3800 In a GUI application, this function posts @a event to the specified @e dest
3801 object using wxEvtHandler::AddPendingEvent().
3802
3803 Otherwise, it dispatches @a event immediately using
3804 wxEvtHandler::ProcessEvent(). See the respective documentation for details
3805 (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent()
3806 this function is not thread-safe for event objects having wxString fields,
3807 use wxQueueEvent() instead.
3808
3809 @header{wx/event.h}
3810 */
3811 void wxPostEvent(wxEvtHandler* dest, const wxEvent& event);
3812
3813 /**
3814 Queue an event for processing on the given object.
3815
3816 This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation
3817 for more details.
3818
3819 @header{wx/event.h}
3820
3821 @param dest
3822 The object to queue the event on, can't be @c NULL.
3823 @param event
3824 The heap-allocated and non-@c NULL event to queue, the function takes
3825 ownership of it.
3826 */
3827 void wxQueueEvent(wxEvtHandler* dest, wxEvent *event);
3828
3829 //@}
3830