gstnavigation

## gstnavigation gstnavigation — Interface for creating, sending and parsing navigation events. |

## Synopsis

    #include <gst/interfaces/navigation.h>

                        GstNavigation;
    struct              GstNavigationInterface;
    enum                GstNavigationCommand;
    enum                GstNavigationEventType;
    enum                GstNavigationMessageType;
    enum                GstNavigationQueryType;
    void                gst_navigation_send_event           (GstNavigation *navigation,
                                                             GstStructure *structure);
    void                gst_navigation_send_key_event       (GstNavigation *navigation,
                                                             const char *event,
                                                             const char *key);
    void                gst_navigation_send_mouse_event     (GstNavigation *navigation,
                                                             const char *event,
                                                             int button,
                                                             double x,
                                                             double y);
    void                gst_navigation_send_command         (GstNavigation *navigation,
                                                             GstNavigationCommand command);
    gboolean            gst_navigation_event_parse_command  (GstEvent *event,
                                                             GstNavigationCommand *command);
    gboolean            gst_navigation_event_parse_key_event
                                                            (GstEvent *event,
                                                             const gchar **key);
    gboolean            gst_navigation_event_parse_mouse_button_event
                                                            (GstEvent *event,
                                                             gint *button,
                                                             gdouble *x,
                                                             gdouble *y);
    gboolean            gst_navigation_event_parse_mouse_move_event
                                                            (GstEvent *event,
                                                             gdouble *x,
                                                             gdouble *y);
    GstNavigationMessageType gst_navigation_message_get_type
                                                            (GstMessage *message);
    GstMessage *        gst_navigation_message_new_angles_changed
                                                            (GstObject *src,
                                                             guint cur_angle,
                                                             guint n_angles);
    GstMessage *        gst_navigation_message_new_commands_changed
                                                            (GstObject *src);
    GstMessage *        gst_navigation_message_new_mouse_over
                                                            (GstObject *src,
                                                             gboolean active);
    gboolean            gst_navigation_message_parse_mouse_over
                                                            (GstMessage *message,
                                                             gboolean *active);
    gboolean            gst_navigation_message_parse_angles_changed
                                                            (GstMessage *message,
                                                             guint *cur_angle,
                                                             guint *n_angles);
    GstQuery *          gst_navigation_query_new_angles     (void);
    GstNavigationQueryType gst_navigation_query_get_type    (GstQuery *query);
    GstQuery *          gst_navigation_query_new_commands   (void);
    gboolean            gst_navigation_query_parse_angles   (GstQuery *query,
                                                             guint *cur_angle,
                                                             guint *n_angles);
    gboolean            gst_navigation_query_parse_commands_length
                                                            (GstQuery *query,
                                                             guint *n_cmds);
    gboolean            gst_navigation_query_parse_commands_nth
                                                            (GstQuery *query,
                                                             guint nth,
                                                             GstNavigationCommand *cmd);
    void                gst_navigation_query_set_angles     (GstQuery *query,
                                                             guint cur_angle,
                                                             guint n_angles);
    void                gst_navigation_query_set_commands   (GstQuery *query,
                                                             gint n_cmds,
                                                             ...);
    void                gst_navigation_query_set_commandsv  (GstQuery *query,
                                                             gint n_cmds,
                                                             GstNavigationCommand *cmds);
    #define             GST_NAVIGATION_COMMAND_DVD_ANGLE_MENU
    #define             GST_NAVIGATION_COMMAND_DVD_AUDIO_MENU
    #define             GST_NAVIGATION_COMMAND_DVD_CHAPTER_MENU
    #define             GST_NAVIGATION_COMMAND_DVD_MENU
    #define             GST_NAVIGATION_COMMAND_DVD_ROOT_MENU
    #define             GST_NAVIGATION_COMMAND_DVD_SUBPICTURE_MENU
    #define             GST_NAVIGATION_COMMAND_DVD_TITLE_MENU

## Object Hierarchy

      GInterface
       +----GstNavigation

## Description

The Navigation interface is used for creating and injecting navigation related events such as mouse button presses, cursor motion and key presses. The associated library also provides methods for parsing received events, and for sending and receiving navigation related bus events. One main usecase is DVD menu navigation.

The main parts of the API are:

