Aw event set

From ActiveWiki
Jump to: navigation, search


Minimum requirements
Added in version 2.1
SDKbuild 13


int aw_event_set (AW_EVENT_ATTRIBUTE e, void (*handler) (void))

Description

Subscribes to an event and installs a handler function.

Callback

None (returns immediately)

Notes

This method is global, in the sense that it applies to all active instances in the bot. It is almost equivalent to calling aw_instance_event_set with the same event handler, for each of the instances. The difference being that the global setting is remembered and will be applied to instances that are created further on.

Once an instance has subscribed to an event, it will begin receiving notifications as that event occurs. Notifications occur in the form of calls to the event handler function that was supplied.

When an event has been subscribed to using this method, all instances in a multi-instance application may receive the event. To determine which instance is receiving a particular event, call aw_instance from within your event handler.

Subscribing to events that are associated with worlds (i.e. AW_EVENT_AVATAR_CLICK) might lead to the event mask being changed. If an instance is connected to a world and the event mask changes then it will be sent to the world.

To unsubscribe from a particular event, call this method with handler set to NULL.

For more information on events and event handlers, see Events.

Arguments

e
Event (defined in Aw.h)
handler
Handler.

Argument attributes

None

Return values

RC_SUCCESS
RC_NOT_INITIALIZED
RC_INVALID_ATTRIBUTE
Not an event.

Returned attributes

None

Usage

void avatar_add (void)
{
  printf ("%s has entered the scene\n", aw_string (AW_AVATAR_NAME));
}

aw_event_set (AW_EVENT_AVATAR_ADD, avatar_add);

See also