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