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