- The GstNavigation interface, implemented by elements which provide an application with the ability to create and inject navigation events into the pipeline.

- GstNavigation event handling API. GstNavigation events are created in response to calls on a GstNavigation interface implementation, and sent in the pipeline. Upstream elements can use the navigation event API functions to parse the contents of received messages.

- GstNavigation message handling API. GstNavigation messages may be sent on the message bus to inform applications of navigation related changes in the pipeline, such as the mouse moving over a clickable region, or the set of available angles changing.

  The GstNavigation message functions provide functions for creating and parsing custom bus messages for signaling GstNavigation changes.

## Details

### GstNavigation

    typedef struct _GstNavigation GstNavigation;

### struct GstNavigationInterface

    struct GstNavigationInterface {
      GTypeInterface g_iface;

      /* virtual functions */
      void (*send_event) (GstNavigation *navigation, GstStructure *structure);
    };

Color-balance interface.

GTypeInterface `g_iface`; | the parent interface
`send_event` () | sending a navigation event

### enum GstNavigationCommand

    typedef enum {
      GST_NAVIGATION_COMMAND_INVALID  = 0,

      GST_NAVIGATION_COMMAND_MENU1    = 1,
      GST_NAVIGATION_COMMAND_MENU2    = 2,
      GST_NAVIGATION_COMMAND_MENU3    = 3,
      GST_NAVIGATION_COMMAND_MENU4    = 4,
      GST_NAVIGATION_COMMAND_MENU5    = 5,
      GST_NAVIGATION_COMMAND_MENU6    = 6,
      GST_NAVIGATION_COMMAND_MENU7    = 7,

      GST_NAVIGATION_COMMAND_LEFT     = 20,
      GST_NAVIGATION_COMMAND_RIGHT    = 21,
      GST_NAVIGATION_COMMAND_UP       = 22,
      GST_NAVIGATION_COMMAND_DOWN     = 23,
      GST_NAVIGATION_COMMAND_ACTIVATE = 24,

      GST_NAVIGATION_COMMAND_PREV_ANGLE = 30,
      GST_NAVIGATION_COMMAND_NEXT_ANGLE = 31
    } GstNavigationCommand;

A set of commands that may be issued to an element providing the GstNavigation interface. The available commands can be queried via the `gst_navigation_query_new_commands()` query.

For convenience in handling DVD navigation, the MENU commands are aliased as: GST_NAVIGATION_COMMAND_DVD_MENU = `GST_NAVIGATION_COMMAND_MENU1` GST_NAVIGATION_COMMAND_DVD_TITLE_MENU = `GST_NAVIGATION_COMMAND_MENU2` GST_NAVIGATION_COMMAND_DVD_ROOT_MENU = `GST_NAVIGATION_COMMAND_MENU3` GST_NAVIGATION_COMMAND_DVD_SUBPICTURE_MENU = `GST_NAVIGATION_COMMAND_MENU4` GST_NAVIGATION_COMMAND_DVD_AUDIO_MENU = `GST_NAVIGATION_COMMAND_MENU5` GST_NAVIGATION_COMMAND_DVD_ANGLE_MENU = `GST_NAVIGATION_COMMAND_MENU6` GST_NAVIGATION_COMMAND_DVD_CHAPTER_MENU = `GST_NAVIGATION_COMMAND_MENU7`

`GST_NAVIGATION_COMMAND_INVALID` | An invalid command entry
`GST_NAVIGATION_COMMAND_MENU1` | Execute navigation menu command 1. For DVD, this enters the DVD root menu, or exits back to the title from the menu.
`GST_NAVIGATION_COMMAND_MENU2` | Execute navigation menu command 2. For DVD, this jumps to the DVD title menu.
`GST_NAVIGATION_COMMAND_MENU3` | Execute navigation menu command 3. For DVD, this jumps into the DVD root menu.
`GST_NAVIGATION_COMMAND_MENU4` | Execute navigation menu command 4. For DVD, this jumps to the Subpicture menu.
`GST_NAVIGATION_COMMAND_MENU5` | Execute navigation menu command 5. For DVD, the jumps to the audio menu.
`GST_NAVIGATION_COMMAND_MENU6` | Execute navigation menu command 6. For DVD, this jumps to the angles menu.
`GST_NAVIGATION_COMMAND_MENU7` | Execute navigation menu command 7. For DVD, this jumps to the chapter menu.
`GST_NAVIGATION_COMMAND_LEFT` | Select the next button to the left in a menu, if such a button exists.
`GST_NAVIGATION_COMMAND_RIGHT` | Select the next button to the right in a menu, if such a button exists.
`GST_NAVIGATION_COMMAND_UP` | Select the button above the current one in a menu, if such a button exists.
`GST_NAVIGATION_COMMAND_DOWN` | Select the button below the current one in a menu, if such a button exists.
`GST_NAVIGATION_COMMAND_ACTIVATE` | Activate (click) the currently selected button in a menu, if such a button exists.
`GST_NAVIGATION_COMMAND_PREV_ANGLE` | Switch to the previous angle in a multiangle feature.
`GST_NAVIGATION_COMMAND_NEXT_ANGLE` | Switch to the next angle in a multiangle feature.

