## Events Element

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.

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.

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.

### Implementing API Hooks for Events

At the API level, events may be propagated several ways:

- Calls to existing virtual functions (e.g. HandleEventL, SizeChanged, etc.); where a subclass must override the function in order to see the event.
- 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).
- Calls through a container’s command handler, which dispatches events to components
- Calls to abstract functions on helper classes, which must be implemented (for example, CCoeScreenDeviceChangeDefaultHandler or the active object used by progress note dialogs).

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 macros. For example, "GenerateVirtualMethodOverrideForEventHandler".

### Generating User Handler Methods

At the user handler level:

- 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.
- 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.
- 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.

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.

### Handling Event Dispatch

An event handler component must define the attribute event-handler-target 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.

A component specifying the event-handler-target attribute must define a “className” property. It must also handle various phases, as described below. These are already in common use:

- BaseClasses
- ClassMethods
- Initialize
- Destroy
- MainSystemIncludes
- MainUserIncludes
- HeaderIncludes
- ForwardDeclarations

Additionally, for event-specific code, use:

- OverriddenMethods
- UserHandlers
- BaseClassList
- EventIncludes
- EventDocs

In a script, the event handler component’s className property is exposed to script and sourcegen as handlerClassName.