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