Since 0.10.23

### enum GstNavigationEventType

    typedef enum {
      GST_NAVIGATION_EVENT_INVALID                    = 0,
      GST_NAVIGATION_EVENT_KEY_PRESS                  = 1,
      GST_NAVIGATION_EVENT_KEY_RELEASE                = 2,
      GST_NAVIGATION_EVENT_MOUSE_BUTTON_PRESS         = 3,
      GST_NAVIGATION_EVENT_MOUSE_BUTTON_RELEASE       = 4,
      GST_NAVIGATION_EVENT_MOUSE_MOVE                 = 5,
      GST_NAVIGATION_EVENT_COMMAND                    = 6
    } GstNavigationEventType;

Enum values for the various events that an element implementing the GstNavigation interface might send up the pipeline.

`GST_NAVIGATION_EVENT_INVALID` | Returned from `gst_navigation_event_get_type()` when the passed event is not a navigation event.
`GST_NAVIGATION_EVENT_KEY_PRESS` | A key press event. Use `gst_navigation_event_parse_key_event()` to extract the details from the event.
`GST_NAVIGATION_EVENT_KEY_RELEASE` | A key release event. Use `gst_navigation_event_parse_key_event()` to extract the details from the event.
`GST_NAVIGATION_EVENT_MOUSE_BUTTON_PRESS` | A mouse button press event. Use `gst_navigation_event_parse_mouse_button_event()` to extract the details from the event.
`GST_NAVIGATION_EVENT_MOUSE_BUTTON_RELEASE` | A mouse button release event. Use `gst_navigation_event_parse_mouse_button_event()` to extract the details from the event.
`GST_NAVIGATION_EVENT_MOUSE_MOVE` | A mouse movement event. Use `gst_navigation_event_parse_mouse_move_event()` to extract the details from the event.
`GST_NAVIGATION_EVENT_COMMAND` | A navigation command event. Use `gst_navigation_event_parse_command()` to extract the details from the event.

Since 0.10.23

### enum GstNavigationMessageType

    typedef enum {
      GST_NAVIGATION_MESSAGE_INVALID,
      GST_NAVIGATION_MESSAGE_MOUSE_OVER,
      GST_NAVIGATION_MESSAGE_COMMANDS_CHANGED,
      GST_NAVIGATION_MESSAGE_ANGLES_CHANGED
    } GstNavigationMessageType;

A set of notifications that may be received on the bus when navigation related status changes.

`GST_NAVIGATION_MESSAGE_INVALID` | Returned from `gst_navigation_message_get_type()` when the passed message is not a navigation message.
`GST_NAVIGATION_MESSAGE_MOUSE_OVER` | Sent when the mouse moves over or leaves a clickable region of the output, such as a DVD menu button.
`GST_NAVIGATION_MESSAGE_COMMANDS_CHANGED` | Sent when the set of available commands changes and should re-queried by interested applications.
`GST_NAVIGATION_MESSAGE_ANGLES_CHANGED` | Sent when display angles in a multi-angle feature (such as a multiangle DVD) change - either angles have appeared or disappeared.

Since 0.10.23

### enum GstNavigationQueryType

    typedef enum {
      GST_NAVIGATION_QUERY_INVALID     = 0,
      GST_NAVIGATION_QUERY_COMMANDS    = 1,
      GST_NAVIGATION_QUERY_ANGLES      = 2
    } GstNavigationQueryType;

