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