1 /* GStreamer Navigation 2 * Copyright (C) 2003 Ronald Bultje <rbultje@ronald.bitfreak.net> 3 * Copyright (C) 2003 David A. Schleef <ds@schleef.org> 4 * 5 * navigation.h: navigation interface design 6 * 7 * This library is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Library General Public 9 * License as published by the Free Software Foundation; either 10 * version 2 of the License, or (at your option) any later version. 11 * 12 * This library is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Library General Public License for more details. 16 * 17 * You should have received a copy of the GNU Library General Public 18 * License along with this library; if not, write to the 19 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 20 * Boston, MA 02110-1301, USA. 21 */ 22 23 #ifndef __GST_NAVIGATION_H__ 24 #define __GST_NAVIGATION_H__ 25 26 #include <gst/gst.h> 27 #include <gst/video/video-prelude.h> 28 29 G_BEGIN_DECLS 30 31 #define GST_TYPE_NAVIGATION \ 32 (gst_navigation_get_type ()) 33 #define GST_NAVIGATION(obj) \ 34 (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_NAVIGATION, GstNavigation)) 35 #define GST_IS_NAVIGATION(obj) \ 36 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_NAVIGATION)) 37 #define GST_NAVIGATION_GET_INTERFACE(obj) \ 38 (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GST_TYPE_NAVIGATION, GstNavigationInterface)) 39 40 typedef struct _GstNavigation GstNavigation; 41 typedef struct _GstNavigationInterface GstNavigationInterface; 42 43 /** 44 * GstNavigationInterface: 45 * @iface: the parent interface 46 * @send_event: sending a navigation event 47 * 48 * Navigation interface. 49 */ 50 struct _GstNavigationInterface { 51 GTypeInterface iface; 52 53 /* virtual functions */ 54 void (*send_event) (GstNavigation *navigation, GstStructure *structure); 55 }; 56 57 GST_VIDEO_API 58 GType gst_navigation_get_type (void); 59 60 /* Navigation commands */ 61 62 /** 63 * GstNavigationCommand: 64 * @GST_NAVIGATION_COMMAND_INVALID: An invalid command entry 65 * @GST_NAVIGATION_COMMAND_MENU1: Execute navigation menu command 1. For DVD, 66 * this enters the DVD root menu, or exits back to the title from the menu. 67 * @GST_NAVIGATION_COMMAND_MENU2: Execute navigation menu command 2. For DVD, 68 * this jumps to the DVD title menu. 69 * @GST_NAVIGATION_COMMAND_MENU3: Execute navigation menu command 3. For DVD, 70 * this jumps into the DVD root menu. 71 * @GST_NAVIGATION_COMMAND_MENU4: Execute navigation menu command 4. For DVD, 72 * this jumps to the Subpicture menu. 73 * @GST_NAVIGATION_COMMAND_MENU5: Execute navigation menu command 5. For DVD, 74 * the jumps to the audio menu. 75 * @GST_NAVIGATION_COMMAND_MENU6: Execute navigation menu command 6. For DVD, 76 * this jumps to the angles menu. 77 * @GST_NAVIGATION_COMMAND_MENU7: Execute navigation menu command 7. For DVD, 78 * this jumps to the chapter menu. 79 * @GST_NAVIGATION_COMMAND_LEFT: Select the next button to the left in a menu, 80 * if such a button exists. 81 * @GST_NAVIGATION_COMMAND_RIGHT: Select the next button to the right in a menu, 82 * if such a button exists. 83 * @GST_NAVIGATION_COMMAND_UP: Select the button above the current one in a 84 * menu, if such a button exists. 85 * @GST_NAVIGATION_COMMAND_DOWN: Select the button below the current one in a 86 * menu, if such a button exists. 87 * @GST_NAVIGATION_COMMAND_ACTIVATE: Activate (click) the currently selected 88 * button in a menu, if such a button exists. 89 * @GST_NAVIGATION_COMMAND_PREV_ANGLE: Switch to the previous angle in a 90 * multiangle feature. 91 * @GST_NAVIGATION_COMMAND_NEXT_ANGLE: Switch to the next angle in a multiangle 92 * feature. 93 * 94 * A set of commands that may be issued to an element providing the 95 * #GstNavigation interface. The available commands can be queried via 96 * the gst_navigation_query_new_commands() query. 97 * 98 * For convenience in handling DVD navigation, the MENU commands are aliased as: 99 * GST_NAVIGATION_COMMAND_DVD_MENU = @GST_NAVIGATION_COMMAND_MENU1 100 * GST_NAVIGATION_COMMAND_DVD_TITLE_MENU = @GST_NAVIGATION_COMMAND_MENU2 101 * GST_NAVIGATION_COMMAND_DVD_ROOT_MENU = @GST_NAVIGATION_COMMAND_MENU3 102 * GST_NAVIGATION_COMMAND_DVD_SUBPICTURE_MENU = @GST_NAVIGATION_COMMAND_MENU4 103 * GST_NAVIGATION_COMMAND_DVD_AUDIO_MENU = @GST_NAVIGATION_COMMAND_MENU5 104 * GST_NAVIGATION_COMMAND_DVD_ANGLE_MENU = @GST_NAVIGATION_COMMAND_MENU6 105 * GST_NAVIGATION_COMMAND_DVD_CHAPTER_MENU = @GST_NAVIGATION_COMMAND_MENU7 106 */ 107 typedef enum { 108 GST_NAVIGATION_COMMAND_INVALID = 0, 109 110 GST_NAVIGATION_COMMAND_MENU1 = 1, 111 GST_NAVIGATION_COMMAND_MENU2 = 2, 112 GST_NAVIGATION_COMMAND_MENU3 = 3, 113 GST_NAVIGATION_COMMAND_MENU4 = 4, 114 GST_NAVIGATION_COMMAND_MENU5 = 5, 115 GST_NAVIGATION_COMMAND_MENU6 = 6, 116 GST_NAVIGATION_COMMAND_MENU7 = 7, 117 118 GST_NAVIGATION_COMMAND_LEFT = 20, 119 GST_NAVIGATION_COMMAND_RIGHT = 21, 120 GST_NAVIGATION_COMMAND_UP = 22, 121 GST_NAVIGATION_COMMAND_DOWN = 23, 122 GST_NAVIGATION_COMMAND_ACTIVATE = 24, 123 124 GST_NAVIGATION_COMMAND_PREV_ANGLE = 30, 125 GST_NAVIGATION_COMMAND_NEXT_ANGLE = 31 126 } GstNavigationCommand; 127 128 /* Some aliases for the menu command types */ 129 #define GST_NAVIGATION_COMMAND_DVD_MENU GST_NAVIGATION_COMMAND_MENU1 130 #define GST_NAVIGATION_COMMAND_DVD_TITLE_MENU GST_NAVIGATION_COMMAND_MENU2 131 #define GST_NAVIGATION_COMMAND_DVD_ROOT_MENU GST_NAVIGATION_COMMAND_MENU3 132 #define GST_NAVIGATION_COMMAND_DVD_SUBPICTURE_MENU GST_NAVIGATION_COMMAND_MENU4 133 #define GST_NAVIGATION_COMMAND_DVD_AUDIO_MENU GST_NAVIGATION_COMMAND_MENU5 134 #define GST_NAVIGATION_COMMAND_DVD_ANGLE_MENU GST_NAVIGATION_COMMAND_MENU6 135 #define GST_NAVIGATION_COMMAND_DVD_CHAPTER_MENU GST_NAVIGATION_COMMAND_MENU7 136 137 /* Queries */ 138 /** 139 * GstNavigationQueryType: 140 * @GST_NAVIGATION_QUERY_INVALID: invalid query 141 * @GST_NAVIGATION_QUERY_COMMANDS: command query 142 * @GST_NAVIGATION_QUERY_ANGLES: viewing angle query 143 * 144 * Tyoes of navigation interface queries. 145 */ 146 typedef enum 147 { 148 GST_NAVIGATION_QUERY_INVALID = 0, 149 GST_NAVIGATION_QUERY_COMMANDS = 1, 150 GST_NAVIGATION_QUERY_ANGLES = 2 151 } GstNavigationQueryType; 152 153 GST_VIDEO_API 154 GstNavigationQueryType gst_navigation_query_get_type (GstQuery *query); 155 156 GST_VIDEO_API 157 GstQuery * gst_navigation_query_new_commands (void); 158 159 GST_VIDEO_API 160 void gst_navigation_query_set_commands (GstQuery *query, gint n_cmds, ...); 161 162 GST_VIDEO_API 163 void gst_navigation_query_set_commandsv (GstQuery *query, gint n_cmds, 164 GstNavigationCommand *cmds); 165 166 GST_VIDEO_API 167 gboolean gst_navigation_query_parse_commands_length (GstQuery *query, 168 guint *n_cmds); 169 170 GST_VIDEO_API 171 gboolean gst_navigation_query_parse_commands_nth (GstQuery *query, guint nth, 172 GstNavigationCommand *cmd); 173 174 GST_VIDEO_API 175 GstQuery * gst_navigation_query_new_angles (void); 176 177 GST_VIDEO_API 178 void gst_navigation_query_set_angles (GstQuery *query, guint cur_angle, 179 guint n_angles); 180 181 GST_VIDEO_API 182 gboolean gst_navigation_query_parse_angles (GstQuery *query, guint *cur_angle, 183 guint *n_angles); 184 185 /* Element messages */ 186 /** 187 * GstNavigationMessageType: 188 * @GST_NAVIGATION_MESSAGE_INVALID: Returned from 189 * gst_navigation_message_get_type() when the passed message is not a 190 * navigation message. 191 * @GST_NAVIGATION_MESSAGE_MOUSE_OVER: Sent when the mouse moves over or leaves a 192 * clickable region of the output, such as a DVD menu button. 193 * @GST_NAVIGATION_MESSAGE_COMMANDS_CHANGED: Sent when the set of available commands 194 * changes and should re-queried by interested applications. 195 * @GST_NAVIGATION_MESSAGE_ANGLES_CHANGED: Sent when display angles in a multi-angle 196 * feature (such as a multiangle DVD) change - either angles have appeared or 197 * disappeared. 198 * @GST_NAVIGATION_MESSAGE_EVENT: Sent when a navigation event was not handled 199 * by any element in the pipeline (Since: 1.6) 200 * 201 * A set of notifications that may be received on the bus when navigation 202 * related status changes. 203 */ 204 typedef enum { 205 GST_NAVIGATION_MESSAGE_INVALID, 206 GST_NAVIGATION_MESSAGE_MOUSE_OVER, 207 GST_NAVIGATION_MESSAGE_COMMANDS_CHANGED, 208 GST_NAVIGATION_MESSAGE_ANGLES_CHANGED, 209 GST_NAVIGATION_MESSAGE_EVENT 210 } GstNavigationMessageType; 211 212 GST_VIDEO_API 213 GstNavigationMessageType gst_navigation_message_get_type (GstMessage *message); 214 215 GST_VIDEO_API 216 GstMessage * gst_navigation_message_new_mouse_over (GstObject *src, 217 gboolean active); 218 219 GST_VIDEO_API 220 gboolean gst_navigation_message_parse_mouse_over (GstMessage *message, 221 gboolean *active); 222 223 GST_VIDEO_API 224 GstMessage * gst_navigation_message_new_commands_changed (GstObject *src); 225 226 GST_VIDEO_API 227 GstMessage * gst_navigation_message_new_angles_changed (GstObject *src, 228 guint cur_angle, 229 guint n_angles); 230 231 GST_VIDEO_API 232 gboolean gst_navigation_message_parse_angles_changed (GstMessage *message, 233 guint *cur_angle, 234 guint *n_angles); 235 236 GST_VIDEO_API 237 GstMessage * gst_navigation_message_new_event (GstObject *src, 238 GstEvent *event); 239 240 GST_VIDEO_API 241 gboolean gst_navigation_message_parse_event (GstMessage *message, 242 GstEvent ** event); 243 /* event parsing functions */ 244 /** 245 * GstNavigationEventType: 246 * @GST_NAVIGATION_EVENT_INVALID: Returned from 247 * gst_navigation_event_get_type() when the passed event is not a navigation event. 248 * @GST_NAVIGATION_EVENT_KEY_PRESS: A key press event. Use 249 * gst_navigation_event_parse_key_event() to extract the details from the event. 250 * @GST_NAVIGATION_EVENT_KEY_RELEASE: A key release event. Use 251 * gst_navigation_event_parse_key_event() to extract the details from the event. 252 * @GST_NAVIGATION_EVENT_MOUSE_BUTTON_PRESS: A mouse button press event. Use 253 * gst_navigation_event_parse_mouse_button_event() to extract the details from the 254 * event. 255 * @GST_NAVIGATION_EVENT_MOUSE_BUTTON_RELEASE: A mouse button release event. Use 256 * gst_navigation_event_parse_mouse_button_event() to extract the details from the 257 * event. 258 * @GST_NAVIGATION_EVENT_MOUSE_MOVE: A mouse movement event. Use 259 * gst_navigation_event_parse_mouse_move_event() to extract the details from the 260 * event. 261 * @GST_NAVIGATION_EVENT_COMMAND: A navigation command event. Use 262 * gst_navigation_event_parse_command() to extract the details from the event. 263 * 264 * Enum values for the various events that an element implementing the 265 * GstNavigation interface might send up the pipeline. 266 */ 267 typedef enum { 268 GST_NAVIGATION_EVENT_INVALID = 0, 269 GST_NAVIGATION_EVENT_KEY_PRESS = 1, 270 GST_NAVIGATION_EVENT_KEY_RELEASE = 2, 271 GST_NAVIGATION_EVENT_MOUSE_BUTTON_PRESS = 3, 272 GST_NAVIGATION_EVENT_MOUSE_BUTTON_RELEASE = 4, 273 GST_NAVIGATION_EVENT_MOUSE_MOVE = 5, 274 GST_NAVIGATION_EVENT_COMMAND = 6 275 } GstNavigationEventType; 276 277 GST_VIDEO_API 278 GstNavigationEventType gst_navigation_event_get_type (GstEvent *event); 279 280 GST_VIDEO_API 281 gboolean gst_navigation_event_parse_key_event (GstEvent *event, 282 const gchar **key); 283 284 GST_VIDEO_API 285 gboolean gst_navigation_event_parse_mouse_button_event (GstEvent *event, 286 gint *button, gdouble *x, gdouble *y); 287 288 GST_VIDEO_API 289 gboolean gst_navigation_event_parse_mouse_move_event (GstEvent *event, 290 gdouble *x, gdouble *y); 291 292 GST_VIDEO_API 293 gboolean gst_navigation_event_parse_command (GstEvent *event, 294 GstNavigationCommand *command); 295 296 /* interface virtual function wrappers */ 297 298 GST_VIDEO_API 299 void gst_navigation_send_event (GstNavigation *navigation, 300 GstStructure *structure); 301 302 GST_VIDEO_API 303 void gst_navigation_send_key_event (GstNavigation *navigation, 304 const char *event, const char *key); 305 306 GST_VIDEO_API 307 void gst_navigation_send_mouse_event (GstNavigation *navigation, 308 const char *event, int button, double x, double y); 309 310 GST_VIDEO_API 311 void gst_navigation_send_command (GstNavigation *navigation, 312 GstNavigationCommand command); 313 314 G_END_DECLS 315 316 #endif /* __GST_NAVIGATION_H__ */ 317