Tyoes of navigation interface queries.

`GST_NAVIGATION_QUERY_INVALID` | invalid query
`GST_NAVIGATION_QUERY_COMMANDS` | command query
`GST_NAVIGATION_QUERY_ANGLES` | viewing angle query

### gst_navigation_send_event ()

    void                gst_navigation_send_event           (GstNavigation *navigation,
                                                             GstStructure *structure);

### gst_navigation_send_key_event ()

    void                gst_navigation_send_key_event       (GstNavigation *navigation,
                                                             const char *event,
                                                             const char *key);

`navigation` : | The navigation interface instance
`event` : | The type of the key event. Recognised values are "key-press" and "key-release"
`key` : | Character representation of the key. This is typically as produced by XKeysymToString.

### gst_navigation_send_mouse_event ()

    void                gst_navigation_send_mouse_event     (GstNavigation *navigation,
                                                             const char *event,
                                                             int button,
                                                             double x,
                                                             double y);

Sends a mouse event to the navigation interface. Mouse event coordinates are sent relative to the display space of the related output area. This is usually the size in pixels of the window associated with the element implementing the GstNavigation interface.

`navigation` : | The navigation interface instance
`event` : | The type of mouse event, as a text string. Recognised values are "mouse-button-press", "mouse-button-release" and "mouse-move".
`button` : | The button number of the button being pressed or released. Pass 0 for mouse-move events.
`x` : | The x coordinate of the mouse event.
`y` : | The y coordinate of the mouse event.

### gst_navigation_send_command ()

    void                gst_navigation_send_command         (GstNavigation *navigation,
                                                             GstNavigationCommand command);

Sends the indicated command to the navigation interface.

`navigation` : | The navigation interface instance
`command` : | The command to issue

Since 0.10.23

### gst_navigation_event_parse_command ()

    gboolean            gst_navigation_event_parse_command  (GstEvent *event,
                                                             GstNavigationCommand *command);

Inspect a GstNavigation command event and retrieve the enum value of the associated command.

`event` : | A GstEvent to inspect.
`command` : | Pointer to GstNavigationCommand to receive the type of the navigation event.
Returns : | TRUE if the navigation command could be extracted, otherwise FALSE.

Since 0.10.23

### gst_navigation_event_parse_key_event ()

    gboolean            gst_navigation_event_parse_key_event
                                                            (GstEvent *event,
                                                             const gchar **key);

`event` : | A GstEvent to inspect.
`key` : | A pointer to a location to receive the string identifying the key press. The returned string is owned by the event, and valid only until the event is unreffed.

Since 0.10.23

### gst_navigation_event_parse_mouse_button_event ()

    gboolean            gst_navigation_event_parse_mouse_button_event
                                                            (GstEvent *event,
                                                             gint *button,
                                                             gdouble *x,
                                                             gdouble *y);

Retrieve the details of either a GstNavigation mouse button press event or a mouse button release event. Determine which type the event is using `gst_navigation_event_get_type()` to retrieve the GstNavigationEventType.

`event` : | A GstEvent to inspect.
`button` : | Pointer to a gint that will receive the button number associated with the event.
`x` : | Pointer to a gdouble to receive the x coordinate of the mouse button event.
`y` : | Pointer to a gdouble to receive the y coordinate of the mouse button event.
Returns : | TRUE if the button number and both coordinates could be extracted, otherwise FALSE.

Since 0.10.23

### gst_navigation_event_parse_mouse_move_event ()

    gboolean            gst_navigation_event_parse_mouse_move_event
                                                            (GstEvent *event,
                                                             gdouble *x,
                                                             gdouble *y);

Inspect a GstNavigation mouse movement event and extract the coordinates of the event.

`event` : | A GstEvent to inspect.
`x` : | Pointer to a gdouble to receive the x coordinate of the mouse movement.
`y` : | Pointer to a gdouble to receive the y coordinate of the mouse movement.
Returns : | TRUE if both coordinates could be extracted, otherwise FALSE.

Since 0.10.23

### gst_navigation_message_get_type ()

    GstNavigationMessageType gst_navigation_message_get_type
                                                            (GstMessage *message);

Check a bus message to see if it is a GstNavigation event, and return the GstNavigationMessageType identifying the type of the message if so.

