]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: event.h | |
3 | // Purpose: interface of wxEvtHandler, wxEventBlocker and many | |
4 | // wxEvent-derived classes | |
5 | // Author: wxWidgets team | |
6 | // RCS-ID: $Id$ | |
7 | // Licence: wxWindows license | |
8 | ///////////////////////////////////////////////////////////////////////////// | |
9 | ||
10 | ||
11 | /** | |
12 | @class wxEvent | |
13 | ||
14 | An event is a structure holding information about an event passed to a | |
15 | callback or member function. | |
16 | ||
17 | wxEvent used to be a multipurpose event object, and is an abstract base class | |
18 | for other event classes (see below). | |
19 | ||
20 | For more information about events, see the @ref overview_eventhandling overview. | |
21 | ||
22 | @beginWxPerlOnly | |
23 | In wxPerl custom event classes should be derived from | |
24 | @c Wx::PlEvent and @c Wx::PlCommandEvent. | |
25 | @endWxPerlOnly | |
26 | ||
27 | @library{wxbase} | |
28 | @category{events} | |
29 | ||
30 | @see wxCommandEvent, wxMouseEvent | |
31 | */ | |
32 | class wxEvent : public wxObject | |
33 | { | |
34 | public: | |
35 | /** | |
36 | Constructor. | |
37 | ||
38 | Notice that events are usually created by wxWidgets itself and creating | |
39 | e.g. a wxPaintEvent in your code and sending it to e.g. a wxTextCtrl | |
40 | will not usually affect it at all as native controls have no specific | |
41 | knowledge about wxWidgets events. However you may construct objects of | |
42 | specific types and pass them to wxEvtHandler::ProcessEvent() if you | |
43 | want to create your own custom control and want to process its events | |
44 | in the same manner as the standard ones. | |
45 | ||
46 | Also please notice that the order of parameters in this constructor is | |
47 | different from almost all the derived classes which specify the event | |
48 | type as the first argument. | |
49 | ||
50 | @param id | |
51 | The identifier of the object (window, timer, ...) which generated | |
52 | this event. | |
53 | @param eventType | |
54 | The unique type of event, e.g. wxEVT_PAINT, wxEVT_SIZE or | |
55 | wxEVT_COMMAND_BUTTON_CLICKED. | |
56 | */ | |
57 | wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL); | |
58 | ||
59 | /** | |
60 | Returns a copy of the event. | |
61 | ||
62 | Any event that is posted to the wxWidgets event system for later action | |
63 | (via wxEvtHandler::AddPendingEvent, wxEvtHandler::QueueEvent or wxPostEvent()) | |
64 | must implement this method. | |
65 | ||
66 | All wxWidgets events fully implement this method, but any derived events | |
67 | implemented by the user should also implement this method just in case they | |
68 | (or some event derived from them) are ever posted. | |
69 | ||
70 | All wxWidgets events implement a copy constructor, so the easiest way of | |
71 | implementing the Clone function is to implement a copy constructor for | |
72 | a new event (call it MyEvent) and then define the Clone function like this: | |
73 | ||
74 | @code | |
75 | wxEvent *Clone() const { return new MyEvent(*this); } | |
76 | @endcode | |
77 | */ | |
78 | virtual wxEvent* Clone() const = 0; | |
79 | ||
80 | /** | |
81 | Returns the object (usually a window) associated with the event, if any. | |
82 | */ | |
83 | wxObject* GetEventObject() const; | |
84 | ||
85 | /** | |
86 | Returns the identifier of the given event type, such as @c wxEVT_COMMAND_BUTTON_CLICKED. | |
87 | */ | |
88 | wxEventType GetEventType() const; | |
89 | ||
90 | /** | |
91 | Returns the identifier associated with this event, such as a button command id. | |
92 | */ | |
93 | int GetId() const; | |
94 | ||
95 | /** | |
96 | Returns @true if the event handler should be skipped, @false otherwise. | |
97 | */ | |
98 | bool GetSkipped() const; | |
99 | ||
100 | /** | |
101 | Gets the timestamp for the event. The timestamp is the time in milliseconds | |
102 | since some fixed moment (not necessarily the standard Unix Epoch, so only | |
103 | differences between the timestamps and not their absolute values usually make sense). | |
104 | ||
105 | @warning | |
106 | wxWidgets returns a non-NULL timestamp only for mouse and key events | |
107 | (see wxMouseEvent and wxKeyEvent). | |
108 | */ | |
109 | long GetTimestamp() const; | |
110 | ||
111 | /** | |
112 | Returns @true if the event is or is derived from wxCommandEvent else it returns @false. | |
113 | ||
114 | @note exists only for optimization purposes. | |
115 | */ | |
116 | bool IsCommandEvent() const; | |
117 | ||
118 | /** | |
119 | Sets the propagation level to the given value (for example returned from an | |
120 | earlier call to wxEvent::StopPropagation). | |
121 | */ | |
122 | void ResumePropagation(int propagationLevel); | |
123 | ||
124 | /** | |
125 | Sets the originating object. | |
126 | */ | |
127 | void SetEventObject(wxObject* object); | |
128 | ||
129 | /** | |
130 | Sets the event type. | |
131 | */ | |
132 | void SetEventType(wxEventType type); | |
133 | ||
134 | /** | |
135 | Sets the identifier associated with this event, such as a button command id. | |
136 | */ | |
137 | void SetId(int id); | |
138 | ||
139 | /** | |
140 | Sets the timestamp for the event. | |
141 | */ | |
142 | void SetTimestamp(long timeStamp = 0); | |
143 | ||
144 | /** | |
145 | Test if this event should be propagated or not, i.e. if the propagation level | |
146 | is currently greater than 0. | |
147 | */ | |
148 | bool ShouldPropagate() const; | |
149 | ||
150 | /** | |
151 | This method can be used inside an event handler to control whether further | |
152 | event handlers bound to this event will be called after the current one returns. | |
153 | ||
154 | Without Skip() (or equivalently if Skip(@false) is used), the event will not | |
155 | be processed any more. If Skip(@true) is called, the event processing system | |
156 | continues searching for a further handler function for this event, even though | |
157 | it has been processed already in the current handler. | |
158 | ||
159 | In general, it is recommended to skip all non-command events to allow the | |
160 | default handling to take place. The command events are, however, normally not | |
161 | skipped as usually a single command such as a button click or menu item | |
162 | selection must only be processed by one handler. | |
163 | */ | |
164 | void Skip(bool skip = true); | |
165 | ||
166 | /** | |
167 | Stop the event from propagating to its parent window. | |
168 | ||
169 | Returns the old propagation level value which may be later passed to | |
170 | ResumePropagation() to allow propagating the event again. | |
171 | */ | |
172 | int StopPropagation(); | |
173 | ||
174 | protected: | |
175 | /** | |
176 | Indicates how many levels the event can propagate. | |
177 | ||
178 | This member is protected and should typically only be set in the constructors | |
179 | of the derived classes. It may be temporarily changed by StopPropagation() | |
180 | and ResumePropagation() and tested with ShouldPropagate(). | |
181 | ||
182 | The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by default) | |
183 | meaning that the event shouldn't be propagated at all or to | |
184 | @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be | |
185 | propagated as much as necessary. | |
186 | ||
187 | Any positive number means that the event should be propagated but no more than | |
188 | the given number of times. E.g. the propagation level may be set to 1 to | |
189 | propagate the event to its parent only, but not to its grandparent. | |
190 | */ | |
191 | int m_propagationLevel; | |
192 | }; | |
193 | ||
194 | /** | |
195 | @class wxEventBlocker | |
196 | ||
197 | This class is a special event handler which allows to discard | |
198 | any event (or a set of event types) directed to a specific window. | |
199 | ||
200 | Example: | |
201 | ||
202 | @code | |
203 | void MyWindow::DoSomething() | |
204 | { | |
205 | { | |
206 | // block all events directed to this window while | |
207 | // we do the 1000 FunctionWhichSendsEvents() calls | |
208 | wxEventBlocker blocker(this); | |
209 | ||
210 | for ( int i = 0; i 1000; i++ ) | |
211 | FunctionWhichSendsEvents(i); | |
212 | ||
213 | } // ~wxEventBlocker called, old event handler is restored | |
214 | ||
215 | // the event generated by this call will be processed: | |
216 | FunctionWhichSendsEvents(0) | |
217 | } | |
218 | @endcode | |
219 | ||
220 | @library{wxcore} | |
221 | @category{events} | |
222 | ||
223 | @see @ref overview_eventhandling, wxEvtHandler | |
224 | */ | |
225 | class wxEventBlocker : public wxEvtHandler | |
226 | { | |
227 | public: | |
228 | /** | |
229 | Constructs the blocker for the given window and for the given event type. | |
230 | ||
231 | If @a type is @c wxEVT_ANY, then all events for that window are blocked. | |
232 | You can call Block() after creation to add other event types to the list | |
233 | of events to block. | |
234 | ||
235 | Note that the @a win window @b must remain alive until the | |
236 | wxEventBlocker object destruction. | |
237 | */ | |
238 | wxEventBlocker(wxWindow* win, wxEventType type = -1); | |
239 | ||
240 | /** | |
241 | Destructor. The blocker will remove itself from the chain of event handlers for | |
242 | the window provided in the constructor, thus restoring normal processing of events. | |
243 | */ | |
244 | virtual ~wxEventBlocker(); | |
245 | ||
246 | /** | |
247 | Adds to the list of event types which should be blocked the given @a eventType. | |
248 | */ | |
249 | void Block(wxEventType eventType); | |
250 | }; | |
251 | ||
252 | ||
253 | ||
254 | /** | |
255 | @class wxEvtHandler | |
256 | ||
257 | A class that can handle events from the windowing system. | |
258 | wxWindow is (and therefore all window classes are) derived from this class. | |
259 | ||
260 | When events are received, wxEvtHandler invokes the method listed in the | |
261 | event table using itself as the object. When using multiple inheritance | |
262 | <b>it is imperative that the wxEvtHandler(-derived) class is the first | |
263 | class inherited</b> such that the @c this pointer for the overall object | |
264 | will be identical to the @c this pointer of the wxEvtHandler portion. | |
265 | ||
266 | @library{wxbase} | |
267 | @category{events} | |
268 | ||
269 | @see @ref overview_eventhandling | |
270 | */ | |
271 | class wxEvtHandler : public wxObject | |
272 | { | |
273 | public: | |
274 | /** | |
275 | Constructor. | |
276 | */ | |
277 | wxEvtHandler(); | |
278 | ||
279 | /** | |
280 | Destructor. | |
281 | ||
282 | If the handler is part of a chain, the destructor will unlink itself and | |
283 | restore the previous and next handlers so that they point to each other. | |
284 | */ | |
285 | virtual ~wxEvtHandler(); | |
286 | ||
287 | /** | |
288 | Queue event for a later processing. | |
289 | ||
290 | This method is similar to ProcessEvent() but while the latter is | |
291 | synchronous, i.e. the event is processed immediately, before the | |
292 | function returns, this one is asynchronous and returns immediately | |
293 | while the event will be processed at some later time (usually during | |
294 | the next event loop iteration). | |
295 | ||
296 | Another important difference is that this method takes ownership of the | |
297 | @a event parameter, i.e. it will delete it itself. This implies that | |
298 | the event should be allocated on the heap and that the pointer can't be | |
299 | used any more after the function returns (as it can be deleted at any | |
300 | moment). | |
301 | ||
302 | QueueEvent() can be used for inter-thread communication from the worker | |
303 | threads to the main thread, it is safe in the sense that it uses | |
304 | locking internally and avoids the problem mentioned in AddPendingEvent() | |
305 | documentation by ensuring that the @a event object is not used by the | |
306 | calling thread any more. Care should still be taken to avoid that some | |
307 | fields of this object are used by it, notably any wxString members of | |
308 | the event object must not be shallow copies of another wxString object | |
309 | as this would result in them still using the same string buffer behind | |
310 | the scenes. For example | |
311 | @code | |
312 | void FunctionInAWorkerThread(const wxString& str) | |
313 | { | |
314 | wxCommandEvent* evt = new wxCommandEvent; | |
315 | ||
316 | // NOT evt->SetString(str) as this would be a shallow copy | |
317 | evt->SetString(str.c_str()); // make a deep copy | |
318 | ||
319 | wxTheApp->QueueEvent( evt ); | |
320 | } | |
321 | @endcode | |
322 | ||
323 | Finally notice that this method automatically wakes up the event loop | |
324 | if it is currently idle by calling ::wxWakeUpIdle() so there is no need | |
325 | to do it manually when using it. | |
326 | ||
327 | @since 2.9.0 | |
328 | ||
329 | @param event | |
330 | A heap-allocated event to be queued, QueueEvent() takes ownership | |
331 | of it. This parameter shouldn't be @c NULL. | |
332 | */ | |
333 | virtual void QueueEvent(wxEvent *event); | |
334 | ||
335 | /** | |
336 | Post an event to be processed later. | |
337 | ||
338 | This function is similar to QueueEvent() but can't be used to post | |
339 | events from worker threads for the event objects with wxString fields | |
340 | (i.e. in practice most of them) because of an unsafe use of the same | |
341 | wxString object which happens because the wxString field in the | |
342 | original @a event object and its copy made internally by this function | |
343 | share the same string buffer internally. Use QueueEvent() to avoid | |
344 | this. | |
345 | ||
346 | A copy of @a event is made by the function, so the original can be deleted | |
347 | as soon as function returns (it is common that the original is created | |
348 | on the stack). This requires that the wxEvent::Clone() method be | |
349 | implemented by event so that it can be duplicated and stored until it | |
350 | gets processed. | |
351 | ||
352 | @param event | |
353 | Event to add to the pending events queue. | |
354 | */ | |
355 | virtual void AddPendingEvent(const wxEvent& event); | |
356 | ||
357 | /** | |
358 | Connects the given function dynamically with the event handler, id and event type. | |
359 | This is an alternative to the use of static event tables. | |
360 | ||
361 | See the @ref page_samples_event sample for usage. | |
362 | ||
363 | This specific overload allows you to connect an event handler to a @e range | |
364 | of @e source IDs. | |
365 | Do not confuse @e source IDs with event @e types: source IDs identify the | |
366 | event generator objects (typically wxMenuItem or wxWindow objects) while the | |
367 | event @e type identify which type of events should be handled by the | |
368 | given @e function (an event generator object may generate many different | |
369 | types of events!). | |
370 | ||
371 | @param id | |
372 | The first ID of the identifier range to be associated with the event | |
373 | handler function. | |
374 | @param lastId | |
375 | The last ID of the identifier range to be associated with the event | |
376 | handler function. | |
377 | @param eventType | |
378 | The event type to be associated with this event handler. | |
379 | @param function | |
380 | The event handler function. Note that this function should | |
381 | be explicitly converted to the correct type which can be done using a macro | |
382 | called @c wxFooEventHandler for the handler for any @c wxFooEvent. | |
383 | @param userData | |
384 | Data to be associated with the event table entry. | |
385 | @param eventSink | |
386 | Object whose member function should be called. | |
387 | If this is @NULL, @c *this will be used. | |
388 | */ | |
389 | void Connect(int id, int lastId, wxEventType eventType, | |
390 | wxObjectEventFunction function, | |
391 | wxObject* userData = NULL, | |
392 | wxEvtHandler* eventSink = NULL); | |
393 | ||
394 | /** | |
395 | See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) | |
396 | overload for more info. | |
397 | ||
398 | This overload can be used to attach an event handler to a single source ID: | |
399 | ||
400 | Example: | |
401 | @code | |
402 | frame->Connect( wxID_EXIT, | |
403 | wxEVT_COMMAND_MENU_SELECTED, | |
404 | wxCommandEventHandler(MyFrame::OnQuit) ); | |
405 | @endcode | |
406 | */ | |
407 | void Connect(int id, wxEventType eventType, | |
408 | wxObjectEventFunction function, | |
409 | wxObject* userData = NULL, | |
410 | wxEvtHandler* eventSink = NULL); | |
411 | ||
412 | /** | |
413 | See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) | |
414 | overload for more info. | |
415 | ||
416 | This overload will connect the given event handler so that regardless of the | |
417 | ID of the event source, the handler will be called. | |
418 | */ | |
419 | void Connect(wxEventType eventType, | |
420 | wxObjectEventFunction function, | |
421 | wxObject* userData = NULL, | |
422 | wxEvtHandler* eventSink = NULL); | |
423 | ||
424 | /** | |
425 | Disconnects the given function dynamically from the event handler, using the | |
426 | specified parameters as search criteria and returning @true if a matching | |
427 | function has been found and removed. | |
428 | ||
429 | This method can only disconnect functions which have been added using the | |
430 | Connect() method. There is no way to disconnect functions connected using | |
431 | the (static) event tables. | |
432 | ||
433 | @param eventType | |
434 | The event type associated with this event handler. | |
435 | @param function | |
436 | The event handler function. | |
437 | @param userData | |
438 | Data associated with the event table entry. | |
439 | @param eventSink | |
440 | Object whose member function should be called. | |
441 | */ | |
442 | bool Disconnect(wxEventType eventType, | |
443 | wxObjectEventFunction function, | |
444 | wxObject* userData = NULL, | |
445 | wxEvtHandler* eventSink = NULL); | |
446 | ||
447 | /** | |
448 | See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) | |
449 | overload for more info. | |
450 | ||
451 | This overload takes the additional @a id parameter. | |
452 | */ | |
453 | bool Disconnect(int id = wxID_ANY, | |
454 | wxEventType eventType = wxEVT_NULL, | |
455 | wxObjectEventFunction function = NULL, | |
456 | wxObject* userData = NULL, | |
457 | wxEvtHandler* eventSink = NULL); | |
458 | ||
459 | /** | |
460 | See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) | |
461 | overload for more info. | |
462 | ||
463 | This overload takes an additional range of source IDs. | |
464 | */ | |
465 | bool Disconnect(int id, int lastId, | |
466 | wxEventType eventType, | |
467 | wxObjectEventFunction function = NULL, | |
468 | wxObject* userData = NULL, | |
469 | wxEvtHandler* eventSink = NULL); | |
470 | ||
471 | /** | |
472 | Returns user-supplied client data. | |
473 | ||
474 | @remarks Normally, any extra data the programmer wishes to associate with | |
475 | the object should be made available by deriving a new class with | |
476 | new data members. | |
477 | ||
478 | @see SetClientData() | |
479 | */ | |
480 | void* GetClientData() const; | |
481 | ||
482 | /** | |
483 | Returns a pointer to the user-supplied client data object. | |
484 | ||
485 | @see SetClientObject(), wxClientData | |
486 | */ | |
487 | wxClientData* GetClientObject() const; | |
488 | ||
489 | /** | |
490 | Returns @true if the event handler is enabled, @false otherwise. | |
491 | ||
492 | @see SetEvtHandlerEnabled() | |
493 | */ | |
494 | bool GetEvtHandlerEnabled() const; | |
495 | ||
496 | /** | |
497 | Returns the pointer to the next handler in the chain. | |
498 | ||
499 | @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(), | |
500 | wxWindow::PushEventHandler, wxWindow::PopEventHandler | |
501 | */ | |
502 | wxEvtHandler* GetNextHandler() const; | |
503 | ||
504 | /** | |
505 | Returns the pointer to the previous handler in the chain. | |
506 | ||
507 | @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(), | |
508 | wxWindow::PushEventHandler, wxWindow::PopEventHandler | |
509 | */ | |
510 | wxEvtHandler* GetPreviousHandler() const; | |
511 | ||
512 | /** | |
513 | Processes an event, searching event tables and calling zero or more suitable | |
514 | event handler function(s). | |
515 | ||
516 | Normally, your application would not call this function: it is called in the | |
517 | wxWidgets implementation to dispatch incoming user interface events to the | |
518 | framework (and application). | |
519 | ||
520 | However, you might need to call it if implementing new functionality | |
521 | (such as a new control) where you define new event types, as opposed to | |
522 | allowing the user to override virtual functions. | |
523 | ||
524 | An instance where you might actually override the ProcessEvent() function is where | |
525 | you want to direct event processing to event handlers not normally noticed by | |
526 | wxWidgets. For example, in the document/view architecture, documents and views | |
527 | are potential event handlers. When an event reaches a frame, ProcessEvent() will | |
528 | need to be called on the associated document and view in case event handler functions | |
529 | are associated with these objects. The property classes library (wxProperty) also | |
530 | overrides ProcessEvent() for similar reasons. | |
531 | ||
532 | The normal order of event table searching is as follows: | |
533 | -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled) | |
534 | the function skips to step (6). | |
535 | -# If the object is a wxWindow, ProcessEvent() is recursively called on the | |
536 | window's wxValidator. If this returns @true, the function exits. | |
537 | -# SearchEventTable() is called for this event handler. If this fails, the base | |
538 | class table is tried, and so on until no more tables exist or an appropriate | |
539 | function was found, in which case the function exits. | |
540 | -# The search is applied down the entire chain of event handlers (usually the | |
541 | chain has a length of one). If this succeeds, the function exits. | |
542 | -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent() | |
543 | is recursively applied to the parent window's event handler. | |
544 | If this returns true, the function exits. | |
545 | -# Finally, ProcessEvent() is called on the wxApp object. | |
546 | ||
547 | @param event | |
548 | Event to process. | |
549 | ||
550 | @return @true if a suitable event handler function was found and | |
551 | executed, and the function did not call wxEvent::Skip. | |
552 | ||
553 | @see SearchEventTable() | |
554 | */ | |
555 | virtual bool ProcessEvent(wxEvent& event); | |
556 | ||
557 | /** | |
558 | Processes an event by calling ProcessEvent() and handles any exceptions | |
559 | that occur in the process. | |
560 | If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called. | |
561 | ||
562 | @param event | |
563 | Event to process. | |
564 | ||
565 | @return @true if the event was processed, @false if no handler was found | |
566 | or an exception was thrown. | |
567 | ||
568 | @see wxWindow::HandleWindowEvent | |
569 | */ | |
570 | bool SafelyProcessEvent(wxEvent& event); | |
571 | ||
572 | /** | |
573 | Searches the event table, executing an event handler function if an appropriate | |
574 | one is found. | |
575 | ||
576 | @param table | |
577 | Event table to be searched. | |
578 | @param event | |
579 | Event to be matched against an event table entry. | |
580 | ||
581 | @return @true if a suitable event handler function was found and | |
582 | executed, and the function did not call wxEvent::Skip. | |
583 | ||
584 | @remarks This function looks through the object's event table and tries | |
585 | to find an entry that will match the event. | |
586 | An entry will match if: | |
587 | @li The event type matches, and | |
588 | @li the identifier or identifier range matches, or the event table | |
589 | entry's identifier is zero. | |
590 | ||
591 | If a suitable function is called but calls wxEvent::Skip, this | |
592 | function will fail, and searching will continue. | |
593 | ||
594 | @see ProcessEvent() | |
595 | */ | |
596 | virtual bool SearchEventTable(wxEventTable& table, | |
597 | wxEvent& event); | |
598 | ||
599 | /** | |
600 | Sets user-supplied client data. | |
601 | ||
602 | @param data | |
603 | Data to be associated with the event handler. | |
604 | ||
605 | @remarks Normally, any extra data the programmer wishes to associate | |
606 | with the object should be made available by deriving a new | |
607 | class with new data members. You must not call this method | |
608 | and SetClientObject on the same class - only one of them. | |
609 | ||
610 | @see GetClientData() | |
611 | */ | |
612 | void SetClientData(void* data); | |
613 | ||
614 | /** | |
615 | Set the client data object. Any previous object will be deleted. | |
616 | ||
617 | @see GetClientObject(), wxClientData | |
618 | */ | |
619 | void SetClientObject(wxClientData* data); | |
620 | ||
621 | /** | |
622 | Enables or disables the event handler. | |
623 | ||
624 | @param enabled | |
625 | @true if the event handler is to be enabled, @false if it is to be disabled. | |
626 | ||
627 | @remarks You can use this function to avoid having to remove the event | |
628 | handler from the chain, for example when implementing a | |
629 | dialog editor and changing from edit to test mode. | |
630 | ||
631 | @see GetEvtHandlerEnabled() | |
632 | */ | |
633 | void SetEvtHandlerEnabled(bool enabled); | |
634 | ||
635 | /** | |
636 | Sets the pointer to the next handler. | |
637 | ||
638 | @param handler | |
639 | Event handler to be set as the next handler. | |
640 | ||
641 | @see GetNextHandler(), SetPreviousHandler(), GetPreviousHandler(), | |
642 | wxWindow::PushEventHandler, wxWindow::PopEventHandler | |
643 | */ | |
644 | void SetNextHandler(wxEvtHandler* handler); | |
645 | ||
646 | /** | |
647 | Sets the pointer to the previous handler. | |
648 | ||
649 | @param handler | |
650 | Event handler to be set as the previous handler. | |
651 | */ | |
652 | void SetPreviousHandler(wxEvtHandler* handler); | |
653 | }; | |
654 | ||
655 | ||
656 | /** | |
657 | @class wxKeyEvent | |
658 | ||
659 | This event class contains information about keypress (character) events. | |
660 | ||
661 | Notice that there are three different kinds of keyboard events in wxWidgets: | |
662 | key down and up events and char events. The difference between the first two | |
663 | is clear - the first corresponds to a key press and the second to a key | |
664 | release - otherwise they are identical. Just note that if the key is | |
665 | maintained in a pressed state you will typically get a lot of (automatically | |
666 | generated) down events but only one up so it is wrong to assume that there is | |
667 | one up event corresponding to each down one. | |
668 | ||
669 | Both key events provide untranslated key codes while the char event carries | |
670 | the translated one. The untranslated code for alphanumeric keys is always | |
671 | an upper case value. For the other keys it is one of @c WXK_XXX values | |
672 | from the @ref page_keycodes. | |
673 | The translated key is, in general, the character the user expects to appear | |
674 | as the result of the key combination when typing the text into a text entry | |
675 | zone, for example. | |
676 | ||
677 | A few examples to clarify this (all assume that CAPS LOCK is unpressed | |
678 | and the standard US keyboard): when the @c 'A' key is pressed, the key down | |
679 | event key code is equal to @c ASCII A == 65. But the char event key code | |
680 | is @c ASCII a == 97. On the other hand, if you press both SHIFT and | |
681 | @c 'A' keys simultaneously , the key code in key down event will still be | |
682 | just @c 'A' while the char event key code parameter will now be @c 'A' | |
683 | as well. | |
684 | ||
685 | Although in this simple case it is clear that the correct key code could be | |
686 | found in the key down event handler by checking the value returned by | |
687 | wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as | |
688 | for non-alphanumeric keys the translation is keyboard-layout dependent and | |
689 | can only be done properly by the system itself. | |
690 | ||
691 | Another kind of translation is done when the control key is pressed: for | |
692 | example, for CTRL-A key press the key down event still carries the | |
693 | same key code @c 'a' as usual but the char event will have key code of 1, | |
694 | the ASCII value of this key combination. | |
695 | ||
696 | You may discover how the other keys on your system behave interactively by | |
697 | running the @ref page_samples_text wxWidgets sample and pressing some keys | |
698 | in any of the text controls shown in it. | |
699 | ||
700 | @b Tip: be sure to call @c event.Skip() for events that you don't process in | |
701 | key event function, otherwise menu shortcuts may cease to work under Windows. | |
702 | ||
703 | @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler | |
704 | does not call @c event.Skip() then the corresponding char event | |
705 | (@c EVT_CHAR) will not happen. | |
706 | This is by design and enables the programs that handle both types of | |
707 | events to be a bit simpler. | |
708 | ||
709 | @note For Windows programmers: The key and char events in wxWidgets are | |
710 | similar to but slightly different from Windows @c WM_KEYDOWN and | |
711 | @c WM_CHAR events. In particular, Alt-x combination will generate a | |
712 | char event in wxWidgets (unless it is used as an accelerator). | |
713 | ||
714 | ||
715 | @beginEventTable{wxKeyEvent} | |
716 | @event{EVT_KEY_DOWN(func)} | |
717 | Process a wxEVT_KEY_DOWN event (any key has been pressed). | |
718 | @event{EVT_KEY_UP(func)} | |
719 | Process a wxEVT_KEY_UP event (any key has been released). | |
720 | @event{EVT_CHAR(func)} | |
721 | Process a wxEVT_CHAR event. | |
722 | @endEventTable | |
723 | ||
724 | @see wxKeyboardState | |
725 | ||
726 | @library{wxcore} | |
727 | @category{events} | |
728 | */ | |
729 | class wxKeyEvent : public wxEvent, | |
730 | public wxKeyboardState | |
731 | { | |
732 | public: | |
733 | /** | |
734 | Constructor. | |
735 | Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK. | |
736 | */ | |
737 | wxKeyEvent(wxEventType keyEventType = wxEVT_NULL); | |
738 | ||
739 | /** | |
740 | Returns the virtual key code. ASCII events return normal ASCII values, | |
741 | while non-ASCII events return values such as @b WXK_LEFT for the left cursor | |
742 | key. See @ref page_keycodes for a full list of the virtual key codes. | |
743 | ||
744 | Note that in Unicode build, the returned value is meaningful only if the | |
745 | user entered a character that can be represented in current locale's default | |
746 | charset. You can obtain the corresponding Unicode character using GetUnicodeKey(). | |
747 | */ | |
748 | int GetKeyCode() const; | |
749 | ||
750 | //@{ | |
751 | /** | |
752 | Obtains the position (in client coordinates) at which the key was pressed. | |
753 | */ | |
754 | wxPoint GetPosition() const; | |
755 | void GetPosition(long* x, long* y) const; | |
756 | //@} | |
757 | ||
758 | /** | |
759 | Returns the raw key code for this event. This is a platform-dependent scan code | |
760 | which should only be used in advanced applications. | |
761 | ||
762 | @note Currently the raw key codes are not supported by all ports, use | |
763 | @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. | |
764 | */ | |
765 | wxUint32 GetRawKeyCode() const; | |
766 | ||
767 | /** | |
768 | Returns the low level key flags for this event. The flags are | |
769 | platform-dependent and should only be used in advanced applications. | |
770 | ||
771 | @note Currently the raw key flags are not supported by all ports, use | |
772 | @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. | |
773 | */ | |
774 | wxUint32 GetRawKeyFlags() const; | |
775 | ||
776 | /** | |
777 | Returns the Unicode character corresponding to this key event. | |
778 | ||
779 | This function is only available in Unicode build, i.e. when | |
780 | @c wxUSE_UNICODE is 1. | |
781 | */ | |
782 | wxChar GetUnicodeKey() const; | |
783 | ||
784 | /** | |
785 | Returns the X position (in client coordinates) of the event. | |
786 | */ | |
787 | wxCoord GetX() const; | |
788 | ||
789 | /** | |
790 | Returns the Y position (in client coordinates) of the event. | |
791 | */ | |
792 | wxCoord GetY() const; | |
793 | }; | |
794 | ||
795 | ||
796 | ||
797 | /** | |
798 | @class wxJoystickEvent | |
799 | ||
800 | This event class contains information about joystick events, particularly | |
801 | events received by windows. | |
802 | ||
803 | @beginEventTable{wxJoystickEvent} | |
804 | @style{EVT_JOY_BUTTON_DOWN(func)} | |
805 | Process a wxEVT_JOY_BUTTON_DOWN event. | |
806 | @style{EVT_JOY_BUTTON_UP(func)} | |
807 | Process a wxEVT_JOY_BUTTON_UP event. | |
808 | @style{EVT_JOY_MOVE(func)} | |
809 | Process a wxEVT_JOY_MOVE event. | |
810 | @style{EVT_JOY_ZMOVE(func)} | |
811 | Process a wxEVT_JOY_ZMOVE event. | |
812 | @style{EVT_JOYSTICK_EVENTS(func)} | |
813 | Processes all joystick events. | |
814 | @endEventTable | |
815 | ||
816 | @library{wxcore} | |
817 | @category{events} | |
818 | ||
819 | @see wxJoystick | |
820 | */ | |
821 | class wxJoystickEvent : public wxEvent | |
822 | { | |
823 | public: | |
824 | /** | |
825 | Constructor. | |
826 | */ | |
827 | wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0, | |
828 | int joystick = wxJOYSTICK1, | |
829 | int change = 0); | |
830 | ||
831 | /** | |
832 | Returns @true if the event was a down event from the specified button | |
833 | (or any button). | |
834 | ||
835 | @param button | |
836 | Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to | |
837 | indicate any button down event. | |
838 | */ | |
839 | bool ButtonDown(int button = wxJOY_BUTTON_ANY) const; | |
840 | ||
841 | /** | |
842 | Returns @true if the specified button (or any button) was in a down state. | |
843 | ||
844 | @param button | |
845 | Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to | |
846 | indicate any button down event. | |
847 | */ | |
848 | bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const; | |
849 | ||
850 | /** | |
851 | Returns @true if the event was an up event from the specified button | |
852 | (or any button). | |
853 | ||
854 | @param button | |
855 | Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to | |
856 | indicate any button down event. | |
857 | */ | |
858 | bool ButtonUp(int button = wxJOY_BUTTON_ANY) const; | |
859 | ||
860 | /** | |
861 | Returns the identifier of the button changing state. | |
862 | ||
863 | This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. | |
864 | */ | |
865 | int GetButtonChange() const; | |
866 | ||
867 | /** | |
868 | Returns the down state of the buttons. | |
869 | ||
870 | This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. | |
871 | */ | |
872 | int GetButtonState() const; | |
873 | ||
874 | /** | |
875 | Returns the identifier of the joystick generating the event - one of | |
876 | wxJOYSTICK1 and wxJOYSTICK2. | |
877 | */ | |
878 | int GetJoystick() const; | |
879 | ||
880 | /** | |
881 | Returns the x, y position of the joystick event. | |
882 | */ | |
883 | wxPoint GetPosition() const; | |
884 | ||
885 | /** | |
886 | Returns the z position of the joystick event. | |
887 | */ | |
888 | int GetZPosition() const; | |
889 | ||
890 | /** | |
891 | Returns @true if this was a button up or down event | |
892 | (@e not 'is any button down?'). | |
893 | */ | |
894 | bool IsButton() const; | |
895 | ||
896 | /** | |
897 | Returns @true if this was an x, y move event. | |
898 | */ | |
899 | bool IsMove() const; | |
900 | ||
901 | /** | |
902 | Returns @true if this was a z move event. | |
903 | */ | |
904 | bool IsZMove() const; | |
905 | }; | |
906 | ||
907 | ||
908 | ||
909 | /** | |
910 | @class wxScrollWinEvent | |
911 | ||
912 | A scroll event holds information about events sent from scrolling windows. | |
913 | ||
914 | ||
915 | @beginEventTable{wxScrollWinEvent} | |
916 | You can use the EVT_SCROLLWIN* macros for intercepting scroll window events | |
917 | from the receiving window. | |
918 | @event{EVT_SCROLLWIN(func)} | |
919 | Process all scroll events. | |
920 | @event{EVT_SCROLLWIN_TOP(func)} | |
921 | Process wxEVT_SCROLLWIN_TOP scroll-to-top events. | |
922 | @event{EVT_SCROLLWIN_BOTTOM(func)} | |
923 | Process wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events. | |
924 | @event{EVT_SCROLLWIN_LINEUP(func)} | |
925 | Process wxEVT_SCROLLWIN_LINEUP line up events. | |
926 | @event{EVT_SCROLLWIN_LINEDOWN(func)} | |
927 | Process wxEVT_SCROLLWIN_LINEDOWN line down events. | |
928 | @event{EVT_SCROLLWIN_PAGEUP(func)} | |
929 | Process wxEVT_SCROLLWIN_PAGEUP page up events. | |
930 | @event{EVT_SCROLLWIN_PAGEDOWN(func)} | |
931 | Process wxEVT_SCROLLWIN_PAGEDOWN page down events. | |
932 | @event{EVT_SCROLLWIN_THUMBTRACK(func)} | |
933 | Process wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events | |
934 | (frequent events sent as the user drags the thumbtrack). | |
935 | @event{EVT_SCROLLWIN_THUMBRELEASE(func)} | |
936 | Process wxEVT_SCROLLWIN_THUMBRELEASE thumb release events. | |
937 | @endEventTable | |
938 | ||
939 | ||
940 | @library{wxcore} | |
941 | @category{events} | |
942 | ||
943 | @see wxScrollEvent, @ref overview_eventhandling | |
944 | */ | |
945 | class wxScrollWinEvent : public wxEvent | |
946 | { | |
947 | public: | |
948 | /** | |
949 | Constructor. | |
950 | */ | |
951 | wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0, | |
952 | int orientation = 0); | |
953 | ||
954 | /** | |
955 | Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the | |
956 | scrollbar. | |
957 | ||
958 | @todo wxHORIZONTAL and wxVERTICAL should go in their own enum | |
959 | */ | |
960 | int GetOrientation() const; | |
961 | ||
962 | /** | |
963 | Returns the position of the scrollbar for the thumb track and release events. | |
964 | ||
965 | Note that this field can't be used for the other events, you need to query | |
966 | the window itself for the current position in that case. | |
967 | */ | |
968 | int GetPosition() const; | |
969 | }; | |
970 | ||
971 | ||
972 | ||
973 | /** | |
974 | @class wxSysColourChangedEvent | |
975 | ||
976 | This class is used for system colour change events, which are generated | |
977 | when the user changes the colour settings using the control panel. | |
978 | This is only appropriate under Windows. | |
979 | ||
980 | @remarks | |
981 | The default event handler for this event propagates the event to child windows, | |
982 | since Windows only sends the events to top-level windows. | |
983 | If intercepting this event for a top-level window, remember to call the base | |
984 | class handler, or to pass the event on to the window's children explicitly. | |
985 | ||
986 | @beginEventTable{wxSysColourChangedEvent} | |
987 | @event{EVT_SYS_COLOUR_CHANGED(func)} | |
988 | Process a wxEVT_SYS_COLOUR_CHANGED event. | |
989 | @endEventTable | |
990 | ||
991 | @library{wxcore} | |
992 | @category{events} | |
993 | ||
994 | @see @ref overview_eventhandling | |
995 | */ | |
996 | class wxSysColourChangedEvent : public wxEvent | |
997 | { | |
998 | public: | |
999 | /** | |
1000 | Constructor. | |
1001 | */ | |
1002 | wxSysColourChangedEvent(); | |
1003 | }; | |
1004 | ||
1005 | ||
1006 | ||
1007 | /** | |
1008 | @class wxWindowCreateEvent | |
1009 | ||
1010 | This event is sent just after the actual window associated with a wxWindow | |
1011 | object has been created. | |
1012 | ||
1013 | Since it is derived from wxCommandEvent, the event propagates up | |
1014 | the window hierarchy. | |
1015 | ||
1016 | @beginEventTable{wxWindowCreateEvent} | |
1017 | @event{EVT_WINDOW_CREATE(func)} | |
1018 | Process a wxEVT_CREATE event. | |
1019 | @endEventTable | |
1020 | ||
1021 | @library{wxcore} | |
1022 | @category{events} | |
1023 | ||
1024 | @see @ref overview_eventhandling, wxWindowDestroyEvent | |
1025 | */ | |
1026 | class wxWindowCreateEvent : public wxCommandEvent | |
1027 | { | |
1028 | public: | |
1029 | /** | |
1030 | Constructor. | |
1031 | */ | |
1032 | wxWindowCreateEvent(wxWindow* win = NULL); | |
1033 | }; | |
1034 | ||
1035 | ||
1036 | ||
1037 | /** | |
1038 | @class wxPaintEvent | |
1039 | ||
1040 | A paint event is sent when a window's contents needs to be repainted. | |
1041 | ||
1042 | Please notice that in general it is impossible to change the drawing of a | |
1043 | standard control (such as wxButton) and so you shouldn't attempt to handle | |
1044 | paint events for them as even if it might work on some platforms, this is | |
1045 | inherently not portable and won't work everywhere. | |
1046 | ||
1047 | @remarks | |
1048 | Note that in a paint event handler, the application must always create a | |
1049 | wxPaintDC object, even if you do not use it. Otherwise, under MS Windows, | |
1050 | refreshing for this and other windows will go wrong. | |
1051 | For example: | |
1052 | @code | |
1053 | void MyWindow::OnPaint(wxPaintEvent& event) | |
1054 | { | |
1055 | wxPaintDC dc(this); | |
1056 | ||
1057 | DrawMyDocument(dc); | |
1058 | } | |
1059 | @endcode | |
1060 | You can optimize painting by retrieving the rectangles that have been damaged | |
1061 | and only repainting these. The rectangles are in terms of the client area, | |
1062 | and are unscrolled, so you will need to do some calculations using the current | |
1063 | view position to obtain logical, scrolled units. | |
1064 | Here is an example of using the wxRegionIterator class: | |
1065 | @code | |
1066 | // Called when window needs to be repainted. | |
1067 | void MyWindow::OnPaint(wxPaintEvent& event) | |
1068 | { | |
1069 | wxPaintDC dc(this); | |
1070 | ||
1071 | // Find Out where the window is scrolled to | |
1072 | int vbX,vbY; // Top left corner of client | |
1073 | GetViewStart(&vbX,&vbY); | |
1074 | ||
1075 | int vX,vY,vW,vH; // Dimensions of client area in pixels | |
1076 | wxRegionIterator upd(GetUpdateRegion()); // get the update rect list | |
1077 | ||
1078 | while (upd) | |
1079 | { | |
1080 | vX = upd.GetX(); | |
1081 | vY = upd.GetY(); | |
1082 | vW = upd.GetW(); | |
1083 | vH = upd.GetH(); | |
1084 | ||
1085 | // Alternatively we can do this: | |
1086 | // wxRect rect(upd.GetRect()); | |
1087 | ||
1088 | // Repaint this rectangle | |
1089 | ...some code... | |
1090 | ||
1091 | upd ++ ; | |
1092 | } | |
1093 | } | |
1094 | @endcode | |
1095 | ||
1096 | ||
1097 | @beginEventTable{wxPaintEvent} | |
1098 | @event{EVT_PAINT(func)} | |
1099 | Process a wxEVT_PAINT event. | |
1100 | @endEventTable | |
1101 | ||
1102 | @library{wxcore} | |
1103 | @category{events} | |
1104 | ||
1105 | @see @ref overview_eventhandling | |
1106 | */ | |
1107 | class wxPaintEvent : public wxEvent | |
1108 | { | |
1109 | public: | |
1110 | /** | |
1111 | Constructor. | |
1112 | */ | |
1113 | wxPaintEvent(int id = 0); | |
1114 | }; | |
1115 | ||
1116 | ||
1117 | ||
1118 | /** | |
1119 | @class wxMaximizeEvent | |
1120 | ||
1121 | An event being sent when a top level window is maximized. Notice that it is | |
1122 | not sent when the window is restored to its original size after it had been | |
1123 | maximized, only a normal wxSizeEvent is generated in this case. | |
1124 | ||
1125 | @beginEventTable{wxMaximizeEvent} | |
1126 | @event{EVT_MAXIMIZE(func)} | |
1127 | Process a wxEVT_MAXIMIZE event. | |
1128 | @endEventTable | |
1129 | ||
1130 | @library{wxcore} | |
1131 | @category{events} | |
1132 | ||
1133 | @see @ref overview_eventhandling, wxTopLevelWindow::Maximize, | |
1134 | wxTopLevelWindow::IsMaximized | |
1135 | */ | |
1136 | class wxMaximizeEvent : public wxEvent | |
1137 | { | |
1138 | public: | |
1139 | /** | |
1140 | Constructor. Only used by wxWidgets internally. | |
1141 | */ | |
1142 | wxMaximizeEvent(int id = 0); | |
1143 | }; | |
1144 | ||
1145 | /** | |
1146 | The possibles modes to pass to wxUpdateUIEvent::SetMode(). | |
1147 | */ | |
1148 | enum wxUpdateUIMode | |
1149 | { | |
1150 | /** Send UI update events to all windows. */ | |
1151 | wxUPDATE_UI_PROCESS_ALL, | |
1152 | ||
1153 | /** Send UI update events to windows that have | |
1154 | the wxWS_EX_PROCESS_UI_UPDATES flag specified. */ | |
1155 | wxUPDATE_UI_PROCESS_SPECIFIED | |
1156 | }; | |
1157 | ||
1158 | ||
1159 | /** | |
1160 | @class wxUpdateUIEvent | |
1161 | ||
1162 | This class is used for pseudo-events which are called by wxWidgets | |
1163 | to give an application the chance to update various user interface elements. | |
1164 | ||
1165 | Without update UI events, an application has to work hard to check/uncheck, | |
1166 | enable/disable, show/hide, and set the text for elements such as menu items | |
1167 | and toolbar buttons. The code for doing this has to be mixed up with the code | |
1168 | that is invoked when an action is invoked for a menu item or button. | |
1169 | ||
1170 | With update UI events, you define an event handler to look at the state of the | |
1171 | application and change UI elements accordingly. wxWidgets will call your member | |
1172 | functions in idle time, so you don't have to worry where to call this code. | |
1173 | ||
1174 | In addition to being a clearer and more declarative method, it also means you don't | |
1175 | have to worry whether you're updating a toolbar or menubar identifier. The same | |
1176 | handler can update a menu item and toolbar button, if the identifier is the same. | |
1177 | Instead of directly manipulating the menu or button, you call functions in the event | |
1178 | object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a | |
1179 | call has been made, and which UI element to update. | |
1180 | ||
1181 | These events will work for popup menus as well as menubars. Just before a menu is | |
1182 | popped up, wxMenu::UpdateUI is called to process any UI events for the window that | |
1183 | owns the menu. | |
1184 | ||
1185 | If you find that the overhead of UI update processing is affecting your application, | |
1186 | you can do one or both of the following: | |
1187 | @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED, | |
1188 | and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should | |
1189 | receive update events. No other windows will receive update events. | |
1190 | @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay | |
1191 | between updates. You may need to call wxWindow::UpdateWindowUI at critical points, | |
1192 | for example when a dialog is about to be shown, in case the user sees a slight | |
1193 | delay before windows are updated. | |
1194 | ||
1195 | Note that although events are sent in idle time, defining a wxIdleEvent handler | |
1196 | for a window does not affect this because the events are sent from wxWindow::OnInternalIdle | |
1197 | which is always called in idle time. | |
1198 | ||
1199 | wxWidgets tries to optimize update events on some platforms. | |
1200 | On Windows and GTK+, events for menubar items are only sent when the menu is about | |
1201 | to be shown, and not in idle time. | |
1202 | ||
1203 | ||
1204 | @beginEventTable{wxUpdateUIEvent} | |
1205 | @event{EVT_UPDATE_UI(id, func)} | |
1206 | Process a wxEVT_UPDATE_UI event for the command with the given id. | |
1207 | @event{EVT_UPDATE_UI_RANGE(id1, id2, func)} | |
1208 | Process a wxEVT_UPDATE_UI event for any command with id included in the given range. | |
1209 | @endEventTable | |
1210 | ||
1211 | @library{wxcore} | |
1212 | @category{events} | |
1213 | ||
1214 | @see @ref overview_eventhandling | |
1215 | */ | |
1216 | class wxUpdateUIEvent : public wxCommandEvent | |
1217 | { | |
1218 | public: | |
1219 | /** | |
1220 | Constructor. | |
1221 | */ | |
1222 | wxUpdateUIEvent(wxWindowID commandId = 0); | |
1223 | ||
1224 | /** | |
1225 | Returns @true if it is appropriate to update (send UI update events to) | |
1226 | this window. | |
1227 | ||
1228 | This function looks at the mode used (see wxUpdateUIEvent::SetMode), | |
1229 | the wxWS_EX_PROCESS_UI_UPDATES flag in @a window, the time update events | |
1230 | were last sent in idle time, and the update interval, to determine whether | |
1231 | events should be sent to this window now. By default this will always | |
1232 | return @true because the update mode is initially wxUPDATE_UI_PROCESS_ALL | |
1233 | and the interval is set to 0; so update events will be sent as often as | |
1234 | possible. You can reduce the frequency that events are sent by changing the | |
1235 | mode and/or setting an update interval. | |
1236 | ||
1237 | @see ResetUpdateTime(), SetUpdateInterval(), SetMode() | |
1238 | */ | |
1239 | static bool CanUpdate(wxWindow* window); | |
1240 | ||
1241 | /** | |
1242 | Check or uncheck the UI element. | |
1243 | */ | |
1244 | void Check(bool check); | |
1245 | ||
1246 | /** | |
1247 | Enable or disable the UI element. | |
1248 | */ | |
1249 | void Enable(bool enable); | |
1250 | ||
1251 | /** | |
1252 | Returns @true if the UI element should be checked. | |
1253 | */ | |
1254 | bool GetChecked() const; | |
1255 | ||
1256 | /** | |
1257 | Returns @true if the UI element should be enabled. | |
1258 | */ | |
1259 | bool GetEnabled() const; | |
1260 | ||
1261 | /** | |
1262 | Static function returning a value specifying how wxWidgets will send update | |
1263 | events: to all windows, or only to those which specify that they will process | |
1264 | the events. | |
1265 | ||
1266 | @see SetMode() | |
1267 | */ | |
1268 | static wxUpdateUIMode GetMode(); | |
1269 | ||
1270 | /** | |
1271 | Returns @true if the application has called Check(). | |
1272 | For wxWidgets internal use only. | |
1273 | */ | |
1274 | bool GetSetChecked() const; | |
1275 | ||
1276 | /** | |
1277 | Returns @true if the application has called Enable(). | |
1278 | For wxWidgets internal use only. | |
1279 | */ | |
1280 | bool GetSetEnabled() const; | |
1281 | ||
1282 | /** | |
1283 | Returns @true if the application has called Show(). | |
1284 | For wxWidgets internal use only. | |
1285 | */ | |
1286 | bool GetSetShown() const; | |
1287 | ||
1288 | /** | |
1289 | Returns @true if the application has called SetText(). | |
1290 | For wxWidgets internal use only. | |
1291 | */ | |
1292 | bool GetSetText() const; | |
1293 | ||
1294 | /** | |
1295 | Returns @true if the UI element should be shown. | |
1296 | */ | |
1297 | bool GetShown() const; | |
1298 | ||
1299 | /** | |
1300 | Returns the text that should be set for the UI element. | |
1301 | */ | |
1302 | wxString GetText() const; | |
1303 | ||
1304 | /** | |
1305 | Returns the current interval between updates in milliseconds. | |
1306 | The value -1 disables updates, 0 updates as frequently as possible. | |
1307 | ||
1308 | @see SetUpdateInterval(). | |
1309 | */ | |
1310 | static long GetUpdateInterval(); | |
1311 | ||
1312 | /** | |
1313 | Used internally to reset the last-updated time to the current time. | |
1314 | ||
1315 | It is assumed that update events are normally sent in idle time, so this | |
1316 | is called at the end of idle processing. | |
1317 | ||
1318 | @see CanUpdate(), SetUpdateInterval(), SetMode() | |
1319 | */ | |
1320 | static void ResetUpdateTime(); | |
1321 | ||
1322 | /** | |
1323 | Specify how wxWidgets will send update events: to all windows, or only to | |
1324 | those which specify that they will process the events. | |
1325 | ||
1326 | @param mode | |
1327 | this parameter may be one of the ::wxUpdateUIMode enumeration values. | |
1328 | The default mode is wxUPDATE_UI_PROCESS_ALL. | |
1329 | */ | |
1330 | static void SetMode(wxUpdateUIMode mode); | |
1331 | ||
1332 | /** | |
1333 | Sets the text for this UI element. | |
1334 | */ | |
1335 | void SetText(const wxString& text); | |
1336 | ||
1337 | /** | |
1338 | Sets the interval between updates in milliseconds. | |
1339 | ||
1340 | Set to -1 to disable updates, or to 0 to update as frequently as possible. | |
1341 | The default is 0. | |
1342 | ||
1343 | Use this to reduce the overhead of UI update events if your application | |
1344 | has a lot of windows. If you set the value to -1 or greater than 0, | |
1345 | you may also need to call wxWindow::UpdateWindowUI at appropriate points | |
1346 | in your application, such as when a dialog is about to be shown. | |
1347 | */ | |
1348 | static void SetUpdateInterval(long updateInterval); | |
1349 | ||
1350 | /** | |
1351 | Show or hide the UI element. | |
1352 | */ | |
1353 | void Show(bool show); | |
1354 | }; | |
1355 | ||
1356 | ||
1357 | ||
1358 | /** | |
1359 | @class wxClipboardTextEvent | |
1360 | ||
1361 | This class represents the events generated by a control (typically a | |
1362 | wxTextCtrl but other windows can generate these events as well) when its | |
1363 | content gets copied or cut to, or pasted from the clipboard. | |
1364 | ||
1365 | There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY, | |
1366 | wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE. | |
1367 | ||
1368 | If any of these events is processed (without being skipped) by an event | |
1369 | handler, the corresponding operation doesn't take place which allows to | |
1370 | prevent the text from being copied from or pasted to a control. It is also | |
1371 | possible to examine the clipboard contents in the PASTE event handler and | |
1372 | transform it in some way before inserting in a control -- for example, | |
1373 | changing its case or removing invalid characters. | |
1374 | ||
1375 | Finally notice that a CUT event is always preceded by the COPY event which | |
1376 | makes it possible to only process the latter if it doesn't matter if the | |
1377 | text was copied or cut. | |
1378 | ||
1379 | @note | |
1380 | These events are currently only generated by wxTextCtrl under GTK+. | |
1381 | They are generated by all controls under Windows. | |
1382 | ||
1383 | @beginEventTable{wxClipboardTextEvent} | |
1384 | @event{EVT_TEXT_COPY(id, func)} | |
1385 | Some or all of the controls content was copied to the clipboard. | |
1386 | @event{EVT_TEXT_CUT(id, func)} | |
1387 | Some or all of the controls content was cut (i.e. copied and | |
1388 | deleted). | |
1389 | @event{EVT_TEXT_PASTE(id, func)} | |
1390 | Clipboard content was pasted into the control. | |
1391 | @endEventTable | |
1392 | ||
1393 | ||
1394 | @library{wxcore} | |
1395 | @category{events} | |
1396 | ||
1397 | @see wxClipboard | |
1398 | */ | |
1399 | class wxClipboardTextEvent : public wxCommandEvent | |
1400 | { | |
1401 | public: | |
1402 | /** | |
1403 | Constructor. | |
1404 | */ | |
1405 | wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0); | |
1406 | }; | |
1407 | ||
1408 | ||
1409 | ||
1410 | /** | |
1411 | @class wxMouseEvent | |
1412 | ||
1413 | This event class contains information about the events generated by the mouse: | |
1414 | they include mouse buttons press and release events and mouse move events. | |
1415 | ||
1416 | All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the | |
1417 | left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and | |
1418 | @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more | |
1419 | buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events | |
1420 | can also be generated. Note that not all mice have even a middle button so a | |
1421 | portable application should avoid relying on the events from it (but the right | |
1422 | button click can be emulated using the left mouse button with the control key | |
1423 | under Mac platforms with a single button mouse). | |
1424 | ||
1425 | For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events | |
1426 | purposes, the mouse is considered to be inside the window if it is in the | |
1427 | window client area and not inside one of its children. In other words, the | |
1428 | parent window receives @c wxEVT_LEAVE_WINDOW event not only when the | |
1429 | mouse leaves the window entirely but also when it enters one of its children. | |
1430 | ||
1431 | The position associated with a mouse event is expressed in the window | |
1432 | coordinates of the window which generated the event, you can use | |
1433 | wxWindow::ClientToScreen() to convert it to screen coordinates and possibly | |
1434 | call wxWindow::ScreenToClient() next to convert it to window coordinates of | |
1435 | another window. | |
1436 | ||
1437 | @note Note that under Windows CE mouse enter and leave events are not natively | |
1438 | supported by the system but are generated by wxWidgets itself. This has several | |
1439 | drawbacks: the LEAVE_WINDOW event might be received some time after the mouse | |
1440 | left the window and the state variables for it may have changed during this time. | |
1441 | ||
1442 | @note Note the difference between methods like wxMouseEvent::LeftDown and | |
1443 | wxMouseEvent::LeftIsDown: the former returns @true when the event corresponds | |
1444 | to the left mouse button click while the latter returns @true if the left | |
1445 | mouse button is currently being pressed. For example, when the user is dragging | |
1446 | the mouse you can use wxMouseEvent::LeftIsDown to test whether the left mouse | |
1447 | button is (still) depressed. Also, by convention, if wxMouseEvent::LeftDown | |
1448 | returns @true, wxMouseEvent::LeftIsDown will also return @true in wxWidgets | |
1449 | whatever the underlying GUI behaviour is (which is platform-dependent). | |
1450 | The same applies, of course, to other mouse buttons as well. | |
1451 | ||
1452 | ||
1453 | @beginEventTable{wxMouseEvent} | |
1454 | @event{EVT_LEFT_DOWN(func)} | |
1455 | Process a wxEVT_LEFT_DOWN event. The handler of this event should normally | |
1456 | call event.Skip() to allow the default processing to take place as otherwise | |
1457 | the window under mouse wouldn't get the focus. | |
1458 | @event{EVT_LEFT_UP(func)} | |
1459 | Process a wxEVT_LEFT_UP event. | |
1460 | @event{EVT_LEFT_DCLICK(func)} | |
1461 | Process a wxEVT_LEFT_DCLICK event. | |
1462 | @event{EVT_MIDDLE_DOWN(func)} | |
1463 | Process a wxEVT_MIDDLE_DOWN event. | |
1464 | @event{EVT_MIDDLE_UP(func)} | |
1465 | Process a wxEVT_MIDDLE_UP event. | |
1466 | @event{EVT_MIDDLE_DCLICK(func)} | |
1467 | Process a wxEVT_MIDDLE_DCLICK event. | |
1468 | @event{EVT_RIGHT_DOWN(func)} | |
1469 | Process a wxEVT_RIGHT_DOWN event. | |
1470 | @event{EVT_RIGHT_UP(func)} | |
1471 | Process a wxEVT_RIGHT_UP event. | |
1472 | @event{EVT_RIGHT_DCLICK(func)} | |
1473 | Process a wxEVT_RIGHT_DCLICK event. | |
1474 | @event{EVT_MOUSE_AUX1_DOWN(func)} | |
1475 | Process a wxEVT_MOUSE_AUX1_DOWN event. | |
1476 | @event{EVT_MOUSE_AUX1_UP(func)} | |
1477 | Process a wxEVT_MOUSE_AUX1_UP event. | |
1478 | @event{EVT_MOUSE_AUX1_DCLICK(func)} | |
1479 | Process a wxEVT_MOUSE_AUX1_DCLICK event. | |
1480 | @event{EVT_MOUSE_AUX2_DOWN(func)} | |
1481 | Process a wxEVT_MOUSE_AUX2_DOWN event. | |
1482 | @event{EVT_MOUSE_AUX2_UP(func)} | |
1483 | Process a wxEVT_MOUSE_AUX2_UP event. | |
1484 | @event{EVT_MOUSE_AUX2_DCLICK(func)} | |
1485 | Process a wxEVT_MOUSE_AUX2_DCLICK event. | |
1486 | @event{EVT_MOTION(func)} | |
1487 | Process a wxEVT_MOTION event. | |
1488 | @event{EVT_ENTER_WINDOW(func)} | |
1489 | Process a wxEVT_ENTER_WINDOW event. | |
1490 | @event{EVT_LEAVE_WINDOW(func)} | |
1491 | Process a wxEVT_LEAVE_WINDOW event. | |
1492 | @event{EVT_MOUSEWHEEL(func)} | |
1493 | Process a wxEVT_MOUSEWHEEL event. | |
1494 | @event{EVT_MOUSE_EVENTS(func)} | |
1495 | Process all mouse events. | |
1496 | @endEventTable | |
1497 | ||
1498 | @library{wxcore} | |
1499 | @category{events} | |
1500 | ||
1501 | @see wxKeyEvent | |
1502 | */ | |
1503 | class wxMouseEvent : public wxEvent, | |
1504 | public wxMouseState | |
1505 | { | |
1506 | public: | |
1507 | /** | |
1508 | Constructor. Valid event types are: | |
1509 | ||
1510 | @li wxEVT_ENTER_WINDOW | |
1511 | @li wxEVT_LEAVE_WINDOW | |
1512 | @li wxEVT_LEFT_DOWN | |
1513 | @li wxEVT_LEFT_UP | |
1514 | @li wxEVT_LEFT_DCLICK | |
1515 | @li wxEVT_MIDDLE_DOWN | |
1516 | @li wxEVT_MIDDLE_UP | |
1517 | @li wxEVT_MIDDLE_DCLICK | |
1518 | @li wxEVT_RIGHT_DOWN | |
1519 | @li wxEVT_RIGHT_UP | |
1520 | @li wxEVT_RIGHT_DCLICK | |
1521 | @li wxEVT_MOUSE_AUX1_DOWN | |
1522 | @li wxEVT_MOUSE_AUX1_UP | |
1523 | @li wxEVT_MOUSE_AUX1_DCLICK | |
1524 | @li wxEVT_MOUSE_AUX2_DOWN | |
1525 | @li wxEVT_MOUSE_AUX2_UP | |
1526 | @li wxEVT_MOUSE_AUX2_DCLICK | |
1527 | @li wxEVT_MOTION | |
1528 | @li wxEVT_MOUSEWHEEL | |
1529 | */ | |
1530 | wxMouseEvent(wxEventType mouseEventType = wxEVT_NULL); | |
1531 | ||
1532 | /** | |
1533 | Returns @true if the event was a first extra button double click. | |
1534 | */ | |
1535 | bool Aux1DClick() const; | |
1536 | ||
1537 | /** | |
1538 | Returns @true if the first extra button mouse button changed to down. | |
1539 | */ | |
1540 | bool Aux1Down() const; | |
1541 | ||
1542 | /** | |
1543 | Returns @true if the first extra button mouse button is currently down, | |
1544 | independent of the current event type. | |
1545 | */ | |
1546 | bool Aux1IsDown() const; | |
1547 | ||
1548 | /** | |
1549 | Returns @true if the first extra button mouse button changed to up. | |
1550 | */ | |
1551 | bool Aux1Up() const; | |
1552 | ||
1553 | /** | |
1554 | Returns @true if the event was a second extra button double click. | |
1555 | */ | |
1556 | bool Aux2DClick() const; | |
1557 | ||
1558 | /** | |
1559 | Returns @true if the second extra button mouse button changed to down. | |
1560 | */ | |
1561 | bool Aux2Down() const; | |
1562 | ||
1563 | /** | |
1564 | Returns @true if the second extra button mouse button is currently down, | |
1565 | independent of the current event type. | |
1566 | */ | |
1567 | bool Aux2IsDown() const; | |
1568 | ||
1569 | /** | |
1570 | Returns @true if the second extra button mouse button changed to up. | |
1571 | */ | |
1572 | bool Aux2Up() const; | |
1573 | ||
1574 | /** | |
1575 | Returns @true if the identified mouse button is changing state. | |
1576 | Valid values of @a button are: | |
1577 | ||
1578 | @li @c wxMOUSE_BTN_LEFT: check if left button was pressed | |
1579 | @li @c wxMOUSE_BTN_MIDDLE: check if middle button was pressed | |
1580 | @li @c wxMOUSE_BTN_RIGHT: check if right button was pressed | |
1581 | @li @c wxMOUSE_BTN_AUX1: check if the first extra button was pressed | |
1582 | @li @c wxMOUSE_BTN_AUX2: check if the second extra button was pressed | |
1583 | @li @c wxMOUSE_BTN_ANY: check if any button was pressed | |
1584 | ||
1585 | @todo introduce wxMouseButton enum | |
1586 | */ | |
1587 | bool Button(int button) const; | |
1588 | ||
1589 | /** | |
1590 | If the argument is omitted, this returns @true if the event was a mouse | |
1591 | double click event. Otherwise the argument specifies which double click event | |
1592 | was generated (see Button() for the possible values). | |
1593 | */ | |
1594 | bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const; | |
1595 | ||
1596 | /** | |
1597 | If the argument is omitted, this returns @true if the event was a mouse | |
1598 | button down event. Otherwise the argument specifies which button-down event | |
1599 | was generated (see Button() for the possible values). | |
1600 | */ | |
1601 | bool ButtonDown(int = wxMOUSE_BTN_ANY) const; | |
1602 | ||
1603 | /** | |
1604 | If the argument is omitted, this returns @true if the event was a mouse | |
1605 | button up event. Otherwise the argument specifies which button-up event | |
1606 | was generated (see Button() for the possible values). | |
1607 | */ | |
1608 | bool ButtonUp(int = wxMOUSE_BTN_ANY) const; | |
1609 | ||
1610 | /** | |
1611 | Returns @true if this was a dragging event (motion while a button is depressed). | |
1612 | ||
1613 | @see Moving() | |
1614 | */ | |
1615 | bool Dragging() const; | |
1616 | ||
1617 | /** | |
1618 | Returns @true if the mouse was entering the window. | |
1619 | ||
1620 | @see Leaving() | |
1621 | */ | |
1622 | bool Entering() const; | |
1623 | ||
1624 | /** | |
1625 | Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE | |
1626 | if no button is involved (for mouse move, enter or leave event, for example). | |
1627 | Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and | |
1628 | double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT | |
1629 | for the same events for the middle and the right buttons respectively. | |
1630 | */ | |
1631 | int GetButton() const; | |
1632 | ||
1633 | /** | |
1634 | Returns the number of mouse clicks for this event: 1 for a simple click, 2 | |
1635 | for a double-click, 3 for a triple-click and so on. | |
1636 | ||
1637 | Currently this function is implemented only in wxMac and returns -1 for the | |
1638 | other platforms (you can still distinguish simple clicks from double-clicks as | |
1639 | they generate different kinds of events however). | |
1640 | ||
1641 | @since 2.9.0 | |
1642 | */ | |
1643 | int GetClickCount() const; | |
1644 | ||
1645 | /** | |
1646 | Returns the configured number of lines (or whatever) to be scrolled per | |
1647 | wheel action. Defaults to three. | |
1648 | */ | |
1649 | int GetLinesPerAction() const; | |
1650 | ||
1651 | /** | |
1652 | Returns the logical mouse position in pixels (i.e. translated according to the | |
1653 | translation set for the DC, which usually indicates that the window has been | |
1654 | scrolled). | |
1655 | */ | |
1656 | wxPoint GetLogicalPosition(const wxDC& dc) const; | |
1657 | ||
1658 | //@{ | |
1659 | /** | |
1660 | Sets *x and *y to the position at which the event occurred. | |
1661 | Returns the physical mouse position in pixels. | |
1662 | ||
1663 | Note that if the mouse event has been artificially generated from a special | |
1664 | keyboard combination (e.g. under Windows when the "menu" key is pressed), the | |
1665 | returned position is ::wxDefaultPosition. | |
1666 | */ | |
1667 | wxPoint GetPosition() const; | |
1668 | void GetPosition(wxCoord* x, wxCoord* y) const; | |
1669 | void GetPosition(long* x, long* y) const; | |
1670 | //@} | |
1671 | ||
1672 | /** | |
1673 | Get wheel delta, normally 120. | |
1674 | ||
1675 | This is the threshold for action to be taken, and one such action | |
1676 | (for example, scrolling one increment) should occur for each delta. | |
1677 | */ | |
1678 | int GetWheelDelta() const; | |
1679 | ||
1680 | /** | |
1681 | Get wheel rotation, positive or negative indicates direction of rotation. | |
1682 | ||
1683 | Current devices all send an event when rotation is at least +/-WheelDelta, but | |
1684 | finer resolution devices can be created in the future. | |
1685 | ||
1686 | Because of this you shouldn't assume that one event is equal to 1 line, but you | |
1687 | should be able to either do partial line scrolling or wait until several | |
1688 | events accumulate before scrolling. | |
1689 | */ | |
1690 | int GetWheelRotation() const; | |
1691 | ||
1692 | /** | |
1693 | Gets the axis the wheel operation concerns; @c 0 is the Y axis as on | |
1694 | most mouse wheels, @c 1 is the X axis. | |
1695 | ||
1696 | Note that only some models of mouse have horizontal wheel axis. | |
1697 | */ | |
1698 | int GetWheelAxis() const; | |
1699 | ||
1700 | /** | |
1701 | Returns X coordinate of the physical mouse event position. | |
1702 | */ | |
1703 | wxCoord GetX() const; | |
1704 | ||
1705 | /** | |
1706 | Returns Y coordinate of the physical mouse event position. | |
1707 | */ | |
1708 | wxCoord GetY() const; | |
1709 | ||
1710 | /** | |
1711 | Returns @true if the event was a mouse button event (not necessarily a button | |
1712 | down event - that may be tested using ButtonDown()). | |
1713 | */ | |
1714 | bool IsButton() const; | |
1715 | ||
1716 | /** | |
1717 | Returns @true if the system has been setup to do page scrolling with | |
1718 | the mouse wheel instead of line scrolling. | |
1719 | */ | |
1720 | bool IsPageScroll() const; | |
1721 | ||
1722 | /** | |
1723 | Returns @true if the mouse was leaving the window. | |
1724 | ||
1725 | @see Entering(). | |
1726 | */ | |
1727 | bool Leaving() const; | |
1728 | ||
1729 | /** | |
1730 | Returns @true if the event was a left double click. | |
1731 | */ | |
1732 | bool LeftDClick() const; | |
1733 | ||
1734 | /** | |
1735 | Returns @true if the left mouse button changed to down. | |
1736 | */ | |
1737 | bool LeftDown() const; | |
1738 | ||
1739 | /** | |
1740 | Returns @true if the left mouse button is currently down, independent | |
1741 | of the current event type. | |
1742 | ||
1743 | Please notice that it is not the same as LeftDown() which returns @true if the | |
1744 | event was generated by the left mouse button being pressed. Rather, it simply | |
1745 | describes the state of the left mouse button at the time when the event was | |
1746 | generated (so while it will be @true for a left click event, it can also be @true | |
1747 | for a right click if it happened while the left mouse button was pressed). | |
1748 | ||
1749 | This event is usually used in the mouse event handlers which process "move | |
1750 | mouse" messages to determine whether the user is (still) dragging the mouse. | |
1751 | */ | |
1752 | bool LeftIsDown() const; | |
1753 | ||
1754 | /** | |
1755 | Returns @true if the left mouse button changed to up. | |
1756 | */ | |
1757 | bool LeftUp() const; | |
1758 | ||
1759 | /** | |
1760 | Returns @true if the Meta key was down at the time of the event. | |
1761 | */ | |
1762 | bool MetaDown() const; | |
1763 | ||
1764 | /** | |
1765 | Returns @true if the event was a middle double click. | |
1766 | */ | |
1767 | bool MiddleDClick() const; | |
1768 | ||
1769 | /** | |
1770 | Returns @true if the middle mouse button changed to down. | |
1771 | */ | |
1772 | bool MiddleDown() const; | |
1773 | ||
1774 | /** | |
1775 | Returns @true if the middle mouse button is currently down, independent | |
1776 | of the current event type. | |
1777 | */ | |
1778 | bool MiddleIsDown() const; | |
1779 | ||
1780 | /** | |
1781 | Returns @true if the middle mouse button changed to up. | |
1782 | */ | |
1783 | bool MiddleUp() const; | |
1784 | ||
1785 | /** | |
1786 | Returns @true if this was a motion event and no mouse buttons were pressed. | |
1787 | If any mouse button is held pressed, then this method returns @false and | |
1788 | Dragging() returns @true. | |
1789 | */ | |
1790 | bool Moving() const; | |
1791 | ||
1792 | /** | |
1793 | Returns @true if the event was a right double click. | |
1794 | */ | |
1795 | bool RightDClick() const; | |
1796 | ||
1797 | /** | |
1798 | Returns @true if the right mouse button changed to down. | |
1799 | */ | |
1800 | bool RightDown() const; | |
1801 | ||
1802 | /** | |
1803 | Returns @true if the right mouse button is currently down, independent | |
1804 | of the current event type. | |
1805 | */ | |
1806 | bool RightIsDown() const; | |
1807 | ||
1808 | /** | |
1809 | Returns @true if the right mouse button changed to up. | |
1810 | */ | |
1811 | bool RightUp() const; | |
1812 | }; | |
1813 | ||
1814 | ||
1815 | ||
1816 | /** | |
1817 | @class wxDropFilesEvent | |
1818 | ||
1819 | This class is used for drop files events, that is, when files have been dropped | |
1820 | onto the window. This functionality is currently only available under Windows. | |
1821 | ||
1822 | The window must have previously been enabled for dropping by calling | |
1823 | wxWindow::DragAcceptFiles(). | |
1824 | ||
1825 | Important note: this is a separate implementation to the more general drag and drop | |
1826 | implementation documented in the @ref overview_dnd. It uses the older, Windows | |
1827 | message-based approach of dropping files. | |
1828 | ||
1829 | @beginEventTable{wxDropFilesEvent} | |
1830 | @event{EVT_DROP_FILES(func)} | |
1831 | Process a wxEVT_DROP_FILES event. | |
1832 | @endEventTable | |
1833 | ||
1834 | @onlyfor{wxmsw} | |
1835 | ||
1836 | @library{wxcore} | |
1837 | @category{events} | |
1838 | ||
1839 | @see @ref overview_eventhandling | |
1840 | */ | |
1841 | class wxDropFilesEvent : public wxEvent | |
1842 | { | |
1843 | public: | |
1844 | /** | |
1845 | Constructor. | |
1846 | */ | |
1847 | wxDropFilesEvent(wxEventType id = 0, int noFiles = 0, | |
1848 | wxString* files = NULL); | |
1849 | ||
1850 | /** | |
1851 | Returns an array of filenames. | |
1852 | */ | |
1853 | wxString* GetFiles() const; | |
1854 | ||
1855 | /** | |
1856 | Returns the number of files dropped. | |
1857 | */ | |
1858 | int GetNumberOfFiles() const; | |
1859 | ||
1860 | /** | |
1861 | Returns the position at which the files were dropped. | |
1862 | Returns an array of filenames. | |
1863 | */ | |
1864 | wxPoint GetPosition() const; | |
1865 | }; | |
1866 | ||
1867 | ||
1868 | ||
1869 | /** | |
1870 | @class wxCommandEvent | |
1871 | ||
1872 | This event class contains information about command events, which originate | |
1873 | from a variety of simple controls. | |
1874 | ||
1875 | More complex controls, such as wxTreeCtrl, have separate command event classes. | |
1876 | ||
1877 | @beginEventTable{wxCommandEvent} | |
1878 | @event{EVT_COMMAND(id, event, func)} | |
1879 | Process a command, supplying the window identifier, command event identifier, | |
1880 | and member function. | |
1881 | @event{EVT_COMMAND_RANGE(id1, id2, event, func)} | |
1882 | Process a command for a range of window identifiers, supplying the minimum and | |
1883 | maximum window identifiers, command event identifier, and member function. | |
1884 | @event{EVT_BUTTON(id, func)} | |
1885 | Process a @c wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control. | |
1886 | @event{EVT_CHECKBOX(id, func)} | |
1887 | Process a @c wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control. | |
1888 | @event{EVT_CHOICE(id, func)} | |
1889 | Process a @c wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control. | |
1890 | @event{EVT_COMBOBOX(id, func)} | |
1891 | Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control. | |
1892 | @event{EVT_LISTBOX(id, func)} | |
1893 | Process a @c wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control. | |
1894 | @event{EVT_LISTBOX_DCLICK(id, func)} | |
1895 | Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control. | |
1896 | @event{EVT_MENU(id, func)} | |
1897 | Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item. | |
1898 | @event{EVT_MENU_RANGE(id1, id2, func)} | |
1899 | Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items. | |
1900 | @event{EVT_CONTEXT_MENU(func)} | |
1901 | Process the event generated when the user has requested a popup menu to appear by | |
1902 | pressing a special keyboard key (under Windows) or by right clicking the mouse. | |
1903 | @event{EVT_RADIOBOX(id, func)} | |
1904 | Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control. | |
1905 | @event{EVT_RADIOBUTTON(id, func)} | |
1906 | Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control. | |
1907 | @event{EVT_SCROLLBAR(id, func)} | |
1908 | Process a @c wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar | |
1909 | control. This is provided for compatibility only; more specific scrollbar event macros | |
1910 | should be used instead (see wxScrollEvent). | |
1911 | @event{EVT_SLIDER(id, func)} | |
1912 | Process a @c wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control. | |
1913 | @event{EVT_TEXT(id, func)} | |
1914 | Process a @c wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control. | |
1915 | @event{EVT_TEXT_ENTER(id, func)} | |
1916 | Process a @c wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control. | |
1917 | Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it | |
1918 | to generate such events. | |
1919 | @event{EVT_TEXT_MAXLEN(id, func)} | |
1920 | Process a @c wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control | |
1921 | when the user tries to enter more characters into it than the limit previously set | |
1922 | with SetMaxLength(). | |
1923 | @event{EVT_TOGGLEBUTTON(id, func)} | |
1924 | Process a @c wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event. | |
1925 | @event{EVT_TOOL(id, func)} | |
1926 | Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c wxEVT_COMMAND_MENU_SELECTED). | |
1927 | Pass the id of the tool. | |
1928 | @event{EVT_TOOL_RANGE(id1, id2, func)} | |
1929 | Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools. | |
1930 | @event{EVT_TOOL_RCLICKED(id, func)} | |
1931 | Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool. | |
1932 | @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)} | |
1933 | Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. | |
1934 | @event{EVT_TOOL_ENTER(id, func)} | |
1935 | Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself. | |
1936 | The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor | |
1937 | has moved off a tool. | |
1938 | @event{EVT_COMMAND_LEFT_CLICK(id, func)} | |
1939 | Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only). | |
1940 | @event{EVT_COMMAND_LEFT_DCLICK(id, func)} | |
1941 | Process a @c wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only). | |
1942 | @event{EVT_COMMAND_RIGHT_CLICK(id, func)} | |
1943 | Process a @c wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only). | |
1944 | @event{EVT_COMMAND_SET_FOCUS(id, func)} | |
1945 | Process a @c wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only). | |
1946 | @event{EVT_COMMAND_KILL_FOCUS(id, func)} | |
1947 | Process a @c wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only). | |
1948 | @event{EVT_COMMAND_ENTER(id, func)} | |
1949 | Process a @c wxEVT_COMMAND_ENTER command, which is generated by a control. | |
1950 | @endEventTable | |
1951 | ||
1952 | @library{wxcore} | |
1953 | @category{events} | |
1954 | */ | |
1955 | class wxCommandEvent : public wxEvent | |
1956 | { | |
1957 | public: | |
1958 | /** | |
1959 | Constructor. | |
1960 | */ | |
1961 | wxCommandEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0); | |
1962 | ||
1963 | /** | |
1964 | Returns client data pointer for a listbox or choice selection event | |
1965 | (not valid for a deselection). | |
1966 | */ | |
1967 | void* GetClientData() const; | |
1968 | ||
1969 | /** | |
1970 | Returns client object pointer for a listbox or choice selection event | |
1971 | (not valid for a deselection). | |
1972 | */ | |
1973 | wxClientData* GetClientObject() const; | |
1974 | ||
1975 | /** | |
1976 | Returns extra information dependant on the event objects type. | |
1977 | ||
1978 | If the event comes from a listbox selection, it is a boolean | |
1979 | determining whether the event was a selection (@true) or a | |
1980 | deselection (@false). A listbox deselection only occurs for | |
1981 | multiple-selection boxes, and in this case the index and string values | |
1982 | are indeterminate and the listbox must be examined by the application. | |
1983 | */ | |
1984 | long GetExtraLong() const; | |
1985 | ||
1986 | /** | |
1987 | Returns the integer identifier corresponding to a listbox, choice or | |
1988 | radiobox selection (only if the event was a selection, not a deselection), | |
1989 | or a boolean value representing the value of a checkbox. | |
1990 | */ | |
1991 | int GetInt() const; | |
1992 | ||
1993 | /** | |
1994 | Returns item index for a listbox or choice selection event (not valid for | |
1995 | a deselection). | |
1996 | */ | |
1997 | int GetSelection() const; | |
1998 | ||
1999 | /** | |
2000 | Returns item string for a listbox or choice selection event. If one | |
2001 | or several items have been deselected, returns the index of the first | |
2002 | deselected item. If some items have been selected and others deselected | |
2003 | at the same time, it will return the index of the first selected item. | |
2004 | */ | |
2005 | wxString GetString() const; | |
2006 | ||
2007 | /** | |
2008 | This method can be used with checkbox and menu events: for the checkboxes, the | |
2009 | method returns @true for a selection event and @false for a deselection one. | |
2010 | For the menu events, this method indicates if the menu item just has become | |
2011 | checked or unchecked (and thus only makes sense for checkable menu items). | |
2012 | ||
2013 | Notice that this method can not be used with wxCheckListBox currently. | |
2014 | */ | |
2015 | bool IsChecked() const; | |
2016 | ||
2017 | /** | |
2018 | For a listbox or similar event, returns @true if it is a selection, @false | |
2019 | if it is a deselection. If some items have been selected and others deselected | |
2020 | at the same time, it will return @true. | |
2021 | */ | |
2022 | bool IsSelection() const; | |
2023 | ||
2024 | /** | |
2025 | Sets the client data for this event. | |
2026 | */ | |
2027 | void SetClientData(void* clientData); | |
2028 | ||
2029 | /** | |
2030 | Sets the client object for this event. The client object is not owned by the | |
2031 | event object and the event object will not delete the client object in its destructor. | |
2032 | ||
2033 | The client object must be owned and deleted by another object (e.g. a control) | |
2034 | that has longer life time than the event object. | |
2035 | */ | |
2036 | void SetClientObject(wxClientData* clientObject); | |
2037 | ||
2038 | /** | |
2039 | Sets the @b m_extraLong member. | |
2040 | */ | |
2041 | void SetExtraLong(long extraLong); | |
2042 | ||
2043 | /** | |
2044 | Sets the @b m_commandInt member. | |
2045 | */ | |
2046 | void SetInt(int intCommand); | |
2047 | ||
2048 | /** | |
2049 | Sets the @b m_commandString member. | |
2050 | */ | |
2051 | void SetString(const wxString& string); | |
2052 | }; | |
2053 | ||
2054 | ||
2055 | ||
2056 | /** | |
2057 | @class wxActivateEvent | |
2058 | ||
2059 | An activate event is sent when a window or application is being activated | |
2060 | or deactivated. | |
2061 | ||
2062 | @beginEventTable{wxActivateEvent} | |
2063 | @event{EVT_ACTIVATE(func)} | |
2064 | Process a wxEVT_ACTIVATE event. | |
2065 | @event{EVT_ACTIVATE_APP(func)} | |
2066 | Process a wxEVT_ACTIVATE_APP event. | |
2067 | @event{EVT_HIBERNATE(func)} | |
2068 | Process a hibernate event, supplying the member function. This event applies | |
2069 | to wxApp only, and only on Windows SmartPhone and PocketPC. | |
2070 | It is generated when the system is low on memory; the application should free | |
2071 | up as much memory as possible, and restore full working state when it receives | |
2072 | a wxEVT_ACTIVATE or wxEVT_ACTIVATE_APP event. | |
2073 | @endEventTable | |
2074 | ||
2075 | ||
2076 | @library{wxcore} | |
2077 | @category{events} | |
2078 | ||
2079 | @see @ref overview_eventhandling, wxApp::IsActive | |
2080 | */ | |
2081 | class wxActivateEvent : public wxEvent | |
2082 | { | |
2083 | public: | |
2084 | /** | |
2085 | Constructor. | |
2086 | */ | |
2087 | wxActivateEvent(wxEventType eventType = wxEVT_NULL, bool active = true, | |
2088 | int id = 0); | |
2089 | ||
2090 | /** | |
2091 | Returns @true if the application or window is being activated, @false otherwise. | |
2092 | */ | |
2093 | bool GetActive() const; | |
2094 | }; | |
2095 | ||
2096 | ||
2097 | ||
2098 | /** | |
2099 | @class wxContextMenuEvent | |
2100 | ||
2101 | This class is used for context menu events, sent to give | |
2102 | the application a chance to show a context (popup) menu. | |
2103 | ||
2104 | Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this | |
2105 | means that the event originated from a keyboard context button event, and you | |
2106 | should compute a suitable position yourself, for example by calling wxGetMousePosition(). | |
2107 | ||
2108 | When a keyboard context menu button is pressed on Windows, a right-click event | |
2109 | with default position is sent first, and if this event is not processed, the | |
2110 | context menu event is sent. So if you process mouse events and you find your | |
2111 | context menu event handler is not being called, you could call wxEvent::Skip() | |
2112 | for mouse right-down events. | |
2113 | ||
2114 | @beginEventTable{wxContextMenuEvent} | |
2115 | @event{EVT_CONTEXT_MENU(func)} | |
2116 | A right click (or other context menu command depending on platform) has been detected. | |
2117 | @endEventTable | |
2118 | ||
2119 | ||
2120 | @library{wxcore} | |
2121 | @category{events} | |
2122 | ||
2123 | @see wxCommandEvent, @ref overview_eventhandling | |
2124 | */ | |
2125 | class wxContextMenuEvent : public wxCommandEvent | |
2126 | { | |
2127 | public: | |
2128 | /** | |
2129 | Constructor. | |
2130 | */ | |
2131 | wxContextMenuEvent(wxEventType id = wxEVT_NULL, int id = 0, | |
2132 | const wxPoint& pos = wxDefaultPosition); | |
2133 | ||
2134 | /** | |
2135 | Returns the position in screen coordinates at which the menu should be shown. | |
2136 | Use wxWindow::ScreenToClient to convert to client coordinates. | |
2137 | ||
2138 | You can also omit a position from wxWindow::PopupMenu in order to use | |
2139 | the current mouse pointer position. | |
2140 | ||
2141 | If the event originated from a keyboard event, the value returned from this | |
2142 | function will be wxDefaultPosition. | |
2143 | */ | |
2144 | const wxPoint& GetPosition() const; | |
2145 | ||
2146 | /** | |
2147 | Sets the position at which the menu should be shown. | |
2148 | */ | |
2149 | void SetPosition(const wxPoint& point); | |
2150 | }; | |
2151 | ||
2152 | ||
2153 | ||
2154 | /** | |
2155 | @class wxEraseEvent | |
2156 | ||
2157 | An erase event is sent when a window's background needs to be repainted. | |
2158 | ||
2159 | On some platforms, such as GTK+, this event is simulated (simply generated just | |
2160 | before the paint event) and may cause flicker. It is therefore recommended that | |
2161 | you set the text background colour explicitly in order to prevent flicker. | |
2162 | The default background colour under GTK+ is grey. | |
2163 | ||
2164 | To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table | |
2165 | definition. | |
2166 | ||
2167 | You must call wxEraseEvent::GetDC and use the returned device context if it is | |
2168 | non-@NULL. If it is @NULL, create your own temporary wxClientDC object. | |
2169 | ||
2170 | @remarks | |
2171 | Use the device context returned by GetDC to draw on, don't create | |
2172 | a wxPaintDC in the event handler. | |
2173 | ||
2174 | @beginEventTable{wxEraseEvent} | |
2175 | @event{EVT_ERASE_BACKGROUND(func)} | |
2176 | Process a wxEVT_ERASE_BACKGROUND event. | |
2177 | @endEventTable | |
2178 | ||
2179 | @library{wxcore} | |
2180 | @category{events} | |
2181 | ||
2182 | @see @ref overview_eventhandling | |
2183 | */ | |
2184 | class wxEraseEvent : public wxEvent | |
2185 | { | |
2186 | public: | |
2187 | /** | |
2188 | Constructor. | |
2189 | */ | |
2190 | wxEraseEvent(int id = 0, wxDC* dc = NULL); | |
2191 | ||
2192 | /** | |
2193 | Returns the device context associated with the erase event to draw on. | |
2194 | */ | |
2195 | wxDC* GetDC() const; | |
2196 | }; | |
2197 | ||
2198 | ||
2199 | ||
2200 | /** | |
2201 | @class wxFocusEvent | |
2202 | ||
2203 | A focus event is sent when a window's focus changes. The window losing focus | |
2204 | receives a "kill focus" event while the window gaining it gets a "set focus" one. | |
2205 | ||
2206 | Notice that the set focus event happens both when the user gives focus to the | |
2207 | window (whether using the mouse or keyboard) and when it is done from the | |
2208 | program itself using wxWindow::SetFocus. | |
2209 | ||
2210 | @beginEventTable{wxFocusEvent} | |
2211 | @event{EVT_SET_FOCUS(func)} | |
2212 | Process a wxEVT_SET_FOCUS event. | |
2213 | @event{EVT_KILL_FOCUS(func)} | |
2214 | Process a wxEVT_KILL_FOCUS event. | |
2215 | @endEventTable | |
2216 | ||
2217 | @library{wxcore} | |
2218 | @category{events} | |
2219 | ||
2220 | @see @ref overview_eventhandling | |
2221 | */ | |
2222 | class wxFocusEvent : public wxEvent | |
2223 | { | |
2224 | public: | |
2225 | /** | |
2226 | Constructor. | |
2227 | */ | |
2228 | wxFocusEvent(wxEventType eventType = wxEVT_NULL, int id = 0); | |
2229 | ||
2230 | /** | |
2231 | Returns the window associated with this event, that is the window which had the | |
2232 | focus before for the @c wxEVT_SET_FOCUS event and the window which is | |
2233 | going to receive focus for the @c wxEVT_KILL_FOCUS one. | |
2234 | ||
2235 | Warning: the window pointer may be @NULL! | |
2236 | */ | |
2237 | wxWindow *GetWindow() const; | |
2238 | }; | |
2239 | ||
2240 | ||
2241 | ||
2242 | /** | |
2243 | @class wxChildFocusEvent | |
2244 | ||
2245 | A child focus event is sent to a (parent-)window when one of its child windows | |
2246 | gains focus, so that the window could restore the focus back to its corresponding | |
2247 | child if it loses it now and regains later. | |
2248 | ||
2249 | Notice that child window is the direct child of the window receiving event. | |
2250 | Use wxWindow::FindFocus() to retreive the window which is actually getting focus. | |
2251 | ||
2252 | @beginEventTable{wxChildFocusEvent} | |
2253 | @event{EVT_CHILD_FOCUS(func)} | |
2254 | Process a wxEVT_CHILD_FOCUS event. | |
2255 | @endEventTable | |
2256 | ||
2257 | @library{wxcore} | |
2258 | @category{events} | |
2259 | ||
2260 | @see @ref overview_eventhandling | |
2261 | */ | |
2262 | class wxChildFocusEvent : public wxCommandEvent | |
2263 | { | |
2264 | public: | |
2265 | /** | |
2266 | Constructor. | |
2267 | ||
2268 | @param win | |
2269 | The direct child which is (or which contains the window which is) receiving | |
2270 | the focus. | |
2271 | */ | |
2272 | wxChildFocusEvent(wxWindow* win = NULL); | |
2273 | ||
2274 | /** | |
2275 | Returns the direct child which receives the focus, or a (grand-)parent of the | |
2276 | control receiving the focus. | |
2277 | ||
2278 | To get the actually focused control use wxWindow::FindFocus. | |
2279 | */ | |
2280 | wxWindow *GetWindow() const; | |
2281 | }; | |
2282 | ||
2283 | ||
2284 | ||
2285 | /** | |
2286 | @class wxMouseCaptureLostEvent | |
2287 | ||
2288 | An mouse capture lost event is sent to a window that obtained mouse capture, | |
2289 | which was subsequently loss due to "external" event, for example when a dialog | |
2290 | box is shown or if another application captures the mouse. | |
2291 | ||
2292 | If this happens, this event is sent to all windows that are on capture stack | |
2293 | (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is | |
2294 | not sent if the capture changes because of a call to CaptureMouse or | |
2295 | ReleaseMouse. | |
2296 | ||
2297 | This event is currently emitted under Windows only. | |
2298 | ||
2299 | @beginEventTable{wxMouseCaptureLostEvent} | |
2300 | @event{EVT_MOUSE_CAPTURE_LOST(func)} | |
2301 | Process a wxEVT_MOUSE_CAPTURE_LOST event. | |
2302 | @endEventTable | |
2303 | ||
2304 | @onlyfor{wxmsw} | |
2305 | ||
2306 | @library{wxcore} | |
2307 | @category{events} | |
2308 | ||
2309 | @see wxMouseCaptureChangedEvent, @ref overview_eventhandling, | |
2310 | wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture | |
2311 | */ | |
2312 | class wxMouseCaptureLostEvent : public wxEvent | |
2313 | { | |
2314 | public: | |
2315 | /** | |
2316 | Constructor. | |
2317 | */ | |
2318 | wxMouseCaptureLostEvent(wxWindowID windowId = 0); | |
2319 | }; | |
2320 | ||
2321 | ||
2322 | ||
2323 | /** | |
2324 | @class wxNotifyEvent | |
2325 | ||
2326 | This class is not used by the event handlers by itself, but is a base class | |
2327 | for other event classes (such as wxBookCtrlEvent). | |
2328 | ||
2329 | It (or an object of a derived class) is sent when the controls state is being | |
2330 | changed and allows the program to wxNotifyEvent::Veto() this change if it wants | |
2331 | to prevent it from happening. | |
2332 | ||
2333 | @library{wxcore} | |
2334 | @category{events} | |
2335 | ||
2336 | @see wxBookCtrlEvent | |
2337 | */ | |
2338 | class wxNotifyEvent : public wxCommandEvent | |
2339 | { | |
2340 | public: | |
2341 | /** | |
2342 | Constructor (used internally by wxWidgets only). | |
2343 | */ | |
2344 | wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0); | |
2345 | ||
2346 | /** | |
2347 | This is the opposite of Veto(): it explicitly allows the event to be processed. | |
2348 | For most events it is not necessary to call this method as the events are allowed | |
2349 | anyhow but some are forbidden by default (this will be mentioned in the corresponding | |
2350 | event description). | |
2351 | */ | |
2352 | void Allow(); | |
2353 | ||
2354 | /** | |
2355 | Returns @true if the change is allowed (Veto() hasn't been called) or @false | |
2356 | otherwise (if it was). | |
2357 | */ | |
2358 | bool IsAllowed() const; | |
2359 | ||
2360 | /** | |
2361 | Prevents the change announced by this event from happening. | |
2362 | ||
2363 | It is in general a good idea to notify the user about the reasons for vetoing | |
2364 | the change because otherwise the applications behaviour (which just refuses to | |
2365 | do what the user wants) might be quite surprising. | |
2366 | */ | |
2367 | void Veto(); | |
2368 | }; | |
2369 | ||
2370 | ||
2371 | ||
2372 | ||
2373 | enum wxHelpEventOrigin | |
2374 | { | |
2375 | wxHE_ORIGIN_UNKNOWN = -1, | |
2376 | wxHE_ORIGIN_KEYBOARD, | |
2377 | ||
2378 | /** event generated by wxContextHelp or from the [?] button on | |
2379 | the title bar (Windows). */ | |
2380 | wxHE_ORIGIN_HELPBUTTON | |
2381 | }; | |
2382 | ||
2383 | /** | |
2384 | @class wxHelpEvent | |
2385 | ||
2386 | A help event is sent when the user has requested context-sensitive help. | |
2387 | This can either be caused by the application requesting context-sensitive help mode | |
2388 | via wxContextHelp, or (on MS Windows) by the system generating a WM_HELP message when | |
2389 | the user pressed F1 or clicked on the query button in a dialog caption. | |
2390 | ||
2391 | A help event is sent to the window that the user clicked on, and is propagated | |
2392 | up the window hierarchy until the event is processed or there are no more event | |
2393 | handlers. | |
2394 | ||
2395 | The application should call wxEvent::GetId to check the identity of the | |
2396 | clicked-on window, and then either show some suitable help or call wxEvent::Skip() | |
2397 | if the identifier is unrecognised. | |
2398 | ||
2399 | Calling Skip is important because it allows wxWidgets to generate further | |
2400 | events for ancestors of the clicked-on window. Otherwise it would be impossible to | |
2401 | show help for container windows, since processing would stop after the first window | |
2402 | found. | |
2403 | ||
2404 | @beginEventTable{wxHelpEvent} | |
2405 | @event{EVT_HELP(id, func)} | |
2406 | Process a wxEVT_HELP event. | |
2407 | @event{EVT_HELP_RANGE(id1, id2, func)} | |
2408 | Process a wxEVT_HELP event for a range of ids. | |
2409 | @endEventTable | |
2410 | ||
2411 | @library{wxcore} | |
2412 | @category{events} | |
2413 | ||
2414 | @see wxContextHelp, wxDialog, @ref overview_eventhandling | |
2415 | */ | |
2416 | class wxHelpEvent : public wxCommandEvent | |
2417 | { | |
2418 | public: | |
2419 | /** | |
2420 | Indicates how a wxHelpEvent was generated. | |
2421 | */ | |
2422 | enum Origin | |
2423 | { | |
2424 | Origin_Unknown, /**< unrecognized event source. */ | |
2425 | Origin_Keyboard, /**< event generated from F1 key press. */ | |
2426 | ||
2427 | /** event generated by wxContextHelp or from the [?] button on | |
2428 | the title bar (Windows). */ | |
2429 | Origin_HelpButton | |
2430 | }; | |
2431 | ||
2432 | /** | |
2433 | Constructor. | |
2434 | */ | |
2435 | wxHelpEvent(wxEventType type = wxEVT_NULL, | |
2436 | wxWindowID winid = 0, | |
2437 | const wxPoint& pt = wxDefaultPosition, | |
2438 | wxHelpEvent::Origin origin = Origin_Unknown); | |
2439 | ||
2440 | /** | |
2441 | Returns the origin of the help event which is one of the ::wxHelpEventOrigin | |
2442 | values. | |
2443 | ||
2444 | The application may handle events generated using the keyboard or mouse | |
2445 | differently, e.g. by using wxGetMousePosition() for the mouse events. | |
2446 | ||
2447 | @see SetOrigin() | |
2448 | */ | |
2449 | wxHelpEvent::Origin GetOrigin() const; | |
2450 | ||
2451 | /** | |
2452 | Returns the left-click position of the mouse, in screen coordinates. | |
2453 | This allows the application to position the help appropriately. | |
2454 | */ | |
2455 | const wxPoint& GetPosition() const; | |
2456 | ||
2457 | /** | |
2458 | Set the help event origin, only used internally by wxWidgets normally. | |
2459 | ||
2460 | @see GetOrigin() | |
2461 | */ | |
2462 | void SetOrigin(wxHelpEvent::Origin origin); | |
2463 | ||
2464 | /** | |
2465 | Sets the left-click position of the mouse, in screen coordinates. | |
2466 | */ | |
2467 | void SetPosition(const wxPoint& pt); | |
2468 | }; | |
2469 | ||
2470 | ||
2471 | ||
2472 | /** | |
2473 | @class wxScrollEvent | |
2474 | ||
2475 | A scroll event holds information about events sent from stand-alone | |
2476 | scrollbars (see wxScrollBar) and sliders (see wxSlider). | |
2477 | ||
2478 | Note that scrolled windows send the wxScrollWinEvent which does not derive from | |
2479 | wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of | |
2480 | events and use the event table macros mentioned below only for the scrollbar-like | |
2481 | controls. | |
2482 | ||
2483 | @section scrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED | |
2484 | ||
2485 | The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb | |
2486 | using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed | |
2487 | by an EVT_SCROLL_CHANGED event). | |
2488 | ||
2489 | The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change the thumb | |
2490 | position, and when clicking next to the thumb (In all these cases the EVT_SCROLL_THUMBRELEASE | |
2491 | event does not happen). | |
2492 | ||
2493 | In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving has finished | |
2494 | independently of the way it had started. Please see the widgets sample ("Slider" page) | |
2495 | to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action. | |
2496 | ||
2497 | @remarks | |
2498 | Note that unless specifying a scroll control identifier, you will need to test for scrollbar | |
2499 | orientation with wxScrollEvent::GetOrientation, since horizontal and vertical scroll events | |
2500 | are processed using the same event handler. | |
2501 | ||
2502 | @beginEventTable{wxScrollEvent} | |
2503 | You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting | |
2504 | scroll events from controls, or EVT_SCROLL... macros without window IDs for | |
2505 | intercepting scroll events from the receiving window -- except for this, the | |
2506 | macros behave exactly the same. | |
2507 | @event{EVT_SCROLL(func)} | |
2508 | Process all scroll events. | |
2509 | @event{EVT_SCROLL_TOP(func)} | |
2510 | Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position). | |
2511 | @event{EVT_SCROLL_BOTTOM(func)} | |
2512 | Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). | |
2513 | @event{EVT_SCROLL_LINEUP(func)} | |
2514 | Process wxEVT_SCROLL_LINEUP line up events. | |
2515 | @event{EVT_SCROLL_LINEDOWN(func)} | |
2516 | Process wxEVT_SCROLL_LINEDOWN line down events. | |
2517 | @event{EVT_SCROLL_PAGEUP(func)} | |
2518 | Process wxEVT_SCROLL_PAGEUP page up events. | |
2519 | @event{EVT_SCROLL_PAGEDOWN(func)} | |
2520 | Process wxEVT_SCROLL_PAGEDOWN page down events. | |
2521 | @event{EVT_SCROLL_THUMBTRACK(func)} | |
2522 | Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent as the | |
2523 | user drags the thumbtrack). | |
2524 | @event{EVT_SCROLL_THUMBRELEASE(func)} | |
2525 | Process wxEVT_SCROLL_THUMBRELEASE thumb release events. | |
2526 | @event{EVT_SCROLL_CHANGED(func)} | |
2527 | Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). | |
2528 | @event{EVT_COMMAND_SCROLL(id, func)} | |
2529 | Process all scroll events. | |
2530 | @event{EVT_COMMAND_SCROLL_TOP(id, func)} | |
2531 | Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position). | |
2532 | @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)} | |
2533 | Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). | |
2534 | @event{EVT_COMMAND_SCROLL_LINEUP(id, func)} | |
2535 | Process wxEVT_SCROLL_LINEUP line up events. | |
2536 | @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)} | |
2537 | Process wxEVT_SCROLL_LINEDOWN line down events. | |
2538 | @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)} | |
2539 | Process wxEVT_SCROLL_PAGEUP page up events. | |
2540 | @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)} | |
2541 | Process wxEVT_SCROLL_PAGEDOWN page down events. | |
2542 | @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)} | |
2543 | Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent | |
2544 | as the user drags the thumbtrack). | |
2545 | @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)} | |
2546 | Process wxEVT_SCROLL_THUMBRELEASE thumb release events. | |
2547 | @event{EVT_COMMAND_SCROLL_CHANGED(func)} | |
2548 | Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). | |
2549 | @endEventTable | |
2550 | ||
2551 | @library{wxcore} | |
2552 | @category{events} | |
2553 | ||
2554 | @see wxScrollBar, wxSlider, wxSpinButton, wxScrollWinEvent, @ref overview_eventhandling | |
2555 | */ | |
2556 | class wxScrollEvent : public wxCommandEvent | |
2557 | { | |
2558 | public: | |
2559 | /** | |
2560 | Constructor. | |
2561 | */ | |
2562 | wxScrollEvent(wxEventType commandType = wxEVT_NULL, int id = 0, int pos = 0, | |
2563 | int orientation = 0); | |
2564 | ||
2565 | /** | |
2566 | Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the | |
2567 | scrollbar. | |
2568 | */ | |
2569 | int GetOrientation() const; | |
2570 | ||
2571 | /** | |
2572 | Returns the position of the scrollbar. | |
2573 | */ | |
2574 | int GetPosition() const; | |
2575 | }; | |
2576 | ||
2577 | /** | |
2578 | See wxIdleEvent::SetMode() for more info. | |
2579 | */ | |
2580 | enum wxIdleMode | |
2581 | { | |
2582 | /** Send idle events to all windows */ | |
2583 | wxIDLE_PROCESS_ALL, | |
2584 | ||
2585 | /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */ | |
2586 | wxIDLE_PROCESS_SPECIFIED | |
2587 | }; | |
2588 | ||
2589 | ||
2590 | /** | |
2591 | @class wxIdleEvent | |
2592 | ||
2593 | This class is used for idle events, which are generated when the system becomes | |
2594 | idle. Note that, unless you do something specifically, the idle events are not | |
2595 | sent if the system remains idle once it has become it, e.g. only a single idle | |
2596 | event will be generated until something else resulting in more normal events | |
2597 | happens and only then is the next idle event sent again. | |
2598 | ||
2599 | If you need to ensure a continuous stream of idle events, you can either use | |
2600 | wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically | |
2601 | (for example from a timer event handler), but note that both of these approaches | |
2602 | (and especially the first one) increase the system load and so should be avoided | |
2603 | if possible. | |
2604 | ||
2605 | By default, idle events are sent to all windows (and also wxApp, as usual). | |
2606 | If this is causing a significant overhead in your application, you can call | |
2607 | wxIdleEvent::SetMode with the value wxIDLE_PROCESS_SPECIFIED, and set the | |
2608 | wxWS_EX_PROCESS_IDLE extra window style for every window which should receive | |
2609 | idle events. | |
2610 | ||
2611 | @beginEventTable{wxIdleEvent} | |
2612 | @event{EVT_IDLE(func)} | |
2613 | Process a wxEVT_IDLE event. | |
2614 | @endEventTable | |
2615 | ||
2616 | @library{wxbase} | |
2617 | @category{events} | |
2618 | ||
2619 | @see @ref overview_eventhandling, wxUpdateUIEvent, wxWindow::OnInternalIdle | |
2620 | */ | |
2621 | class wxIdleEvent : public wxEvent | |
2622 | { | |
2623 | public: | |
2624 | /** | |
2625 | Constructor. | |
2626 | */ | |
2627 | wxIdleEvent(); | |
2628 | ||
2629 | /** | |
2630 | Returns @true if it is appropriate to send idle events to this window. | |
2631 | ||
2632 | This function looks at the mode used (see wxIdleEvent::SetMode), | |
2633 | and the wxWS_EX_PROCESS_IDLE style in @a window to determine whether idle | |
2634 | events should be sent to this window now. | |
2635 | ||
2636 | By default this will always return @true because the update mode is initially | |
2637 | wxIDLE_PROCESS_ALL. You can change the mode to only send idle events to | |
2638 | windows with the wxWS_EX_PROCESS_IDLE extra window style set. | |
2639 | ||
2640 | @see SetMode() | |
2641 | */ | |
2642 | static bool CanSend(wxWindow* window); | |
2643 | ||
2644 | /** | |
2645 | Static function returning a value specifying how wxWidgets will send idle | |
2646 | events: to all windows, or only to those which specify that they | |
2647 | will process the events. | |
2648 | ||
2649 | @see SetMode(). | |
2650 | */ | |
2651 | static wxIdleMode GetMode(); | |
2652 | ||
2653 | /** | |
2654 | Returns @true if the OnIdle function processing this event requested more | |
2655 | processing time. | |
2656 | ||
2657 | @see RequestMore() | |
2658 | */ | |
2659 | bool MoreRequested() const; | |
2660 | ||
2661 | /** | |
2662 | Tells wxWidgets that more processing is required. | |
2663 | ||
2664 | This function can be called by an OnIdle handler for a window or window event | |
2665 | handler to indicate that wxApp::OnIdle should forward the OnIdle event once | |
2666 | more to the application windows. | |
2667 | ||
2668 | If no window calls this function during OnIdle, then the application will | |
2669 | remain in a passive event loop (not calling OnIdle) until a new event is | |
2670 | posted to the application by the windowing system. | |
2671 | ||
2672 | @see MoreRequested() | |
2673 | */ | |
2674 | void RequestMore(bool needMore = true); | |
2675 | ||
2676 | /** | |
2677 | Static function for specifying how wxWidgets will send idle events: to | |
2678 | all windows, or only to those which specify that they will process the events. | |
2679 | ||
2680 | @param mode | |
2681 | Can be one of the ::wxIdleMode values. | |
2682 | The default is wxIDLE_PROCESS_ALL. | |
2683 | */ | |
2684 | static void SetMode(wxIdleMode mode); | |
2685 | }; | |
2686 | ||
2687 | ||
2688 | ||
2689 | /** | |
2690 | @class wxInitDialogEvent | |
2691 | ||
2692 | A wxInitDialogEvent is sent as a dialog or panel is being initialised. | |
2693 | Handlers for this event can transfer data to the window. | |
2694 | ||
2695 | The default handler calls wxWindow::TransferDataToWindow. | |
2696 | ||
2697 | @beginEventTable{wxInitDialogEvent} | |
2698 | @event{EVT_INIT_DIALOG(func)} | |
2699 | Process a wxEVT_INIT_DIALOG event. | |
2700 | @endEventTable | |
2701 | ||
2702 | @library{wxcore} | |
2703 | @category{events} | |
2704 | ||
2705 | @see @ref overview_eventhandling | |
2706 | */ | |
2707 | class wxInitDialogEvent : public wxEvent | |
2708 | { | |
2709 | public: | |
2710 | /** | |
2711 | Constructor. | |
2712 | */ | |
2713 | wxInitDialogEvent(int id = 0); | |
2714 | }; | |
2715 | ||
2716 | ||
2717 | ||
2718 | /** | |
2719 | @class wxWindowDestroyEvent | |
2720 | ||
2721 | This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a | |
2722 | window is destroyed. | |
2723 | ||
2724 | When a class derived from wxWindow is destroyed its destructor will have | |
2725 | already run by the time this event is sent. Therefore this event will not | |
2726 | usually be received at all. | |
2727 | ||
2728 | To receive this event wxEvtHandler::Connect() must be used (using an event | |
2729 | table macro will not work). Since it is received after the destructor has run, | |
2730 | an object should not handle its own wxWindowDestroyEvent, but it can be used | |
2731 | to get notification of the destruction of another window. | |
2732 | ||
2733 | @library{wxcore} | |
2734 | @category{events} | |
2735 | ||
2736 | @see @ref overview_eventhandling, wxWindowCreateEvent | |
2737 | */ | |
2738 | class wxWindowDestroyEvent : public wxCommandEvent | |
2739 | { | |
2740 | public: | |
2741 | /** | |
2742 | Constructor. | |
2743 | */ | |
2744 | wxWindowDestroyEvent(wxWindow* win = NULL); | |
2745 | }; | |
2746 | ||
2747 | ||
2748 | /** | |
2749 | The possible flag values for a wxNavigationKeyEvent. | |
2750 | */ | |
2751 | enum wxNavigationKeyEventFlags | |
2752 | { | |
2753 | wxNKEF_IS_BACKWARD = 0x0000, | |
2754 | wxNKEF_IS_FORWARD = 0x0001, | |
2755 | wxNKEF_WINCHANGE = 0x0002, | |
2756 | wxNKEF_FROMTAB = 0x0004 | |
2757 | }; | |
2758 | ||
2759 | ||
2760 | /** | |
2761 | @class wxNavigationKeyEvent | |
2762 | ||
2763 | This event class contains information about navigation events, | |
2764 | generated by navigation keys such as tab and page down. | |
2765 | ||
2766 | This event is mainly used by wxWidgets implementations. | |
2767 | A wxNavigationKeyEvent handler is automatically provided by wxWidgets | |
2768 | when you make a class into a control container with the macro | |
2769 | WX_DECLARE_CONTROL_CONTAINER. | |
2770 | ||
2771 | @beginEventTable{wxNavigationKeyEvent} | |
2772 | @event{EVT_NAVIGATION_KEY(func)} | |
2773 | Process a navigation key event. | |
2774 | @endEventTable | |
2775 | ||
2776 | @library{wxcore} | |
2777 | @category{events} | |
2778 | ||
2779 | @see wxWindow::Navigate, wxWindow::NavigateIn | |
2780 | */ | |
2781 | class wxNavigationKeyEvent : public wxEvent | |
2782 | { | |
2783 | public: | |
2784 | wxNavigationKeyEvent(); | |
2785 | wxNavigationKeyEvent(const wxNavigationKeyEvent& event); | |
2786 | ||
2787 | /** | |
2788 | Returns the child that has the focus, or @NULL. | |
2789 | */ | |
2790 | wxWindow* GetCurrentFocus() const; | |
2791 | ||
2792 | /** | |
2793 | Returns @true if the navigation was in the forward direction. | |
2794 | */ | |
2795 | bool GetDirection() const; | |
2796 | ||
2797 | /** | |
2798 | Returns @true if the navigation event was from a tab key. | |
2799 | This is required for proper navigation over radio buttons. | |
2800 | */ | |
2801 | bool IsFromTab() const; | |
2802 | ||
2803 | /** | |
2804 | Returns @true if the navigation event represents a window change | |
2805 | (for example, from Ctrl-Page Down in a notebook). | |
2806 | */ | |
2807 | bool IsWindowChange() const; | |
2808 | ||
2809 | /** | |
2810 | Sets the current focus window member. | |
2811 | */ | |
2812 | void SetCurrentFocus(wxWindow* currentFocus); | |
2813 | ||
2814 | /** | |
2815 | Sets the direction to forward if @a direction is @true, or backward | |
2816 | if @false. | |
2817 | */ | |
2818 | void SetDirection(bool direction); | |
2819 | ||
2820 | /** | |
2821 | Sets the flags for this event. | |
2822 | The @a flags can be a combination of the ::wxNavigationKeyEventFlags values. | |
2823 | */ | |
2824 | void SetFlags(long flags); | |
2825 | ||
2826 | /** | |
2827 | Marks the navigation event as from a tab key. | |
2828 | */ | |
2829 | void SetFromTab(bool fromTab); | |
2830 | ||
2831 | /** | |
2832 | Marks the event as a window change event. | |
2833 | */ | |
2834 | void SetWindowChange(bool windowChange); | |
2835 | }; | |
2836 | ||
2837 | ||
2838 | ||
2839 | /** | |
2840 | @class wxMouseCaptureChangedEvent | |
2841 | ||
2842 | An mouse capture changed event is sent to a window that loses its | |
2843 | mouse capture. This is called even if wxWindow::ReleaseCapture | |
2844 | was called by the application code. Handling this event allows | |
2845 | an application to cater for unexpected capture releases which | |
2846 | might otherwise confuse mouse handling code. | |
2847 | ||
2848 | @onlyfor{wxmsw} | |
2849 | ||
2850 | @beginEventTable{wxMouseCaptureChangedEvent} | |
2851 | @event{EVT_MOUSE_CAPTURE_CHANGED(func)} | |
2852 | Process a wxEVT_MOUSE_CAPTURE_CHANGED event. | |
2853 | @endEventTable | |
2854 | ||
2855 | @library{wxcore} | |
2856 | @category{events} | |
2857 | ||
2858 | @see wxMouseCaptureLostEvent, @ref overview_eventhandling, | |
2859 | wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture | |
2860 | */ | |
2861 | class wxMouseCaptureChangedEvent : public wxEvent | |
2862 | { | |
2863 | public: | |
2864 | /** | |
2865 | Constructor. | |
2866 | */ | |
2867 | wxMouseCaptureChangedEvent(wxWindowID windowId = 0, | |
2868 | wxWindow* gainedCapture = NULL); | |
2869 | ||
2870 | /** | |
2871 | Returns the window that gained the capture, or @NULL if it was a | |
2872 | non-wxWidgets window. | |
2873 | */ | |
2874 | wxWindow* GetCapturedWindow() const; | |
2875 | }; | |
2876 | ||
2877 | ||
2878 | ||
2879 | /** | |
2880 | @class wxCloseEvent | |
2881 | ||
2882 | This event class contains information about window and session close events. | |
2883 | ||
2884 | The handler function for EVT_CLOSE is called when the user has tried to close a | |
2885 | a frame or dialog box using the window manager (X) or system menu (Windows). | |
2886 | It can also be invoked by the application itself programmatically, for example by | |
2887 | calling the wxWindow::Close function. | |
2888 | ||
2889 | You should check whether the application is forcing the deletion of the window | |
2890 | using wxCloseEvent::CanVeto. If this is @false, you @e must destroy the window | |
2891 | using wxWindow::Destroy. | |
2892 | ||
2893 | If the return value is @true, it is up to you whether you respond by destroying | |
2894 | the window. | |
2895 | ||
2896 | If you don't destroy the window, you should call wxCloseEvent::Veto to | |
2897 | let the calling code know that you did not destroy the window. | |
2898 | This allows the wxWindow::Close function to return @true or @false depending | |
2899 | on whether the close instruction was honoured or not. | |
2900 | ||
2901 | Example of a wxCloseEvent handler: | |
2902 | ||
2903 | @code | |
2904 | void MyFrame::OnClose(wxCloseEvent& event) | |
2905 | { | |
2906 | if ( event.CanVeto() && m_bFileNotSaved ) | |
2907 | { | |
2908 | if ( wxMessageBox("The file has not been saved... continue closing?", | |
2909 | "Please confirm", | |
2910 | wxICON_QUESTION | wxYES_NO) != wxYES ) | |
2911 | { | |
2912 | event.Veto(); | |
2913 | return; | |
2914 | } | |
2915 | } | |
2916 | ||
2917 | Destroy(); // you may also do: event.Skip(); | |
2918 | // since the default event handler does call Destroy(), too | |
2919 | } | |
2920 | @endcode | |
2921 | ||
2922 | The EVT_END_SESSION event is slightly different as it is sent by the system | |
2923 | when the user session is ending (e.g. because of log out or shutdown) and | |
2924 | so all windows are being forcefully closed. At least under MSW, after the | |
2925 | handler for this event is executed the program is simply killed by the | |
2926 | system. Because of this, the default handler for this event provided by | |
2927 | wxWidgets calls all the usual cleanup code (including wxApp::OnExit()) so | |
2928 | that it could still be executed and exit()s the process itself, without | |
2929 | waiting for being killed. If this behaviour is for some reason undesirable, | |
2930 | make sure that you define a handler for this event in your wxApp-derived | |
2931 | class and do not call @c event.Skip() in it (but be aware that the system | |
2932 | will still kill your application). | |
2933 | ||
2934 | @beginEventTable{wxCloseEvent} | |
2935 | @event{EVT_CLOSE(func)} | |
2936 | Process a close event, supplying the member function. | |
2937 | This event applies to wxFrame and wxDialog classes. | |
2938 | @event{EVT_QUERY_END_SESSION(func)} | |
2939 | Process a query end session event, supplying the member function. | |
2940 | This event can be handled in wxApp-derived class only. | |
2941 | @event{EVT_END_SESSION(func)} | |
2942 | Process an end session event, supplying the member function. | |
2943 | This event can be handled in wxApp-derived class only. | |
2944 | @endEventTable | |
2945 | ||
2946 | @library{wxcore} | |
2947 | @category{events} | |
2948 | ||
2949 | @see wxWindow::Close, @ref overview_windowdeletion | |
2950 | */ | |
2951 | class wxCloseEvent : public wxEvent | |
2952 | { | |
2953 | public: | |
2954 | /** | |
2955 | Constructor. | |
2956 | */ | |
2957 | wxCloseEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0); | |
2958 | ||
2959 | /** | |
2960 | Returns @true if you can veto a system shutdown or a window close event. | |
2961 | Vetoing a window close event is not possible if the calling code wishes to | |
2962 | force the application to exit, and so this function must be called to check this. | |
2963 | */ | |
2964 | bool CanVeto() const; | |
2965 | ||
2966 | /** | |
2967 | Returns @true if the user is just logging off or @false if the system is | |
2968 | shutting down. This method can only be called for end session and query end | |
2969 | session events, it doesn't make sense for close window event. | |
2970 | */ | |
2971 | bool GetLoggingOff() const; | |
2972 | ||
2973 | /** | |
2974 | Sets the 'can veto' flag. | |
2975 | */ | |
2976 | void SetCanVeto(bool canVeto); | |
2977 | ||
2978 | /** | |
2979 | Sets the 'logging off' flag. | |
2980 | */ | |
2981 | void SetLoggingOff(bool loggingOff); | |
2982 | ||
2983 | /** | |
2984 | Call this from your event handler to veto a system shutdown or to signal | |
2985 | to the calling application that a window close did not happen. | |
2986 | ||
2987 | You can only veto a shutdown if CanVeto() returns @true. | |
2988 | */ | |
2989 | void Veto(bool veto = true); | |
2990 | }; | |
2991 | ||
2992 | ||
2993 | ||
2994 | /** | |
2995 | @class wxMenuEvent | |
2996 | ||
2997 | This class is used for a variety of menu-related events. Note that | |
2998 | these do not include menu command events, which are | |
2999 | handled using wxCommandEvent objects. | |
3000 | ||
3001 | The default handler for @c wxEVT_MENU_HIGHLIGHT displays help | |
3002 | text in the first field of the status bar. | |
3003 | ||
3004 | @beginEventTable{wxMenuEvent} | |
3005 | @event{EVT_MENU_OPEN(func)} | |
3006 | A menu is about to be opened. On Windows, this is only sent once for each | |
3007 | navigation of the menubar (up until all menus have closed). | |
3008 | @event{EVT_MENU_CLOSE(func)} | |
3009 | A menu has been just closed. | |
3010 | @event{EVT_MENU_HIGHLIGHT(id, func)} | |
3011 | The menu item with the specified id has been highlighted: used to show | |
3012 | help prompts in the status bar by wxFrame | |
3013 | @event{EVT_MENU_HIGHLIGHT_ALL(func)} | |
3014 | A menu item has been highlighted, i.e. the currently selected menu item has changed. | |
3015 | @endEventTable | |
3016 | ||
3017 | @library{wxcore} | |
3018 | @category{events} | |
3019 | ||
3020 | @see wxCommandEvent, @ref overview_eventhandling | |
3021 | */ | |
3022 | class wxMenuEvent : public wxEvent | |
3023 | { | |
3024 | public: | |
3025 | /** | |
3026 | Constructor. | |
3027 | */ | |
3028 | wxMenuEvent(wxEventType id = wxEVT_NULL, int id = 0, wxMenu* menu = NULL); | |
3029 | ||
3030 | /** | |
3031 | Returns the menu which is being opened or closed. This method should only be | |
3032 | used with the @c OPEN and @c CLOSE events and even for them the | |
3033 | returned pointer may be @NULL in some ports. | |
3034 | */ | |
3035 | wxMenu* GetMenu() const; | |
3036 | ||
3037 | /** | |
3038 | Returns the menu identifier associated with the event. | |
3039 | This method should be only used with the @c HIGHLIGHT events. | |
3040 | */ | |
3041 | int GetMenuId() const; | |
3042 | ||
3043 | /** | |
3044 | Returns @true if the menu which is being opened or closed is a popup menu, | |
3045 | @false if it is a normal one. | |
3046 | ||
3047 | This method should only be used with the @c OPEN and @c CLOSE events. | |
3048 | */ | |
3049 | bool IsPopup() const; | |
3050 | }; | |
3051 | ||
3052 | /** | |
3053 | @class wxShowEvent | |
3054 | ||
3055 | An event being sent when the window is shown or hidden. | |
3056 | ||
3057 | Currently only wxMSW, wxGTK and wxOS2 generate such events. | |
3058 | ||
3059 | @onlyfor{wxmsw,wxgtk,wxos2} | |
3060 | ||
3061 | @beginEventTable{wxShowEvent} | |
3062 | @event{EVT_SHOW(func)} | |
3063 | Process a wxEVT_SHOW event. | |
3064 | @endEventTable | |
3065 | ||
3066 | @library{wxcore} | |
3067 | @category{events} | |
3068 | ||
3069 | @see @ref overview_eventhandling, wxWindow::Show, | |
3070 | wxWindow::IsShown | |
3071 | */ | |
3072 | ||
3073 | class wxShowEvent : public wxEvent | |
3074 | { | |
3075 | public: | |
3076 | /** | |
3077 | Constructor. | |
3078 | */ | |
3079 | wxShowEvent(int winid = 0, bool show = false); | |
3080 | ||
3081 | /** | |
3082 | Set whether the windows was shown or hidden. | |
3083 | */ | |
3084 | void SetShow(bool show); | |
3085 | ||
3086 | /** | |
3087 | Return @true if the window has been shown, @false if it has been | |
3088 | hidden. | |
3089 | */ | |
3090 | bool IsShown() const; | |
3091 | ||
3092 | /** | |
3093 | @deprecated This function is deprecated in favour of IsShown(). | |
3094 | */ | |
3095 | bool GetShow() const; | |
3096 | }; | |
3097 | ||
3098 | ||
3099 | ||
3100 | /** | |
3101 | @class wxIconizeEvent | |
3102 | ||
3103 | An event being sent when the frame is iconized (minimized) or restored. | |
3104 | ||
3105 | Currently only wxMSW and wxGTK generate such events. | |
3106 | ||
3107 | @onlyfor{wxmsw,wxgtk} | |
3108 | ||
3109 | @beginEventTable{wxIconizeEvent} | |
3110 | @event{EVT_ICONIZE(func)} | |
3111 | Process a wxEVT_ICONIZE event. | |
3112 | @endEventTable | |
3113 | ||
3114 | @library{wxcore} | |
3115 | @category{events} | |
3116 | ||
3117 | @see @ref overview_eventhandling, wxTopLevelWindow::Iconize, | |
3118 | wxTopLevelWindow::IsIconized | |
3119 | */ | |
3120 | class wxIconizeEvent : public wxEvent | |
3121 | { | |
3122 | public: | |
3123 | /** | |
3124 | Constructor. | |
3125 | */ | |
3126 | wxIconizeEvent(int id = 0, bool iconized = true); | |
3127 | ||
3128 | /** | |
3129 | Returns @true if the frame has been iconized, @false if it has been | |
3130 | restored. | |
3131 | */ | |
3132 | bool IsIconized() const; | |
3133 | ||
3134 | /** | |
3135 | @deprecated This function is deprecated in favour of IsIconized(). | |
3136 | */ | |
3137 | bool Iconized() const; | |
3138 | }; | |
3139 | ||
3140 | ||
3141 | ||
3142 | /** | |
3143 | @class wxMoveEvent | |
3144 | ||
3145 | A move event holds information about move change events. | |
3146 | ||
3147 | @beginEventTable{wxMoveEvent} | |
3148 | @event{EVT_MOVE(func)} | |
3149 | Process a wxEVT_MOVE event, which is generated when a window is moved. | |
3150 | @event{EVT_MOVE_START(func)} | |
3151 | Process a wxEVT_MOVE_START event, which is generated when the user starts | |
3152 | to move or size a window. wxMSW only. | |
3153 | @event{EVT_MOVE_END(func)} | |
3154 | Process a wxEVT_MOVE_END event, which is generated when the user stops | |
3155 | moving or sizing a window. wxMSW only. | |
3156 | @endEventTable | |
3157 | ||
3158 | @library{wxcore} | |
3159 | @category{events} | |
3160 | ||
3161 | @see wxPoint, @ref overview_eventhandling | |
3162 | */ | |
3163 | class wxMoveEvent : public wxEvent | |
3164 | { | |
3165 | public: | |
3166 | /** | |
3167 | Constructor. | |
3168 | */ | |
3169 | wxMoveEvent(const wxPoint& pt, int id = 0); | |
3170 | ||
3171 | /** | |
3172 | Returns the position of the window generating the move change event. | |
3173 | */ | |
3174 | wxPoint GetPosition() const; | |
3175 | }; | |
3176 | ||
3177 | ||
3178 | /** | |
3179 | @class wxSizeEvent | |
3180 | ||
3181 | A size event holds information about size change events. | |
3182 | ||
3183 | The EVT_SIZE handler function will be called when the window has been resized. | |
3184 | ||
3185 | You may wish to use this for frames to resize their child windows as appropriate. | |
3186 | ||
3187 | Note that the size passed is of the whole window: call wxWindow::GetClientSize | |
3188 | for the area which may be used by the application. | |
3189 | ||
3190 | When a window is resized, usually only a small part of the window is damaged | |
3191 | and you may only need to repaint that area. However, if your drawing depends on the | |
3192 | size of the window, you may need to clear the DC explicitly and repaint the whole window. | |
3193 | In which case, you may need to call wxWindow::Refresh to invalidate the entire window. | |
3194 | ||
3195 | @beginEventTable{wxSizeEvent} | |
3196 | @event{EVT_SIZE(func)} | |
3197 | Process a wxEVT_SIZE event. | |
3198 | @endEventTable | |
3199 | ||
3200 | @library{wxcore} | |
3201 | @category{events} | |
3202 | ||
3203 | @see wxSize, @ref overview_eventhandling | |
3204 | */ | |
3205 | class wxSizeEvent : public wxEvent | |
3206 | { | |
3207 | public: | |
3208 | /** | |
3209 | Constructor. | |
3210 | */ | |
3211 | wxSizeEvent(const wxSize& sz, int id = 0); | |
3212 | ||
3213 | /** | |
3214 | Returns the entire size of the window generating the size change event. | |
3215 | */ | |
3216 | wxSize GetSize() const; | |
3217 | }; | |
3218 | ||
3219 | ||
3220 | ||
3221 | /** | |
3222 | @class wxSetCursorEvent | |
3223 | ||
3224 | A wxSetCursorEvent is generated when the mouse cursor is about to be set as a | |
3225 | result of mouse motion. | |
3226 | ||
3227 | This event gives the application the chance to perform specific mouse cursor | |
3228 | processing based on the current position of the mouse within the window. | |
3229 | Use wxSetCursorEvent::SetCursor to specify the cursor you want to be displayed. | |
3230 | ||
3231 | @beginEventTable{wxSetCursorEvent} | |
3232 | @event{EVT_SET_CURSOR(func)} | |
3233 | Process a wxEVT_SET_CURSOR event. | |
3234 | @endEventTable | |
3235 | ||
3236 | @library{wxcore} | |
3237 | @category{events} | |
3238 | ||
3239 | @see ::wxSetCursor, wxWindow::wxSetCursor | |
3240 | */ | |
3241 | class wxSetCursorEvent : public wxEvent | |
3242 | { | |
3243 | public: | |
3244 | /** | |
3245 | Constructor, used by the library itself internally to initialize the event | |
3246 | object. | |
3247 | */ | |
3248 | wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0); | |
3249 | ||
3250 | /** | |
3251 | Returns a reference to the cursor specified by this event. | |
3252 | */ | |
3253 | const wxCursor& GetCursor() const; | |
3254 | ||
3255 | /** | |
3256 | Returns the X coordinate of the mouse in client coordinates. | |
3257 | */ | |
3258 | wxCoord GetX() const; | |
3259 | ||
3260 | /** | |
3261 | Returns the Y coordinate of the mouse in client coordinates. | |
3262 | */ | |
3263 | wxCoord GetY() const; | |
3264 | ||
3265 | /** | |
3266 | Returns @true if the cursor specified by this event is a valid cursor. | |
3267 | ||
3268 | @remarks You cannot specify wxNullCursor with this event, as it is not | |
3269 | considered a valid cursor. | |
3270 | */ | |
3271 | bool HasCursor() const; | |
3272 | ||
3273 | /** | |
3274 | Sets the cursor associated with this event. | |
3275 | */ | |
3276 | void SetCursor(const wxCursor& cursor); | |
3277 | }; | |
3278 | ||
3279 | ||
3280 | ||
3281 | // ============================================================================ | |
3282 | // Global functions/macros | |
3283 | // ============================================================================ | |
3284 | ||
3285 | /** @addtogroup group_funcmacro_events */ | |
3286 | //@{ | |
3287 | ||
3288 | /** | |
3289 | A special event type usually used to indicate that some wxEvent has yet | |
3290 | no type assigned. | |
3291 | */ | |
3292 | wxEventType wxEVT_NULL; | |
3293 | ||
3294 | /** | |
3295 | Each wxEvent-derived class has an @e event-type associated. | |
3296 | See the macro DEFINE_EVENT_TYPE() for more info. | |
3297 | ||
3298 | @see @ref overview_eventhandling_custom | |
3299 | */ | |
3300 | typedef int wxEventType; | |
3301 | ||
3302 | /** | |
3303 | Initializes a new event type using wxNewEventType(). | |
3304 | */ | |
3305 | #define DEFINE_EVENT_TYPE(name) const wxEventType name = wxNewEventType(); | |
3306 | ||
3307 | /** | |
3308 | Generates a new unique event type. | |
3309 | */ | |
3310 | wxEventType wxNewEventType(); | |
3311 | ||
3312 | /** | |
3313 | Use this macro inside a class declaration to declare a @e static event table | |
3314 | for that class. | |
3315 | ||
3316 | In the implementation file you'll need to use the BEGIN_EVENT_TABLE() | |
3317 | and the END_EVENT_TABLE() macros, plus some additional @c EVT_xxx macro | |
3318 | to capture events. | |
3319 | ||
3320 | @see @ref overview_eventhandling_eventtables | |
3321 | */ | |
3322 | #define DECLARE_EVENT_TABLE() | |
3323 | ||
3324 | /** | |
3325 | Use this macro in a source file to start listing @e static event handlers | |
3326 | for a specific class. | |
3327 | ||
3328 | Use END_EVENT_TABLE() to terminate the event-declaration block. | |
3329 | ||
3330 | @see @ref overview_eventhandling_eventtables | |
3331 | */ | |
3332 | #define BEGIN_EVENT_TABLE(theClass, baseClass) | |
3333 | ||
3334 | /** | |
3335 | Use this macro in a source file to end listing @e static event handlers | |
3336 | for a specific class. | |
3337 | ||
3338 | Use BEGIN_EVENT_TABLE() to start the event-declaration block. | |
3339 | ||
3340 | @see @ref overview_eventhandling_eventtables | |
3341 | */ | |
3342 | #define END_EVENT_TABLE() | |
3343 | ||
3344 | /** | |
3345 | In a GUI application, this function posts @a event to the specified @e dest | |
3346 | object using wxEvtHandler::AddPendingEvent(). | |
3347 | ||
3348 | Otherwise, it dispatches @a event immediately using | |
3349 | wxEvtHandler::ProcessEvent(). See the respective documentation for details | |
3350 | (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent() | |
3351 | this function is not thread-safe for event objects having wxString fields, | |
3352 | use wxQueueEvent() instead. | |
3353 | ||
3354 | @header{wx/event.h} | |
3355 | */ | |
3356 | void wxPostEvent(wxEvtHandler* dest, const wxEvent& event); | |
3357 | ||
3358 | /** | |
3359 | Queue an event for processing on the given object. | |
3360 | ||
3361 | This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation | |
3362 | for more details. | |
3363 | ||
3364 | @header{wx/event.h} | |
3365 | ||
3366 | @param dest | |
3367 | The object to queue the event on, can't be @c NULL. | |
3368 | @param event | |
3369 | The heap-allocated and non-@c NULL event to queue, the function takes | |
3370 | ownership of it. | |
3371 | */ | |
3372 | void wxQueueEvent(wxEvtHandler* dest, wxEvent *event); | |
3373 | ||
3374 | //@} | |
3375 |