* Copyright (C) 2007-2009 Jan Schmidt <thaytan@noraisin.net>

 * navigation.c: navigation event virtual class function wrappers

/**

 * SECTION:gstnavigation

 * @short_description: Interface for creating, sending and parsing navigation

 * events.

 *

 * 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:

 * <itemizedlist>

 * <listitem>

 * <para>

 * The GstNavigation interface, implemented by elements which provide an application

 * with the ability to create and inject navigation events into the pipeline.

 * </para>

 * </listitem>

 * <listitem>

 * <para>

 * 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.

 * </para>

 * </listitem>

 * <listitem>

 * <para>

 * 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.

 * </para><para>

 * The GstNavigation message functions provide functions for creating and parsing

 * custom bus messages for signalling GstNavigation changes.

 * </para>

 * </listitem>

 * </itemizedlist>

 */

#include <gst/interfaces/interfaces-enumtypes.h>

#define GST_NAVIGATION_MESSAGE_NAME "GstNavigationMessage"

#define GST_NAVIGATION_QUERY_NAME "GstNavigationQuery"

#define GST_NAVIGATION_EVENT_NAME "application/x-gst-navigation"

/**

 * gst_navigation_send_mouse_event:

 * @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_structure_new (GST_NAVIGATION_EVENT_NAME, "event", G_TYPE_STRING,

/**

 * gst_navigation_send_mouse_event:

 * @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.

 *

 * 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.

 *

 */

      gst_structure_new (GST_NAVIGATION_EVENT_NAME, "event", G_TYPE_STRING,

/**

 * gst_navigation_send_command:

 * @navigation: The navigation interface instance

 * @command: The command to issue

 *

 * Sends the indicated command to the navigation interface.

 *

 * Since: 0.10.23

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_navigation_send_command (GstNavigation * navigation,

    GstNavigationCommand command)

{

  gst_navigation_send_event (navigation,

      gst_structure_new (GST_NAVIGATION_EVENT_NAME, "event", G_TYPE_STRING,

          "command", "command-code", G_TYPE_UINT, (guint) command, NULL));

}

/* Navigation Queries */

#define GST_NAVIGATION_QUERY_HAS_TYPE(query,query_type) \

(gst_navigation_query_get_type (query) == GST_NAVIGATION_QUERY_ ## query_type)

/**

 * gst_navigation_query_get_type:

 * @query: The query to inspect

 *

 * Inspect a #GstQuery and return the #GstNavigationQueryType associated with

 * it if it is a #GstNavigation query.

 *

 * Returns: The #GstNavigationQueryType of the query, or

 * #GST_NAVIGATION_QUERY_INVALID

 * Since: 0.10.23

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstNavigationQueryType

gst_navigation_query_get_type (GstQuery * query)

{

  const GstStructure *s;

  const gchar *q_type;

  if (query == NULL || GST_QUERY_TYPE (query) != GST_QUERY_CUSTOM)

    return GST_NAVIGATION_QUERY_INVALID;

  s = gst_query_get_structure (query);

  if (s == NULL || !gst_structure_has_name (s, GST_NAVIGATION_QUERY_NAME))

    return GST_NAVIGATION_QUERY_INVALID;

  q_type = gst_structure_get_string (s, "type");

  if (q_type == NULL)

    return GST_NAVIGATION_QUERY_INVALID;

  if (g_str_equal (q_type, "commands"))

    return GST_NAVIGATION_QUERY_COMMANDS;

  else if (g_str_equal (q_type, "angles"))

    return GST_NAVIGATION_QUERY_ANGLES;

  return GST_NAVIGATION_QUERY_INVALID;

}

/**

 * gst_navigation_query_new_commands:

 *

 * 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

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstQuery *

gst_navigation_query_new_commands (void)

{

  GstQuery *query;

  GstStructure *structure;

  structure = gst_structure_new (GST_NAVIGATION_QUERY_NAME,

      "type", G_TYPE_STRING, "commands", NULL);

  query = gst_query_new_application (GST_QUERY_CUSTOM, structure);

  return query;

}

static void

gst_query_list_add_command (GValue * list, GstNavigationCommand val)

{

  GValue item = { 0, };

  g_value_init (&item, GST_TYPE_NAVIGATION_COMMAND);

  g_value_set_enum (&item, val);

  gst_value_list_append_value (list, &item);

  g_value_unset (&item);

}

/**

 * gst_navigation_query_set_commands:

 * @query: a #GstQuery

 * @n_cmds: the number of commands to set.

 * @...: A list of @GstNavigationCommand values, @n_cmds entries long.

 *

 * Set the #GstNavigation command query result fields in @query. The number

 * of commands passed must be equal to @n_commands.

 *

 * Since: 0.10.23

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

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

{

  va_list ap;

  GValue list = { 0, };

  GstStructure *structure;

  gint i;

  g_return_if_fail (GST_NAVIGATION_QUERY_HAS_TYPE (query, COMMANDS));

  g_value_init (&list, GST_TYPE_LIST);

  va_start (ap, n_cmds);

  for (i = 0; i < n_cmds; i++) {

    GstNavigationCommand val = va_arg (ap, GstNavigationCommand);

    gst_query_list_add_command (&list, val);

  }

  va_end (ap);

  structure = gst_query_get_structure (query);

  gst_structure_set_value (structure, "commands", &list);

  g_value_unset (&list);

}

/**

 * gst_navigation_query_set_commandsv:

 * @query: a #GstQuery

 * @n_cmds: the number of commands to set.

 * @cmds: An array containing @n_cmds @GstNavigationCommand values.

 *

 * Set the #GstNavigation command query result fields in @query. The number

 * of commands passed must be equal to @n_commands.

 *

 * Since: 0.10.23

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_navigation_query_set_commandsv (GstQuery * query, gint n_cmds,

    GstNavigationCommand * cmds)

{

  GValue list = { 0, };

  GstStructure *structure;

  gint i;

  g_return_if_fail (GST_NAVIGATION_QUERY_HAS_TYPE (query, COMMANDS));

  g_value_init (&list, GST_TYPE_LIST);

  for (i = 0; i < n_cmds; i++) {

    gst_query_list_add_command (&list, cmds[i]);

  }

  structure = gst_query_get_structure (query);

  gst_structure_set_value (structure, "commands", &list);

  g_value_unset (&list);

}

/**

 * gst_navigation_query_parse_commands_length:

 * @query: a #GstQuery

 * @n_cmds: the number of commands in this query.

 *

 * Parse the number of commands in the #GstNavigation commands @query.

 *

 * Returns: %TRUE if the query could be successfully parsed. %FALSE if not.

 * Since: 0.10.23

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

gboolean

gst_navigation_query_parse_commands_length (GstQuery * query, guint * n_cmds)

{

  GstStructure *structure;

  const GValue *list;

  g_return_val_if_fail (GST_NAVIGATION_QUERY_HAS_TYPE (query, COMMANDS), FALSE);

  if (n_cmds == NULL)

    return TRUE;

  structure = gst_query_get_structure (query);

  list = gst_structure_get_value (structure, "commands");

  if (list == NULL)

    *n_cmds = 0;

  else

    *n_cmds = gst_value_list_get_size (list);

  return TRUE;

}

/**

 * gst_navigation_query_parse_commands_nth:

 * @query: a #GstQuery

 * @nth: the nth command to retrieve.

 * @cmd: a pointer to store the nth command into.

 *

 * 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.

 *

 * Returns: %TRUE if the query could be successfully parsed. %FALSE if not.

 * Since: 0.10.23

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

gboolean

gst_navigation_query_parse_commands_nth (GstQuery * query, guint nth,

    GstNavigationCommand * cmd)

{

  GstStructure *structure;

  const GValue *list;

  g_return_val_if_fail (GST_NAVIGATION_QUERY_HAS_TYPE (query, COMMANDS), FALSE);

  if (cmd == NULL)

    return TRUE;

  structure = gst_query_get_structure (query);

  list = gst_structure_get_value (structure, "commands");

  if (list == NULL) {

    *cmd = GST_NAVIGATION_COMMAND_INVALID;

  } else {

    if (nth < gst_value_list_get_size (list)) {

      *cmd = (GstNavigationCommand)

          g_value_get_enum (gst_value_list_get_value (list, nth));

    } else

      *cmd = GST_NAVIGATION_COMMAND_INVALID;

  }

  return TRUE;

}

/**

 * gst_navigation_query_new_angles:

 *

 * 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

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

GstQuery *

gst_navigation_query_new_angles (void)

{

  GstQuery *query;

  GstStructure *structure;

  structure = gst_structure_new (GST_NAVIGATION_QUERY_NAME,

      "type", G_TYPE_STRING, "angles", NULL);

  query = gst_query_new_application (GST_QUERY_CUSTOM, structure);

  return query;

}

/**

 * gst_navigation_query_set_angles:

 * @query: a #GstQuery

 * @cur_angle: the current viewing angle to set.

 * @n_angles: the number of viewing angles to set.

 *

 * Set the #GstNavigation angles query result field in @query.

 *

 * Since: 0.10.23

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_navigation_query_set_angles (GstQuery * query, guint cur_angle,

    guint n_angles)

{

  GstStructure *structure;

  g_return_if_fail (GST_NAVIGATION_QUERY_HAS_TYPE (query, ANGLES));

  structure = gst_query_get_structure (query);

  gst_structure_set (structure,

      "angle", G_TYPE_UINT, cur_angle, "angles", G_TYPE_UINT, n_angles, NULL);

}

/**

 * gst_navigation_query_parse_angles:

 * @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

 *

 * 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.