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 attributes 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_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_STREAMPOS:
 104    Not supported yet.
 105
 106  - VLC_VOLUME_CHANGE:
 107    Action    : change sound volume.
 108    Parameters:
 109      1: - VLC_VOLUME_MUTE: switch to mute mode.
 110         - VLC_VOLUME_UP: raise sounds volume.
 111         - VLC_VOLUME_DOWN:
 112         - VLC_VOLUME_SET: set sound volume to second parameter
 113      2: if first parameter is VLC_VOLUME_SET only, an integer between 0 and 100.
 114
 115  - VLC_PLAYLIST_ADD_FILE:
 116    Action    : Open an "open file dialog box" to add files to playlist.
 117    Parameters: none.
 118
 119  - VLC_WINDOW_MOVE:
 120    Action    : initiate manual window movement.
 121    Parameters: only one which must match the ID of a window. It should be
 122                used with image controls.
 123
 124  - VLC_WINDOW_OPEN:
 125    Action    : open a window with a fading effect if selected.
 126    Parameters:
 127      1: ID of the window to open.
 128      2: Describe what to do. Nothing is opening. 'TRUE' is the same. 'FALSE' is
 129         closing window. 'CHANGE' is switching between these two states.
 130
 131  - VLC_WINDOW_CLOSE:
 132    Action    : close a window with a fading effect if selected.
 133    Parameters:
 134      1: ID of the window to close.
 135      2: Describe what to do. Nothing is closing. 'TRUE' is the same. 'FALSE' is
 136         opening window. 'CHANGE' is switching between these two states.
 137
 138  - CTRL_SET_SLIDER:
 139    Not supported yet.
 140
 141  - CTRL_SET_TEXT:
 142    Not supported yet.
 143
 144  - CTRL_ID_VISIBLE:
 145    Action    : hide/show a control.
 146    Parameters:
 147      1: ID of the control to hide/show.
 148      2: Describe what to do. Nothing is showing control. 'TRUE' is the same.
 149         'FALSE' is hiding control. 'CHANGE' is switching between these two
 150         states.
 151
 152  - CTRL_ID_ENABLED:
 153    Not supported yet.
 154
 155  - CTRL_ID_MOVE:
 156    Action    : moves a control.
 157    Parameters:
 158      1: ID of the control to move.
 159      2: horizontal offset of movement.
 160      3: vertical offset of movement.
 161
 162  - PLAYLIST_ID_DEL:
 163    Action    : remove items from playlist.
 164    Parameters:
 165      1: ID of the playlist.
 166
 167
 168 What to do with events ?
 169 =======================
 170
 171 When creating your event, you must assign an ID to each of them.
 172 Now you have to associate events with controls.
 173 Some attributes of some controls are supposed to be filled with those IDs. That
 174 is to say that when the action corresponding to the attribute will be done,
 175 the event associated will be executed. The best exemple is assigning an event
 176 to the 'onclick' attribute of a button control. The event will be executed when
 177 clicking on the button.
 178 You can execute several events. To do this you just have to separate them with
 179 semicolon.
 180 Exemple:
 181   <ButtonControl [...] onclick="event1;event2;event3"/>
 182
 183
 184 Do I have to create every event for each skin ?
 185 ===============================================
 186
 187 No, a set of predefined events are present. Here they are with their ID and
 188 shortcut.
 189
 190   ID           Shortcut     Description
 191
 192   tray                      Hide or show in the system tray.
 193   taskbar      CTRL+B       Hide or show in the taskbar.
 194   play         X            Play.
 195   pause        C            Pause.
 196   stop         V            Stop.
 197   next         B            Next file.
 198   prev         Z            Previous file.
 199   fullscreen   F            Switch to fullscreen mode.
 200   mute                      Mute the sound.
 201   volume_up
 202   volume_down
 203   quit         CTRL+C       Quit VLC.
 204   open         CTRL+O       Open a file.
 205   add_file     CTRL+A       Add a file.
 206   load_skin    CTRL+S       Change skin.
 207   on_top       CTRL+T       Toggle the "Always on top" status
 208   show_prefs                Show the preferences dialog box.
 209   show_info                 Show the FileInfo dialog box.
 210   show_log                  Show the Messages dialog box.
 211   hide_log                  Hide the Messages dialog box.
 212