Navigator events

Event codes for navigator service events.

Synopsis:

#include <bps/navigator.h>

enum {
      NAVIGATOR_INVOKE = 0x01   
      NAVIGATOR_EXIT = 0x02   
      NAVIGATOR_WINDOW_STATE = 0x03   
      NAVIGATOR_SWIPE_DOWN = 0x04   
      NAVIGATOR_SWIPE_START = 0x05   
      NAVIGATOR_LOW_MEMORY = 0x06   
      NAVIGATOR_ORIENTATION_CHECK = 0x07   
      NAVIGATOR_ORIENTATION = 0x08   
      NAVIGATOR_BACK = 0x09   
      NAVIGATOR_WINDOW_ACTIVE = 0x0a   
      NAVIGATOR_WINDOW_INACTIVE = 0x0b   
      NAVIGATOR_ORIENTATION_DONE = 0x0c   
      NAVIGATOR_ORIENTATION_RESULT = 0x0d   
      NAVIGATOR_WINDOW_LOCK = 0x0e   
      NAVIGATOR_WINDOW_UNLOCK = 0x0f   
      NAVIGATOR_INVOKE_TARGET = 0x10   
      NAVIGATOR_INVOKE_QUERY_RESULT = 0x11   
      NAVIGATOR_INVOKE_VIEWER = 0x12   
      NAVIGATOR_INVOKE_TARGET_RESULT = 0x13   
      NAVIGATOR_INVOKE_VIEWER_RESULT = 0x14   
      NAVIGATOR_INVOKE_VIEWER_RELAY = 0x15   
      NAVIGATOR_INVOKE_VIEWER_STOPPED = 0x16   
      NAVIGATOR_KEYBOARD_STATE = 0x17   
      NAVIGATOR_KEYBOARD_POSITION = 0x18   
      NAVIGATOR_INVOKE_VIEWER_RELAY_RESULT = 0x19   
      NAVIGATOR_DEVICE_LOCK_STATE = 0x1a   
      NAVIGATOR_WINDOW_COVER = 0x1b   
      NAVIGATOR_WINDOW_COVER_ENTER = 0x1c   
      NAVIGATOR_WINDOW_COVER_EXIT = 0x1d   
      NAVIGATOR_CARD_PEEK_STARTED = 0x1e   
      NAVIGATOR_CARD_PEEK_STOPPED = 0x1f   
      NAVIGATOR_CARD_RESIZE = 0x20   
      NAVIGATOR_CHILD_CARD_CLOSED = 0x21   
      NAVIGATOR_CARD_CLOSED = 0x22   
      NAVIGATOR_INVOKE_GET_FILTERS_RESULT = 0x23   
      NAVIGATOR_APP_STATE = 0x24   
      NAVIGATOR_INVOKE_SET_FILTERS_RESULT = 0x25   
      NAVIGATOR_PEEK_STARTED = 0x26   
      NAVIGATOR_PEEK_STOPPED = 0x27   
      NAVIGATOR_CARD_READY_CHECK = 0x28   
      NAVIGATOR_POOLED = 0x29   
      NAVIGATOR_ORIENTATION_SIZE = 0x2a   
      NAVIGATOR_INVOKE_LIST_CURSOR_MOVED = 0x2b   
      NAVIGATOR_INVOKE_LIST_ITEM_SELECTED = 0x2c   
      NAVIGATOR_INVOKE_TIMER_REGISTRATION = 0x2d   
      NAVIGATOR_SYSKEY_PRESS = 0x2e   
      NAVIGATOR_OTHER = 0xff   
};

Since:

BlackBerry 10.0.0

Data:

NAVIGATOR_INVOKE: Indicates that the application is a registered URL handler, and the navigator is invoking a URL type on the application.; For example, a web browser might need to handle an http invoke request from another application, and load the website that is associated with the request.

NAVIGATOR_EXIT: Indicates that the user has quit the application, the device is rebooting, or some other event has occurred that results in the application needing to terminate.; After this type of event is received, the application has a short amount of time (3 seconds) to terminate itself. If the application has not terminated after this time has elapsed, the navigator terminates the application.

