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