include/vlc_extensions.h

   1 /*****************************************************************************
   2  * vlc_extensions.h: Extensions (meta data, web information, ...)
   3  *****************************************************************************
   4  * Copyright (C) 2009-2010 VideoLAN and authors
   5  *
   6  * Authors: Jean-Philippe André < jpeg # videolan.org >
   7  *
   8  * This program is free software; you can redistribute it and/or modify it
   9  * under the terms of the GNU Lesser General Public License as published by
  10  * the Free Software Foundation; either version 2.1 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16  * GNU Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public License
  19  * along with this program; if not, write to the Free Software Foundation,
  20  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  21  *****************************************************************************/
  22
  23 #ifndef VLC_EXTENSIONS_H
  24 #define VLC_EXTENSIONS_H
  25
  26 #include "vlc_common.h"
  27 #include "vlc_arrays.h"
  28
  29 /* Structures */
  30 typedef struct extensions_manager_sys_t extensions_manager_sys_t;
  31 typedef struct extensions_manager_t extensions_manager_t;
  32 typedef struct extension_sys_t extension_sys_t;
  33
  34 /** Extension descriptor: name, title, author, ... */
  35 typedef struct extension_t {
  36     /* Below, (ro) means read-only for the GUI */
  37     char *psz_name;           /**< Real name of the extension (ro) */
  38
  39     char *psz_title;          /**< Display title (ro) */
  40     char *psz_author;         /**< Author of the extension (ro) */
  41     char *psz_version;        /**< Version (ro) */
  42     char *psz_url;            /**< A URL to the official page (ro) */
  43     char *psz_description;    /**< Full description (ro) */
  44     char *psz_shortdescription; /**< Short description (eg. 1 line)  (ro) */
  45     char *p_icondata;         /**< Embedded data for the icon (ro) */
  46     int   i_icondata_size;    /**< Size of that data */
  47
  48     extension_sys_t *p_sys;   /**< Reserved for the manager module */
  49 } extension_t;
  50
  51 /** Extensions manager object */
  52 struct extensions_manager_t
  53 {
  54     struct vlc_object_t obj;
  55
  56     module_t *p_module;                /**< Extensions manager module */
  57     extensions_manager_sys_t *p_sys;   /**< Reserved for the module */
  58
  59     DECL_ARRAY(extension_t*) extensions; /**< Array of extension descriptors */
  60     vlc_mutex_t lock;                  /**< A lock for the extensions array */
  61
  62     /** Control, see extension_Control */
  63     int ( *pf_control ) ( extensions_manager_t*, int, va_list );
  64 };
  65
  66 /* Control commands */
  67 enum
  68 {
  69     /* Control extensions */
  70     EXTENSION_ACTIVATE,       /**< arg1: extension_t* */
  71     EXTENSION_DEACTIVATE,     /**< arg1: extension_t* */
  72     EXTENSION_IS_ACTIVATED,   /**< arg1: extension_t*, arg2: bool* */
  73     EXTENSION_HAS_MENU,       /**< arg1: extension_t* */
  74     EXTENSION_GET_MENU,       /**< arg1: extension_t*, arg2: char***, arg3: uint16_t** */
  75     EXTENSION_TRIGGER_ONLY,   /**< arg1: extension_t*, arg2: bool* */
  76     EXTENSION_TRIGGER,        /**< arg1: extension_t* */
  77     EXTENSION_TRIGGER_MENU,   /**< arg1: extension_t*, int (uint16_t) */
  78     EXTENSION_SET_INPUT,      /**< arg1: extension_t*, arg2 (input_item_t*) */
  79     EXTENSION_PLAYING_CHANGED, /**< arg1: extension_t*, arg2 int( playing status ) */
  80     EXTENSION_META_CHANGED,   /**< arg1: extension_t*, arg2 (input_item_t*) */
  81 };
  82
  83 /**
  84  * Control function for extensions.
  85  * Every GUI -> extension command will go through this function.
  86  **/
  87 static inline int extension_Control( extensions_manager_t *p_mgr,
  88                                      int i_control, ... )
  89 {
  90     va_list args;
  91     va_start( args, i_control );
  92     int i_ret = p_mgr->pf_control( p_mgr, i_control, args );
  93     va_end( args );
  94     return i_ret;
  95 }
  96
  97 /**
  98  * Helper for extension_HasMenu, extension_IsActivated...
  99  * Do not use.
 100  **/
 101 static inline bool __extension_GetBool( extensions_manager_t *p_mgr,
 102                                         extension_t *p_ext,
 103                                         int i_flag,
 104                                         bool b_default )
 105 {
 106     bool b = b_default;
 107     int i_ret = extension_Control( p_mgr, i_flag, p_ext, &b );
 108     if( i_ret != VLC_SUCCESS )
 109         return b_default;
 110     else
 111         return b;
 112 }
 113
 114 /** Activate or trigger an extension */
 115 #define extension_Activate( mgr, ext ) \
 116         extension_Control( mgr, EXTENSION_ACTIVATE, ext )
 117
 118 /** Trigger the extension. Attention: NOT multithreaded! */
 119 #define extension_Trigger( mgr, ext ) \
 120         extension_Control( mgr, EXTENSION_TRIGGER, ext )
 121
 122 /** Deactivate an extension */
 123 #define extension_Deactivate( mgr, ext ) \
 124         extension_Control( mgr, EXTENSION_DEACTIVATE, ext )
 125
 126 /** Is this extension activated? */
 127 #define extension_IsActivated( mgr, ext ) \
 128         __extension_GetBool( mgr, ext, EXTENSION_IS_ACTIVATED, false )
 129
 130 /** Does this extension have a sub-menu? */
 131 #define extension_HasMenu( mgr, ext ) \
 132         __extension_GetBool( mgr, ext, EXTENSION_HAS_MENU, false )
 133
 134 /** Get this extension's sub-menu */
 135 static inline int extension_GetMenu( extensions_manager_t *p_mgr,
 136                                      extension_t *p_ext,
 137                                      char ***pppsz,
 138                                      uint16_t **ppi )
 139 {
 140     return extension_Control( p_mgr, EXTENSION_GET_MENU, p_ext, pppsz, ppi );
 141 }
 142
 143 /** Trigger an entry of the extension menu */
 144 static inline int extension_TriggerMenu( extensions_manager_t *p_mgr,
 145                                          extension_t *p_ext,
 146                                          uint16_t i )
 147 {
 148     return extension_Control( p_mgr, EXTENSION_TRIGGER_MENU, p_ext, i );
 149 }
 150
 151 /** Trigger an entry of the extension menu */
 152 /* TODO: use player */
 153 static inline int extension_SetInput( extensions_manager_t *p_mgr,
 154                                       extension_t *p_ext, input_item_t *p_item )
 155 {
 156     return extension_Control( p_mgr, EXTENSION_SET_INPUT, p_ext, p_item );
 157 }
 158
 159 static inline int extension_PlayingChanged( extensions_manager_t *p_mgr,
 160                                             extension_t *p_ext,
 161                                             int state )
 162 {
 163     return extension_Control( p_mgr, EXTENSION_PLAYING_CHANGED, p_ext, state );
 164 }
 165
 166 static inline int extension_MetaChanged( extensions_manager_t *p_mgr,
 167                                          extension_t *p_ext )
 168 {
 169     return extension_Control( p_mgr, EXTENSION_META_CHANGED, p_ext );
 170 }
 171
 172 /** Can this extension only be triggered but not activated?
 173     Not compatible with HasMenu */
 174 #define extension_TriggerOnly( mgr, ext ) \
 175         __extension_GetBool( mgr, ext, EXTENSION_TRIGGER_ONLY, false )
 176
 177
 178 /*****************************************************************************
 179  * Extension dialogs
 180  *****************************************************************************/
 181
 182 typedef struct extension_dialog_t extension_dialog_t;
 183 typedef struct extension_widget_t extension_widget_t;
 184
 185 /// User interface event types
 186 typedef enum
 187 {
 188     EXTENSION_EVENT_CLICK,       ///< Click on a widget: data = widget
 189     EXTENSION_EVENT_CLOSE,       ///< Close the dialog: no data
 190     // EXTENSION_EVENT_SELECTION_CHANGED,
 191     // EXTENSION_EVENT_TEXT_CHANGED,
 192 } extension_dialog_event_e;
 193
 194 /// Command to pass to the extension dialog owner
 195 typedef struct
 196 {
 197     extension_dialog_t *p_dlg;      ///< Destination dialog
 198     extension_dialog_event_e event; ///< Event, @see extension_dialog_event_e
 199     void *p_data;                   ///< Opaque data to send
 200 } extension_dialog_command_t;
 201
 202
 203 /// Dialog descriptor for extensions
 204 struct extension_dialog_t
 205 {
 206     vlc_object_t *p_object;      ///< Owner object (callback on "dialog-event")
 207
 208     char *psz_title;             ///< Title for the Dialog (in TitleBar)
 209     int i_width;                 ///< Width hint in pixels (may be discarded)
 210     int i_height;                ///< Height hint in pixels (may be discarded)
 211
 212     DECL_ARRAY(extension_widget_t*) widgets; ///< Widgets owned by the dialog
 213
 214     bool b_hide;                 ///< Hide this dialog (!b_hide shows)
 215     bool b_kill;                 ///< Kill this dialog
 216
 217     void *p_sys;                 ///< Dialog private pointer
 218     void *p_sys_intf;            ///< GUI private pointer
 219     vlc_mutex_t lock;            ///< Dialog mutex
 220     vlc_cond_t cond;             ///< Signaled == UI is done working on the dialog
 221 };
 222
 223 /** Send a command to an Extension dialog
 224  * @param p_dialog The dialog
 225  * @param event @see extension_dialog_event_e for a list of possible events
 226  * @param data Optional opaque data,  @see extension_dialog_event_e
 227  * @return VLC error code
 228  **/
 229 static inline int extension_DialogCommand( extension_dialog_t* p_dialog,
 230                                            extension_dialog_event_e event,
 231                                            void *data )
 232 {
 233     extension_dialog_command_t command;
 234     command.p_dlg = p_dialog;
 235     command.event = event;
 236     command.p_data = data;
 237     var_SetAddress( p_dialog->p_object, "dialog-event", &command );
 238     return VLC_SUCCESS;
 239 }
 240
 241 /** Close the dialog
 242  * @param dlg The dialog
 243  **/
 244 #define extension_DialogClosed( dlg ) \
 245         extension_DialogCommand( dlg, EXTENSION_EVENT_CLOSE, NULL )
 246
 247 /** Forward a click on a widget
 248  * @param dlg The dialog
 249  * @param wdg The widget (button, ...)
 250  **/
 251 #define extension_WidgetClicked( dlg, wdg ) \
 252         extension_DialogCommand( dlg, EXTENSION_EVENT_CLICK, wdg )
 253
 254 /// Widget types
 255 typedef enum
 256 {
 257     EXTENSION_WIDGET_LABEL,      ///< Text label
 258     EXTENSION_WIDGET_BUTTON,     ///< Clickable button
 259     EXTENSION_WIDGET_IMAGE,      ///< Image label (psz_text is local URI)
 260     EXTENSION_WIDGET_HTML,       ///< HTML or rich text area (non editable)
 261     EXTENSION_WIDGET_TEXT_FIELD, ///< Editable text line for user input
 262     EXTENSION_WIDGET_PASSWORD,   ///< Editable password input (******)
 263     EXTENSION_WIDGET_DROPDOWN,   ///< Drop-down box
 264     EXTENSION_WIDGET_LIST,       ///< Vertical list box (of strings)
 265     EXTENSION_WIDGET_CHECK_BOX,  ///< Checkable box with label
 266     EXTENSION_WIDGET_SPIN_ICON,  ///< A "loading..." spinning icon
 267 } extension_widget_type_e;
 268
 269 /// Widget descriptor for extensions
 270 struct extension_widget_t
 271 {
 272     /* All widgets */
 273     extension_widget_type_e type; ///< Type of the widget
 274     char *psz_text;               ///< Text. May be NULL or modified by the UI
 275
 276     /* Drop-down & List widgets */
 277     struct extension_widget_value_t {
 278         int i_id;          ///< Identifier for the extension module
 279                            ///< (weird behavior may occur if not unique)
 280         char *psz_text;    ///< String value
 281         bool b_selected;   ///< True if this item is selected
 282         struct extension_widget_value_t *p_next; ///< Next value or NULL
 283     } *p_values;                  ///< Chained list of values (Drop-down/List)
 284
 285     /* Check-box */
 286     bool b_checked;               ///< Is this entry checked
 287
 288     /* Layout */
 289     int i_row;                    ///< Row in the grid
 290     int i_column;                 ///< Column in the grid
 291     int i_horiz_span;             ///< Horizontal size of the object
 292     int i_vert_span;              ///< Vertical size of the object
 293     int i_width;                  ///< Width hint
 294     int i_height;                 ///< Height hint
 295     bool b_hide;                  ///< Hide this widget (make it invisible)
 296
 297     /* Spinning icon */
 298     int i_spin_loops;             ///< Number of loops to play (-1 = infinite,
 299                                   ///< 0 = stop animation)
 300
 301     /* Orders */
 302     bool b_kill;                  ///< Destroy this widget
 303     bool b_update;                ///< Update this widget
 304
 305     /* Misc */
 306     void *p_sys;                  ///< Reserved for the extension manager
 307     void *p_sys_intf;             ///< Reserved for the UI, but:
 308                                   ///< NULL means the UI has destroyed the widget
 309                                   ///< or has not created it yet
 310     extension_dialog_t *p_dialog; ///< Parent dialog
 311 };
 312
 313 #endif /* VLC_EXTENSIONS_H */