Handling native events

There are two distinct types of events in modules:

  • JavaScript events which can be triggered from native code at any point, used for situations that aren't a direct response to an API method call.
  • Native events which are points in an application's execution that modules can hook into and execute their own code. For example modules can execute native code on application start, without having to use any JavaScript.

Quite frequently you'll want to handle a native event and trigger a corresponding JavaScript event. This section of the module docs will discuss the second type of event, those which are triggered by the device. If you're interested in the first type of event described, see Triggering JavaScript events.

Android

To listen for native events in Android an EventListener class must be added to your module's package. For example, io.trigger.forge.android.modules.alert.EventListener. This class should extend the ForgeEventListener class and implement any of the methods it wants to listen for. See the Javadoc for ForgeEventListener for the list of methods available for override as well as their meaning.

The example EventListener from the inspector project looks like:

public class EventListener extends ForgeEventListener {
    @Override
    public void onRestart() {
        ForgeApp.event("alert.resume", null);
    }
}
  • @Override on the method ensures the method exists in ForgeEventListener and is an available event.
  • If you want to prevent subsequent event listeners from receiving an event, you should return a non-null value. For example, if a key press event is handled by a module it can return true and prevent other modules from seeing the event.

iOS

To listen for native events in iOS, a class called <module>_EventListener must be created where <module> is your module name. This class should extend ForgeEventListener and implement any of the methods it wants to listen for. See the appledocs for ForgeEventListener for the list of methods available for override as well as their meaning.

The example EventListener from the inspector project looks like:

@interface alert_EventListener : ForgeEventListener

@end

@implementation alert_EventListener

+ (void)applicationWillEnterForeground:(UIApplication *)application {
    [[ForgeApp sharedApp] event:@"alert.resume" withParam:nil];
}

@end
  • If you want to prevent subsequent event listeners from receiving an event, you should return a non-nil value. For example, if a key press event is handled by a module it can return YES and prevent other modules from seeing the event.