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