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