NAVIGATOR_WINDOW_STATE: Indicates that the state of the application window has changed.; For example, the application window might have changed to full screen from a thumbnail. The navigator_window_state_t enumeration defines the possible states that an application window can be in.

NAVIGATOR_SWIPE_DOWN: Indicates that the user has performed a downward swipe gesture from the top of the device screen.; By convention, this gesture displays a menu.

NAVIGATOR_SWIPE_START: Indicates that the user has started a swipe gesture.; This type of event is generated if the application has requested swipe start events by calling navigator_request_swipe_start(). For example, if an application calls navigator_request_swipe_start() and the user performs a downward swipe gesture from the top of the device screen, the application receives a NAVIGATOR_SWIPE_START event followed by a series of touch events. This functionality can be useful if the application wants to respond more appropriately to swipe gestures (for example, by displaying the menu in sync with the user's downward swipe gesture).

NAVIGATOR_LOW_MEMORY: Indicates that the device is low on memory.; To prevent degraded performance and a potentially poor user experience, an application should respond to this event by freeing any memory that it isn't using.

NAVIGATOR_ORIENTATION_CHECK: Indicates that the device has rotated.; An application should respond to this event by calling navigator_orientation_check_response() and indicating whether it intends to rotate along with the device rotation. If the application indicates that it intends to rotate, the navigator sends a follow-up NAVIGATOR_ORIENTATION event when it is time for the application to resize its screen.

NAVIGATOR_ORIENTATION: Indicates that an application should resize its screen in response to the rotation of the device.; This event is generated if the application has called navigator_orientation_check_response() and indicated that it intends to rotate. After the application is finished resizing its screen, the application should call navigator_done_orientation() to let the navigator know that the application is finished rotating.

NAVIGATOR_BACK: Indicates that the user has performed a swipe gesture from the bottom left of the device screen towards the top right.

NAVIGATOR_WINDOW_ACTIVE: Indicates that the application window has become active (for example, if the application window changes to full screen from being hidden).

NAVIGATOR_WINDOW_INACTIVE: Indicates that the application window has become inactive (for example, if the application window changes to hidden from being full screen).

NAVIGATOR_ORIENTATION_DONE: Indicates that the device has finished rotating.

NAVIGATOR_ORIENTATION_RESULT: Indicates that a request to change the orientation with navigator_set_orientation() has completed.

NAVIGATOR_WINDOW_LOCK: Indicates that the corporate or enterprise application is locked.; When locked, the window changes to a lock icon and cannot be used. To use the window again, the user must unlock it by touching the window and then typing a password.

NAVIGATOR_WINDOW_UNLOCK: Indicates that the corporate or enterprise application is unlocked.; When an application is first launched, it is considered unlocked. No message is sent when the application starts.

NAVIGATOR_INVOKE_TARGET: Indicates an invocation for the target was received.; The application should retrieve the invocation properties through the navigator_invoke_event_get_invocation() function.

NAVIGATOR_INVOKE_QUERY_RESULT: Indicates an invocation query result was received.; The application should retrieve the invocation query result actions through the navigator_invoke_event_get_query_result_action() and navigator_invoke_event_get_query_result_action_count() functions.

NAVIGATOR_INVOKE_VIEWER: Indicates a viewer invocation was received.; The application should retrieve the viewer invocation through the navigator_invoke_event_get_viewer() function.

NAVIGATOR_INVOKE_TARGET_RESULT: Indicates an invocation target response was received.; The application should retrieve the invocation ID through the navigator_event_get_id() function and the error through the navigator_event_get_err() function.

NAVIGATOR_INVOKE_VIEWER_RESULT: Indicates an invocation viewer response was received.; The application should retrieve the invocation viewer ID through the navigator_event_get_id() function and the error through the navigator_event_get_err() function.

NAVIGATOR_INVOKE_VIEWER_RELAY: If the current process is the parent application of the viewer it indicates that the request message from the viewer was received.; If the current process is the viewer it indicates that the request message from the parent application was received. To retrieve the message name use the navigator_invoke_event_get_viewer_relay_message_name() function. To retrieve the data use the navigator_invoke_event_get_viewer_relay_data() function. To retrieve the window ID of the viewer use the navigator_invoke_event_get_viewer_relay_window_id() function.

NAVIGATOR_INVOKE_VIEWER_STOPPED: Indicates that the invocation viewer has terminated.; To retrieve the window ID use the navigator_invoke_event_get_window_id() function.

NAVIGATOR_KEYBOARD_STATE: Indicates that the the keyboard has changed state.; The navigator_keyboard_state_t enumeration defines the possible states that the keyboard can be in.

NAVIGATOR_KEYBOARD_POSITION: Indicates that the keyboard has changed position.

NAVIGATOR_INVOKE_VIEWER_RELAY_RESULT

If the current process is the parent application of the viewer it indicates that the response message from the viewer was received.

If the current process is the viewer it indicates that the response message from the parent application was received. In case of an error in delivering the request message to the peer the event contains an error message. To retrieve the error message use navigator_event_get_err() function. If the error message is NULL in the event the following functions should be used to retrieve the message name, the data and the window ID of the viewer:

NAVIGATOR_DEVICE_LOCK_STATE: Indicates that the device has been locked or unlocked.; navigator_event_get_device_lock_state()

NAVIGATOR_WINDOW_COVER: Provide details about the window cover.; Occurs on application startup.

NAVIGATOR_WINDOW_COVER_ENTER: Occurs when navigator displays the application's window cover.

NAVIGATOR_WINDOW_COVER_EXIT: Occurs when the navigator removes the application's window cover.

NAVIGATOR_CARD_PEEK_STARTED: Indicates that the card peek action has started.; Card peeking is the ability to see behind a card using a gesture to drag the card off screen to expose the card's parent or root.

NAVIGATOR_CARD_PEEK_STOPPED: Indicates that the card peek action has stopped.; Call the navigator_event_get_card_peek_stopped_swipe_away function upon receiving this event to determine if the peeking action was stopped due to a "swipe away" gesture or not.

NAVIGATOR_CARD_RESIZE

Indicates that the card application should resize its buffer and call the navigator_card_resized() function when finished.

When this event is triggered, the Navigator delivers a message to the card containing the resize data, which the card extracts and uses to execute the transformation.

The members contained in the message and the functions the card application must use to retrive them are as follows:

Event ID: the ID of the message to identify the event (navigator_event_get_id())
Width: the new width of the card (navigator_event_get_card_width())
Height: the new height of the card (navigator_event_get_card_height())
Device orientation type: the orientation of the device (either portrait or landscape) (navigator_event_get_card_orientation())
Card edge: the orientation of the card relative to the device (navigator_event_get_card_edge())

NAVIGATOR_CHILD_CARD_CLOSED

Indicates to the parent of a card application that the child card has been closed.

When this event is triggered, the Navigator delivers a message to the parent of the closed child card containing information about the closure as well as any response data sent by the card (if the card requested the closure).

The members contained in the message and the functions the parent application must use to retrieve them are as follows:

Reason: the reason why the child card closed (navigator_event_get_card_closed_reason())
Data type: the MIME type of the data sent by the child card (navigator_event_get_card_closed_data_type())
Data: the data sent by the child card (navigator_event_get_card_closed_data())

NAVIGATOR_CARD_CLOSED: Indicates that the card has been closed and is being pooled.; Pooling is a feature that allows a card of a certain type to be opened multiple times in quick sucession, such as when viewing a series of emails one after the other. This event informs the card that it should clean-up its state and listen for further invocations. When a card receives the event it should assume that its child card is also closed. A card may retrieve the reason for its closure by calling the navigator_event_get_card_closed_reason() function.

NAVIGATOR_INVOKE_GET_FILTERS_RESULT: Indicates a get invoke target filters result was received.; The application should retrieve the get invoke target filters result filters through navigator_invoke_get_filters() function.

NAVIGATOR_APP_STATE: Occurs when the Adaptive Partition Scheduler will move the application to a different partition (background, foreground, or stopped).

NAVIGATOR_INVOKE_SET_FILTERS_RESULT

NAVIGATOR_PEEK_STARTED: Indicates that the peek action of this card has started.; Card peeking is the ability to see behind a card using a gesture to drag the card off screen to expose the card's parent or root.

NAVIGATOR_PEEK_STOPPED: Indicates that the peek action of this card has stopped.; Call the navigator_event_get_peek_stopped_swipe_away function upon receiving this event to determine if the peeking action was stopped due to a "swipe away" gesture or not.

NAVIGATOR_CARD_READY_CHECK: Indicates that the Navigator is ready to display the card's window.; Call navigator_card_send_card_ready() to notify the navigator when the card is ready to be shown.

NAVIGATOR_POOLED

Indicates that the navigator would like to pool your application or card.

Pooled means that the application is still running as a process but its window is not visible to the user.

If an application would like to be pooled it must reply to this message by calling navigator_pooled_response() within 1 second. If there is no response within 1 second, the application will be terminated. When pooled, an application is also put into the stopped partition after 10 seconds. An application that supports pooling is responsible for closing files, connections and resources and is also responsible for restoring them when the the application gets the active signal again. This means that an application has 10 seconds to prepare itself to sit dormant in the pool.

The application decides if it wants to return to the last state it was in or to reset the state to something else. These decisions should be made when the application receives the NAVIGATOR_POOLED event so that it's ready to be displayed when it pulled from the pool later. Trying to change scenes/render new graphics, etc., when the application is made active again may result in flicker or stale data when the window is made visible again. So it's best to put the application in its "restore" state when it goes into the pool.

If the application wants to be pooled, extract the ID from this event with navigator_event_get_id() and then call navigator_pooled_response() with that ID.

NAVIGATOR_ORIENTATION_SIZE

Informs the app what the rotated window's width and height will be.

This event will occur after a NAVIGATOR_ORIENTATION_CHECK event and before a NAVIGATOR_ORIENTATION event. It will indicate what the window size will be after the rotation is completed. For the vast majority of apps, the width and height will simply be swapped from the current width and height.

Use navigator_event_get_orientation_size_width() and navigator_event_get_orientation_size_height() to extract the width and height from the event.

NAVIGATOR_INVOKE_LIST_CURSOR_MOVED

Informs the app that the cursor of an invoke list is being moved.

This event will occur after a NAVIGATOR_CARD_PEEK_STARTED event and before a NAVIGATOR_CARD_PEEK_STOPPED or NAVIGATOR_INVOKE_LIST_ITEM_SELECTED event. It will indicate that the application should select the next available item in the invoke list as a candidate for the next invoke request.

Use navigator_invoke_get_list_id() to extract the id of the list that this request corresponds to, and navigator_invoke_get_list_cursor_direction() to extract the direction of movement.

NAVIGATOR_INVOKE_LIST_ITEM_SELECTED

Informs the app that an invoke list item has been selected.

This event may occur after a NAVIGATOR_CARD_PEEK_STARTED event and before a NAVIGATOR_CARD_PEEK_STOPPED event. It will indicate that the application should invoke the currently selected invoke item belonging to the list in question based on previous NAVIGATOR_INVOKE_LIST_CURSOR_MOVED events. In these instances, navigator_invoke_get_list_item_selection() returns NAVIGATOR_INVOKE_LIST_CURSOR_DIRECTION_UNSPECIFIED.

This event may also occur outside of peeking, in which case navigator_invoke_get_list_item_selection() returns the item that should be selected.

Use navigator_invoke_get_list_id() to extract the list ID of the list that this request corresponds to, and navigator_invoke_get_list_item_selection() to extract the direction of movement.

NAVIGATOR_INVOKE_TIMER_REGISTRATION

Indicates a timer registration result was received.

The application should retrieve the registration action through the navigator_invoke_timer_registration_get_action() function and the action error code through the navigator_event_get_err() function.

NAVIGATOR_SYSKEY_PRESS

Indicates the user pressed a system key.

The application should indicate whether it will handle the key press by calling the navigator_syskey_press_response() function as soon as possible.

NAVIGATOR_OTHER: Indicates that the event is not any of the above event types.; It could be a custom event.

Library:

libbps (For the qcc command, use the -l bps option to link against this library)

Description:

This enumeration defines the event codes for the types of events that the navigator service may return. Note that a reply is expected when your application receives a NAVIGATOR_ORIENTATION or NAVIGATOR_ORIENTATION_CHECK event. See the navigator_orientation_check_response() and navigator_done_orientation() functions for more information.