`message` : | A GstMessage to inspect.
Returns : | The type of the GstMessage, or GST_NAVIGATION_MESSAGE_INVALID if the message is not a GstNavigation notification.

Since 0.10.23

### gst_navigation_message_new_angles_changed ()

    GstMessage *        gst_navigation_message_new_angles_changed
                                                            (GstObject *src,
                                                             guint cur_angle,
                                                             guint n_angles);

Creates a new GstNavigation message with type GST_NAVIGATION_MESSAGE_ANGLES_CHANGED for notifying an application that the current angle, or current number of angles available in a multiangle video has changed.

`src` : | A GstObject to set as source of the new message.
`cur_angle` : | The currently selected angle.
`n_angles` : | The number of viewing angles now available.
Returns : | The new GstMessage.

Since 0.10.23

### gst_navigation_message_new_commands_changed ()

    GstMessage *        gst_navigation_message_new_commands_changed
                                                            (GstObject *src);

Creates a new GstNavigation message with type GST_NAVIGATION_MESSAGE_COMMANDS_CHANGED

`src` : | A GstObject to set as source of the new message.
Returns : | The new GstMessage.

Since 0.10.23

### gst_navigation_message_new_mouse_over ()

    GstMessage *        gst_navigation_message_new_mouse_over
                                                            (GstObject *src,
                                                             gboolean active);

Creates a new GstNavigation message with type GST_NAVIGATION_MESSAGE_MOUSE_OVER.

`src` : | A GstObject to set as source of the new message.
`active` : | `TRUE` if the mouse has entered a clickable area of the display. `FALSE` if it over a non-clickable area.
Returns : | The new GstMessage.

Since 0.10.23

### gst_navigation_message_parse_mouse_over ()

    gboolean            gst_navigation_message_parse_mouse_over
                                                            (GstMessage *message,
                                                             gboolean *active);

Parse a GstNavigation message of type GST_NAVIGATION_MESSAGE_MOUSE_OVER and extract the active/inactive flag. If the mouse over event is marked active, it indicates that the mouse is over a clickable area.

`message` : | A GstMessage to inspect.
`active` : | A pointer to a gboolean to receive the active/inactive state, or NULL.
Returns : | `TRUE` if the message could be successfully parsed. `FALSE` if not.

Since 0.10.23

### gst_navigation_message_parse_angles_changed ()

    gboolean            gst_navigation_message_parse_angles_changed
                                                            (GstMessage *message,
                                                             guint *cur_angle,
                                                             guint *n_angles);

Parse a GstNavigation message of type GST_NAVIGATION_MESSAGE_ANGLES_CHANGED and extract the `cur_angle` and `n_angles` parameters.

`message` : | A GstMessage to inspect.
`cur_angle` : | A pointer to a guint to receive the new current angle number, or NULL
`n_angles` : | A pointer to a guint to receive the new angle count, or NULL.
Returns : | `TRUE` if the message could be successfully parsed. `FALSE` if not.

Since 0.10.23

### gst_navigation_query_new_angles ()

    GstQuery *          gst_navigation_query_new_angles     (void);

Create a new GstNavigation angles query. When executed, it will query the pipeline for the set of currently available angles, which may be greater than one in a multiangle video.

Returns : | The new query.

Since 0.10.23

### gst_navigation_query_get_type ()

    GstNavigationQueryType gst_navigation_query_get_type    (GstQuery *query);

Inspect a GstQuery and return the GstNavigationQueryType associated with it if it is a GstNavigation query.

`query` : | The query to inspect
Returns : | The GstNavigationQueryType of the query, or GST_NAVIGATION_QUERY_INVALID

Since 0.10.23

### gst_navigation_query_new_commands ()

    GstQuery *          gst_navigation_query_new_commands   (void);

Create a new GstNavigation commands query. When executed, it will query the pipeline for the set of currently available commands.

Returns : | The new query.

Since 0.10.23

### gst_navigation_query_parse_angles ()

    gboolean            gst_navigation_query_parse_angles   (GstQuery *query,
                                                             guint *cur_angle,
                                                             guint *n_angles);

Parse the current angle number in the GstNavigation angles `query` into the guint pointed to by the `cur_angle` variable, and the number of available angles into the guint pointed to by the `n_angles` variable.

