| author | fturovic <frank.turovich@nokia.com> |
| Tue, 27 Jul 2010 15:28:19 -0500 | |
| changeset 1704 | 24ac5a5cf80c |
| parent 0 | fb279309251b |
| permissions | -rw-r--r-- |
|
1704
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
2 |
<html> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
3 |
<head> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
4 |
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
5 |
<meta http-equiv="Content-Style-Type" content="text/css" /> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
6 |
<title>Events Element</title> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
7 |
<link rel="StyleSheet" href="../../../book.css" type="text/css"/> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
8 |
</head> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
9 |
<body bgcolor="#FFFFFF"> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
10 |
<h2>Events Element</h2> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
11 |
<p>Events can be associated with a component. Components inherit the events of their base components. Events are named notifications or hooks to which code can be attached. Events are propagated through code, so a class must be implemented in order to handle an event. Because there are always classes associated with the application and with each UI design, these are good candidates. Also inner classes or other standalone classes can be added where needed.</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
12 |
<p>The Events element defines related events via the <event> element. A list of events can be defined for a component. The set of available events, and default event, may be overridden by code or a script. See the com.nokia.sdt.datamodel.adapter.IComponentEventInfo interface for more information.</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
13 |
<p>The Event element defines characteristics of the event and primarily the pattern used for the default event handler function name. The source generated for events involves implementing integration with the API and creating a user handler. All of these are conditionally generated only when the event is bound. When the event is unbound, however, any code that may have been edited by the user (read: non-owned methods) are not deleted.</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
14 |
<h3>Implementing API Hooks for Events</h3> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
15 |
<p>At the API level, events may be propagated several ways:</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
16 |
<ul type="disc"> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
17 |
<li>Calls to existing virtual functions (e.g. HandleEventL, SizeChanged, etc.); where a subclass must override the function in order to see the event.</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
18 |
<li>Calls to “M” classes, interfaces implemented on other classes, whose instances are passed to registration functions (for example, the SetCallback() function of a progress note).</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
19 |
<li>Calls through a container’s command handler, which dispatches events to components</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
20 |
<li>Calls to abstract functions on helper classes, which must be implemented (for example, CCoeScreenDeviceChangeDefaultHandler or the active object used by progress note dialogs).</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
21 |
</ul> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
22 |
<p>Code having to do with API-level event handling is added to owned regions of classes and the main source file. Thus, when an event is unbound, all this code disappears. See the CommonMacros.inc file for helpful <a href="cc_source_generation.htm#macros">macros</a>. For example, "GenerateVirtualMethodOverrideForEventHandler".</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
23 |
<h3>Generating User Handler Methods</h3> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
24 |
<p>At the user handler level:</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
25 |
<ul> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
26 |
<li>Each event handler has a user-editable method associated with it. This allows user code to be isolated syntactically from generated code so it can be edited. The event binding’s display value is used as the pattern for the method name, which sourcegen associates with a given class and type to provide an actual signature.</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
27 |
<li>By default, this display value is generated to be relatively unique. The user can choose the display value and may elect to choose the same display value for multiple event handlers in multiple components, although this will likely resolve to the same method if the event type and the event-handling component are the same.</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
28 |
<li>Each event handler must be declared (in terms of arguments, leaving behavior, and return value) so that the handler method can communicate with generated code. Since handler sharing is allowed, then arguments must specify which component (instance variable) is the target of the event, if it is integral to handling the event properly.</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
29 |
</ul> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
30 |
<p>Code having to do with user-level event handlers are not owned. They are stranded when an event binding changes or is deleted. See the CommonMacros.inc file and the "GenerateUserEventHandlerFunction" macro to assist in creating user handlers.</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
31 |
<h3>Handling Event Dispatch</h3> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
32 |
<p>An event handler component must define the attribute <strong>event-handler-target</strong> in the attributes element. Such a component is usually a container and defines a class. However, a component may choose to handle its own events without specifying this attribute.</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
33 |
<p>A component specifying the <strong>event-handler-target</strong> attribute must define a “className” property. It must also handle various phases, as described below. These are already in common use:</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
34 |
<ul> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
35 |
<li>BaseClasses</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
36 |
<li>ClassMethods</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
37 |
<li>Initialize</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
38 |
<li>Destroy</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
39 |
<li>MainSystemIncludes</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
40 |
<li>MainUserIncludes</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
41 |
<li>HeaderIncludes</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
42 |
<li>ForwardDeclarations</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
43 |
</ul> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
44 |
<p>Additionally, for event-specific code, use:</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
45 |
<ul> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
46 |
<li>OverriddenMethods</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
47 |
<li>UserHandlers</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
48 |
<li>BaseClassList</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
49 |
<li>EventIncludes</li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
50 |
<li>EventDocs </li> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
51 |
</ul> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
52 |
<p>In a script, the event handler component’s className property is exposed to script and sourcegen as <span class="code">handlerClassName</span>.</p> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
53 |
<div id="footer">Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. <br>License: <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a></div> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
54 |
|
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
55 |
</body> |
|
24ac5a5cf80c
updated copyright dates and fixed some css issues
fturovic <frank.turovich@nokia.com>
parents:
0
diff
changeset
|
56 |
</html> |