need a window identifier, since normally you are only interested in the current\r
window's size events.\r
\r
-The EVT_BUTTON macro demonstrates that the originating event does not have to\r
+The @c EVT_BUTTON macro demonstrates that the originating event does not have to\r
come from the window class implementing the event table -- if the event source\r
is a button within a panel within a frame, this will still work, because event\r
tables are searched up through the hierarchy of windows for the command events.\r
wxEvtHandler (usually indirectly via wxWindow). See the declaration of MyFrame\r
in the previous section. However the similarities end here and both the syntax\r
and the possibilities of handling events in this way are rather different.\r
- \r
+\r
Let us start by looking at the syntax: the first obvious difference is that you\r
-need not use @c DECLARE_EVENT_TABLE() nor @c BEGIN_EVENT_TABLE and the\r
+need not use DECLARE_EVENT_TABLE() nor BEGIN_EVENT_TABLE() and the\r
associated macros. Instead, in any place in your code, but usually in\r
the code of the class defining the handler itself (and definitely not in the\r
global scope as with the event tables), call its Connect() method like this:\r
<li value="5">\r
The event is passed to the next event handler, if any, in the event handler\r
chain, i.e., the steps (1) to (4) are done for it. This chain can be formed\r
- using wxEvtHandler::SetNextHandler() or wxWindow::PushEventHandler() but\r
- usually there is no next event handler and chaining event handlers using\r
- these functions is much less useful now that Connect() exists so this step\r
- will almost never do anything.\r
+ using wxEvtHandler::SetNextHandler():\r
+ @image html overview_eventhandling_chain.png\r
+ (referring to the image, if @c A->ProcessEvent is called and it doesn't handle\r
+ the event, @c B->ProcessEvent will be called and so on...).\r
+ In the case of wxWindow you can build a stack (implemented using wxEvtHandler\r
+ double-linked list) using wxWindow::PushEventHandler():\r
+ @image html overview_eventhandling_winstack.png\r
+ (referring to the image, if @c W->ProcessEvent is called, it immediately calls\r
+ @c A->ProcessEvent; if nor @c A nor @c B handle the event, then the wxWindow\r
+ itself is used - i.e. the dynamically connected event handlers and static\r
+ event table entries of wxWindow are looked as the last possibility, after\r
+ all pushed event handlers were tested).\r
+ Note however that usually there are no wxEvtHandler chains nor wxWindows stacks\r
+ so this step will usually do anything.\r
</li>\r
\r
<li value="6">\r
\r
<li value="7">\r
Finally, i.e., if the event is still not processed, the wxApp object itself\r
- gets a last chance to process it.\r
+ (which derives from wxEvtHandler) gets a last chance to process it.\r
</li>\r
</ol>\r
\r
for other purposes). In fact, identifiers do not need to be unique\r
across your entire application as long they are unique within the\r
particular context you're interested in, such as a frame and its children. You\r
-may use the @c wxID_OK identifier, for example, on any number of dialogs so\r
-long as you don't have several within the same dialog.\r
+may use the @c wxID_OK identifier, for example, on any number of dialogs\r
+as long as you don't have several within the same dialog.\r
\r
If you pass @c wxID_ANY to a window constructor, an identifier will be\r
generated for you automatically by wxWidgets. This is useful when you don't\r
care about the exact identifier either because you're not going to process the\r
-events from the control being created at all or because you process the events\r
+events from the control being created or because you process the events\r
from all controls in one place (in which case you should specify @c wxID_ANY\r
in the event table or wxEvtHandler::Connect call\r
-as well. The automatically generated identifiers are always negative and so\r
+as well). The automatically generated identifiers are always negative and so\r
will never conflict with the user-specified identifiers which must be always\r
positive.\r
\r
See @ref page_stdevtid for the list of standard identifiers available.\r
You can use wxID_HIGHEST to determine the number above which it is safe to\r
define your own identifiers. Or, you can use identifiers below wxID_LOWEST.\r
-Finally, you can allocate identifiers dynamically using wxNewId() function to.\r
+Finally, you can allocate identifiers dynamically using wxNewId() function too.\r
If you use wxNewId() consistently in your application, you can be sure that\r
-the your identifiers don't conflict accidentally.\r
+your identifiers don't conflict accidentally.\r
\r
\r
@section overview_eventhandling_custom Custom Event Summary\r
\r
@subsection overview_eventhandling_custom_general General approach\r
\r
-Since version 2.2.x of wxWidgets, each event type is identified by ID which\r
-is given to the event type @e at runtime which makes it possible to add\r
+Since version 2.2.x of wxWidgets, each event type is identified by an ID\r
+given to the event type @e at runtime that makes it possible to add\r
new event types to the library or application without risking ID clashes\r
(two different event types mistakingly getting the same event ID).\r
This event type ID is stored in a struct of type <b>const wxEventType</b>.\r
\r
In order to define a new event type, there are principally two choices.\r
-One is to define a entirely new event class (typically deriving from\r
+One is to define an entirely new event class (typically deriving from\r
wxEvent or wxCommandEvent).\r
\r
-The other is to use the existing event classes and give them an new event\r
-type. You'll have to define and declare a new event type using either way,\r
-and this is done using the following macros:\r
+The other is to use the existing event classes and give them a new event\r
+type. You'll have to define and declare a new event type either way\r
+using the following macros:\r
\r
@code\r
// in the header of the source file\r
\r
@subsection overview_eventhandling_custom_existing Using Existing Event Classes\r
\r
-If you just want to use a wxCommandEvent with a new event type, you can then use\r
+If you just want to use a wxCommandEvent with a new event type, use\r
one of the generic event table macros listed below, without having to define a\r
new event class yourself. This also has the advantage that you won't have to define a\r
new wxEvent::Clone() method for posting events between threads etc.\r
@ref group_class_events "event classes group page".\r
\r
\r
-@todo for all controls state clearly when calling a member function results in an\r
- event being generated and when it doesn't (possibly updating also the\r
- 'Events generated by the user vs programmatically generated events' paragraph\r
- of the 'Event handling overview' with the list of the functions which break\r
- that rule).\r
+@todo For all controls, state clearly when calling a member function results in\r
+ an event being generated and when it doesn't (possibly updating also the\r
+ 'Events generated by the user versus programmatically-generated events'\r
+ paragraph of the 'Event Handling Overview' with the list of the functions\r
+ that break the rule).\r
\r
*/\r
\r
projects / wxWidgets.git / blobdiff