`query` : | a GstQuery
`cur_angle` : | Pointer to a guint into which to store the currently selected angle value from the query, or NULL
`n_angles` : | Pointer to a guint into which to store the number of angles value from the query, or NULL
Returns : | `TRUE` if the query could be successfully parsed. `FALSE` if not.

Since 0.10.23

### gst_navigation_query_parse_commands_length ()

    gboolean            gst_navigation_query_parse_commands_length
                                                            (GstQuery *query,
                                                             guint *n_cmds);

Parse the number of commands in the GstNavigation commands `query`.

`query` : | a GstQuery
`n_cmds` : | the number of commands in this query.
Returns : | `TRUE` if the query could be successfully parsed. `FALSE` if not.

Since 0.10.23

### gst_navigation_query_parse_commands_nth ()

    gboolean            gst_navigation_query_parse_commands_nth
                                                            (GstQuery *query,
                                                             guint nth,
                                                             GstNavigationCommand *cmd);

Parse the GstNavigation command query and retrieve the `nth` command from it into `cmd`. If the list contains less elements than `nth`, `cmd` will be set to GST_NAVIGATION_COMMAND_INVALID.

`query` : | a GstQuery
`nth` : | the nth command to retrieve.
`cmd` : | a pointer to store the nth command into.
Returns : | `TRUE` if the query could be successfully parsed. `FALSE` if not.

Since 0.10.23

### gst_navigation_query_set_angles ()

    void                gst_navigation_query_set_angles     (GstQuery *query,
                                                             guint cur_angle,
                                                             guint n_angles);

Set the GstNavigation angles query result field in `query`.

`query` : | a GstQuery
`cur_angle` : | the current viewing angle to set.
`n_angles` : | the number of viewing angles to set.

Since 0.10.23

### gst_navigation_query_set_commands ()

    void                gst_navigation_query_set_commands   (GstQuery *query,
                                                             gint n_cmds,
                                                             ...);

Set the GstNavigation command query result fields in `query`. The number of commands passed must be equal to `n_commands`.

`query` : | a GstQuery
`n_cmds` : | the number of commands to set.
`...` : | A list of `GstNavigationCommand` values, `n_cmds` entries long.

Since 0.10.23

### gst_navigation_query_set_commandsv ()

    void                gst_navigation_query_set_commandsv  (GstQuery *query,
                                                             gint n_cmds,
                                                             GstNavigationCommand *cmds);

Set the GstNavigation command query result fields in `query`. The number of commands passed must be equal to `n_commands`.

`query` : | a GstQuery
`n_cmds` : | the number of commands to set.
`cmds` : | An array containing `n_cmds` `GstNavigationCommand` values.

Since 0.10.23

### GST_NAVIGATION_COMMAND_DVD_ANGLE_MENU

    #define GST_NAVIGATION_COMMAND_DVD_ANGLE_MENU      GST_NAVIGATION_COMMAND_MENU6

### GST_NAVIGATION_COMMAND_DVD_AUDIO_MENU

    #define GST_NAVIGATION_COMMAND_DVD_AUDIO_MENU      GST_NAVIGATION_COMMAND_MENU5

### GST_NAVIGATION_COMMAND_DVD_CHAPTER_MENU

    #define GST_NAVIGATION_COMMAND_DVD_CHAPTER_MENU    GST_NAVIGATION_COMMAND_MENU7

### GST_NAVIGATION_COMMAND_DVD_MENU

    #define GST_NAVIGATION_COMMAND_DVD_MENU            GST_NAVIGATION_COMMAND_MENU1

### GST_NAVIGATION_COMMAND_DVD_ROOT_MENU

    #define GST_NAVIGATION_COMMAND_DVD_ROOT_MENU       GST_NAVIGATION_COMMAND_MENU3

### GST_NAVIGATION_COMMAND_DVD_SUBPICTURE_MENU

    #define GST_NAVIGATION_COMMAND_DVD_SUBPICTURE_MENU GST_NAVIGATION_COMMAND_MENU4

### GST_NAVIGATION_COMMAND_DVD_TITLE_MENU

    #define GST_NAVIGATION_COMMAND_DVD_TITLE_MENU      GST_NAVIGATION_COMMAND_MENU2