git.sesse.net Git - vlc/blob - 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 attiributes are explained in the 'skins-howto.txt' file except the 'event'
  20 attribute wich 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_LOG_SHOW:
  58    Not supported yet
  59
  60  - VLC_LOG_CLEAR:
  61    Not supported yet.
  62
  63  - VLC_INTF_REFRESH:
  64    Action    : Force refreshing of the interface.
  65    Parameters: none.
  66
  67  - VLC_CHANGE_TRAY:
  68    Action    : if VLC is not visible in system tray, show it, else hide it.
  69    Parameters: none.
  70
  71  - VLC_CHANGE_TASKBAR:
  72    Action    : if VLC is not visible in taskbar, show it, else hide it.
  73    Parameters: none.
  74
  75  - VLC_FULLSCREEN:
  76    Action    : switch current playlist item to fullscreen mode.
  77    Parameters: none.
  78
  79  - VLC_PLAY:
  80    Action    : play the stream.
  81    Parameters: none.
  82
  83  - VLC_STOP:
  84    Action    : stop the stream.
  85    Parameters: none.
  86
  87  - VLC_PAUSE:
  88    Action    : pause the stream.
  89    Parameters: none.
  90
  91  - VLC_NEXT:
  92    Action    : go to the next file in the playlist.
  93    Parameters: none.
  94
  95  - VLC_PREV:
  96    Action    : go to the previous file in the playlist.
  97    Parameters: none.
  98
  99  - VLC_STREAMPOS:
 100    Not supported yet.
 101
 102  - VLC_VOLUME_CHANGE:
 103    Action    : change sound volume.
 104    Parameters:
 105      1: - VLC_VOLUME_MUTE: switch to mute mode.
 106         - VLC_VOLUME_UP: raise sounds volume.
 107         - VLC_VOLUME_DOWN:
 108         - VLC_VOLUME_SET: set sound volume to second parameter
 109      2: if first parameter is VLC_VOLUME_SET only, an integer between 0 and 100.
 110
 111  - VLC_PLAYLIST_ADD_FILE:
 112    Action    : Open an "open file dialog box" to add files to playlist.
 113    Parameters: none.
 114
 115  - VLC_WINDOW_MOVE:
 116    Action    : initiate manual window movement.
 117    Parameters: only one which must match the ID of a window. It should be
 118                used with image controls.
 119
 120  - VLC_WINDOW_OPEN:
 121    Action    : open a window with a fading effect if selected.
 122    Parameters:
 123      1: ID of the window to open.
 124      2: Describe what to do. Nothing is opening. 'TRUE' is the same. 'FALSE' is
 125         closing window. 'CHANGE' is switching between these two states.
 126
 127  - VLC_WINDOW_CLOSE:
 128    Action    : close a window with a fading effect if selected.
 129    Parameters:
 130      1: ID of the window to close.
 131      2: Describe what to do. Nothing is closing. 'TRUE' is the same. 'FALSE' is
 132         opening window. 'CHANGE' is switching between these two states.
 133
 134  - CTRL_SET_SLIDER:
 135    Not supported yet.
 136
 137  - CTRL_SET_TEXT:
 138    Not supported yet.
 139
 140  - CTRL_ID_VISIBLE:
 141    Action    : hide/show a control.
 142    Parameters:
 143      1: ID of the control to hide/show.
 144      2: Describe what to do. Nothing is showing control. 'TRUE' is the same.
 145         'FALSE' is hiding control. 'CHANGE' is switching between these two
 146         states.
 147
 148  - CTRL_ID_ENABLED:
 149    Not supported yet.
 150
 151  - CTRL_ID_MOVE:
 152    Action    : moves a control.
 153    Parameters:
 154      1: ID of the control to move.
 155      2: horizontal offset of movement.
 156      3: vertical offset of movement.
 157
 158  - PLAYLIST_ID_DEL:
 159    Action    : remove items from playlist.
 160    Parameters:
 161      1: ID of the playlist.
 162
 163
 164 What to do with events ?
 165 =======================
 166
 167 When creating your event, you must assign an ID to each of them.
 168 Now you have to associate events with controls.
 169 Some attributes of some controls are supposed to be filled with those IDs. That
 170 is to say that when the action corresponding to the attribute will be done,
 171 the event associated will be executed. The best exemple is assigning an event
 172 to the 'onclick' attribute of a button control. The event will be executed when
 173 clicking on the button.
 174 You can execute several events. To do this you just have to separate them with
 175 semicolon.
 176 Exemple:
 177   <ButtonControl [...] onclick="event1;event2;event3"/>
 178
 179
 180 Do I have to create every event for each skin ?
 181 ===============================================
 182
 183 No, a set of predefined events are present. Here they are with their ID and
 184 shortcut.
 185
 186   ID           Shortcut     Description
 187
 188   tray         CTRL+T       Hide or show in the system tray.
 189   taskbar      CTRL+B       Hide or show in the taskbar.
 190   play         X            Play.
 191   pause        C            Pause.
 192   stop         V            Stop.
 193   next         B            Next file.
 194   prev         Z            Previous file.
 195   fullscreen   F            Switch to fullscreen mode.
 196   mute                      Mute the sound.
 197   volume_up
 198   volume_down
 199   quit         CTRL+C       Quit VLC.
 200   open         CTRL+O       Open a file.
 201   add_file     CTRL+A       Add a file.
 202   load_skin    CTRL+S       Change skin.
 203