event: Events

The forge.event namespace allows the app to listen for events of interest.

These may be triggered multiple times (or potentially not at all) depending on the situation.

API

forge.event.menuPressed.addListener(callback, error)

Android

Triggered when the menu button is pressed on an Android device.

Parameters:
callback
function(contact) callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

forge.event.backPressed.addListener(callback, error)

Android

Triggered when the back button is pressed on an Android device.

Parameters:
callback
function(closeApplication, pauseApplication) callback invoked when back button is pressed. closeApplication is a function which, if called, will forcibly shut down the application. pauseApplication is a function which, if called, will send the app into the background instead.
error
function(content) called with details of any error which may occur

Note: closeApplication is a legacy callback which is only retained for compatibility purposes. If you are developing a new app it is highly recommended that you use the pauseApplication callback.

forge.event.backPressed.preventDefault(callback, error)

Android

Prevents the default action when the back button is pressed from the point this is called onwards, allowing the app to handle the event itself using forge.event.backPressed.addListener.

Parameters:
callback
function() callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

forge.event.orientationChange.addListener(callback, error)

iOS, Android

Triggered when the device is rotated, use forge.is.orientation.portrait() and forge.is.orientation.landscape() to determine orientation.

Parameters:
callback
function() callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

forge.event.connectionStateChange.addListener(callback, error)

iOS, Android

Triggered when the device connection state changes, use forge.is.connection.connected() and forge.is.connection.wifi() to test new connection state.

Parameters:
callback
function() callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

Note: This event will also be fired once during app startup, as soon as we determine the connection status.

forge.event.messagePushed.addListener(callback, error)

iOS, Android

Triggered when a push notification is received both while the application is running or if the application is launched via that notification.

Parameters:
callback
function(data) callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

Currently available as part of our integration with Parse.

forge.event.appPaused.addListener(callback, error)

iOS, Android

Triggered when the app loses focus and moves into the background.

Parameters:
callback
function(data) callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

Note: You should also not assume that an app that is paused will be resumed, the app may be killed at this point by the user or device without ever being resumed.

What can be executed in the callback varies by platform:

  • Android: Any javascript can be run, but timers may not be fired until the app is resumed, this prevents unnecessary battery usage by the app.
  • iOS: A short amount of time is given for execution, it is generally best to assume that callbacks and timers may not fire until the app is resumed.

forge.event.appResumed.addListener(callback, error)

iOS, Android

Triggered when the app is resumed from a previous paused state.

Parameters:
callback
function(data) callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur

forge.event.statusBarTapped.addListener(callback, error)

iOS

Triggered when the user taps on the status bar. Tapping the status bar will also scroll the webview to the top.

Parameters:
callback
function(data) callback to be invoked when no errors occur
error
function(content) called with details of any error which may occur