doc/skins/events-howto.txt

   1 Before reading this document, you should first take a look at skins-howto.txt
   2 to understand the general functioning of VLC skins.
   3
   4 What is an event ?
   5 ==================
   6
   7 Events are the dynamic part of the skins. It means that beyond visual aspect,
   8 the interface must react with the user actions. An event describes a simple
   9 interaction, in fact one simple action such as playing a file, hiding a
  10 window...
  11 So when designing a skin you will have to specify what those interactions are.
  12 For this you will use simple actions that are described in event tags and you
  13 would be able to add them and associate them to controls.
  14
  15 How to create an event ?
  16 ========================
  17
  18 An event describes a simple action as seen above.
  19 All attributes are explained in the 'skins-howto.txt' file except the 'event'
  20 attribute which is a bit special.
  21 In the 'event' attribute you will enter a simple script with the following
  22 syntax :
  23   "EVENT(parameter1,parameter2,...)"
  24
  25 The number of parameters depends on EVENT.
  26 All this is case sensitive.
  27 Don't add spaces.
  28 EVENT is the action to execute, it can be one of the following:
  29
  30  - VLC_NOTHING:
  31    Action    : none, it executes nothing so don't use it !
  32    Parameters: none.
  33
  34  - VLC_SHOW:
  35    Action    : Open all windows of the interface with a fading effect if
  36                selected.
  37    Parameters: none.
  38
  39  - VLC_HIDE:
  40    Action    : Close all windows of the interface with a fading effect if
  41                selected.
  42    Parameters:
  43      - First 1 is an EVENT to execute when all windows have been closed.
  44
  45  - VLC_QUIT:
  46    Action    : Quit the interface
  47    Parameters: none.
  48
  49  - VLC_OPEN:
  50    Action    : Open an "open file dialog box" to open a file to play.
  51    Parameters: none.
  52
  53  - VLC_LOAD_SKIN:
  54    Action    : Open an "open file dialog box" to change the current skin.
  55    Parameters: none.
  56
  57  - VLC_ON_TOP:
  58    Action    : Toggle the "Always on top" status
  59    Parameters: none.
  60
  61  - VLC_LOG_SHOW:
  62    Not supported yet
  63
  64  - VLC_LOG_CLEAR:
  65    Not supported yet.
  66
  67  - VLC_INTF_REFRESH:
  68    Action    : Force refreshing of the interface.
  69    Parameters: none.
  70
  71  - VLC_CHANGE_TRAY:
  72    Action    : if VLC is not visible in system tray, show it, else hide it.
  73    Parameters: none.
  74
  75  - VLC_CHANGE_TASKBAR:
  76    Action    : if VLC is not visible in taskbar, show it, else hide it.
  77    Parameters: none.
  78
  79  - VLC_FULLSCREEN:
  80    Action    : switch current playlist item to fullscreen mode.
  81    Parameters: none.
  82
  83  - VLC_PLAY:
  84    Action    : play the stream.
  85    Parameters: none.
  86
  87  - VLC_STOP:
  88    Action    : stop the stream.
  89    Parameters: none.
  90
  91  - VLC_PAUSE:
  92    Action    : pause the stream.
  93    Parameters: none.
  94
  95  - VLC_NEXT:
  96    Action    : go to the next file in the playlist.
  97    Parameters: none.
  98
  99  - VLC_PREV:
 100    Action    : go to the previous file in the playlist.
 101    Parameters: none.
 102
 103  - VLC_SLOWER:
 104    Action    : play the stream slower.
 105    Parameters: none.
 106
 107  - VLC_FASTER:
 108    Action    : play the stream faster.
 109    Parameters: none.
 110
 111  - VLC_STREAMPOS:
 112    Not supported yet.
 113
 114  - VLC_VOLUME_CHANGE:
 115    Action    : change sound volume.
 116    Parameters:
 117      1: - VLC_VOLUME_MUTE: switch to mute mode.
 118         - VLC_VOLUME_UP: raise sounds volume.
 119         - VLC_VOLUME_DOWN:
 120         - VLC_VOLUME_SET: set sound volume to second parameter
 121      2: if first parameter is VLC_VOLUME_SET only, an integer between 0 and 100.
 122
 123  - VLC_PLAYLIST_ADD_FILE:
 124    Action    : Open an "open file dialog box" to add files to playlist.
 125    Parameters: none.
 126
 127  - VLC_WINDOW_MOVE:
 128    Action    : initiate manual window movement.
 129    Parameters: only one which must match the ID of a window. It should be
 130                used with image controls.
 131
 132  - VLC_WINDOW_OPEN:
 133    Action    : open a window with a fading effect if selected.
 134    Parameters:
 135      1: ID of the window to open.
 136      2: Describe what to do. Nothing is opening. 'TRUE' is the same. 'FALSE' is
 137         closing window. 'CHANGE' is switching between these two states.
 138
 139  - VLC_WINDOW_CLOSE:
 140    Action    : close a window with a fading effect if selected.
 141    Parameters:
 142      1: ID of the window to close.
 143      2: Describe what to do. Nothing is closing. 'TRUE' is the same. 'FALSE' is
 144         opening window. 'CHANGE' is switching between these two states.
 145
 146  - CTRL_SET_SLIDER:
 147    Not supported yet.
 148
 149  - CTRL_SET_TEXT:
 150    Not supported yet.
 151
 152  - CTRL_ID_VISIBLE:
 153    Action    : hide/show a control.
 154    Parameters:
 155      1: ID of the control to hide/show.
 156      2: Describe what to do. Nothing is showing control. 'TRUE' is the same.
 157         'FALSE' is hiding control. 'CHANGE' is switching between these two
 158         states.
 159
 160  - CTRL_ID_ENABLED:
 161    Not supported yet.
 162
 163  - CTRL_ID_MOVE:
 164    Action    : moves a control.
 165    Parameters:
 166      1: ID of the control to move.
 167      2: horizontal offset of movement.
 168      3: vertical offset of movement.
 169
 170  - PLAYLIST_ID_DEL:
 171    Action    : remove items from playlist.
 172    Parameters:
 173      1: ID of the playlist.
 174
 175
 176 What to do with events ?
 177 =======================
 178
 179 When creating your event, you must assign an ID to each of them.
 180 Now you have to associate events with controls.
 181 Some attributes of some controls are supposed to be filled with those IDs. That
 182 is to say that when the action corresponding to the attribute will be done,
 183 the event associated will be executed. The best example is assigning an event
 184 to the 'onclick' attribute of a button control. The event will be executed when
 185 clicking on the button.
 186 You can execute several events. To do this you just have to separate them with
 187 semicolon.
 188 Example:
 189   <ButtonControl [...] onclick="event1;event2;event3"/>
 190
 191
 192 Do I have to create every event for each skin ?
 193 ===============================================
 194
 195 No, a set of predefined events are present. Here they are with their ID and
 196 shortcut.
 197
 198   ID           Shortcut     Description
 199
 200   tray                      Hide or show in the system tray.
 201   taskbar      CTRL+B       Hide or show in the taskbar.
 202   play         X            Play.
 203   pause        C            Pause.
 204   stop         V            Stop.
 205   next         B            Next file.
 206   prev         Z            Previous file.
 207   slow                      Play slower.
 208   fast                      Play faster.
 209   fullscreen   F            Switch to fullscreen mode.
 210   mute                      Mute the sound.
 211   volume_up
 212   volume_down
 213   quit         CTRL+C       Quit VLC.
 214   open         CTRL+O       Open a file.
 215   add_file     CTRL+A       Add a file.
 216   load_skin    CTRL+S       Change skin.
 217   on_top       CTRL+T       Toggle the "Always on top" status
 218   show_prefs                Show the preferences dialog box.
 219   show_info                 Show the FileInfo dialog box.
 220   show_log                  Show the Messages dialog box.
 221   hide_log                  Hide the Messages dialog box.
 222