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 general purpose about 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 attibutes 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 followings
  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 playing file to fullscreen mode.
  77    Parameters: none.
  78
  79  - VLC_PLAY:
  80    Action    : play stream.
  81    Parameters: none.
  82
  83  - VLC_STOP:
  84    Action    : stop playing stream.
  85    Parameters: none.
  86
  87  - VLC_PAUSE:
  88    Action    : pause the stream.
  89    Parameters: none.
  90
  91  - VLC_NEXT:
  92    Action    : go to next file in playlist.
  93    Parameters: none.
  94
  95  - VLC_PREV:
  96    Action    : go to previous file in 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 this to state.
 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 this to state.
 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. FALSE
 145         is hiding control. CHANGE is switching between this to state.
 146
 147  - CTRL_ID_ENABLED:
 148    Not supported yet.
 149
 150  - CTRL_ID_MOVE:
 151    Action    : moves a control.
 152    Parameters:
 153      1: ID of the control to move.
 154      2: horizontal offset of movement.
 155      3: vertical offset of movement.
 156
 157  - PLAYLIST_ID_DEL:
 158    Action    : remove items from playlist.
 159    Parameters:
 160      1: ID of the playlist.
 161
 162
 163 What to do with event ?
 164 =======================
 165
 166 When creating your event, you must assign an ID to each of them.
 167 Now you have to associate events with controls.
 168 Some attributes of some controls are supposed to be filled with those IDs. That
 169 is to say that when the action correspounding to the attribute will be done,
 170 the event associated will be executed. The best exemple is assigning an event
 171 to the 'onclick' attribute of a button control. The event will be executed when
 172 clicking on the button.
 173 You can execute several events. To do this you just have to separate them with
 174 semicolon.
 175 Exemple:
 176   <ButtonControl [...] onclick="event1;event2;event3"/>
 177
 178
 179 Do I have to create every event for each skin ?
 180 ===============================================
 181
 182 No, a set of predefined events are present. Here they are with their ID and
 183 shortcut.
 184
 185   ID           Shortcut     Description
 186
 187   tray         CTRL+T       Hide or show in the system tray.
 188   taskbar      CTRL+B       Hide or show in the taskbar.
 189   play         X            Play.
 190   pause        C            Pause.
 191   stop         V            Stop.
 192   next         B            Next file.
 193   prev         Z            Previous file.
 194   fullscreen   F            Switch to fullscreen mode.
 195   mute                      Mute the sound.
 196   volume_up
 197   volume_down
 198   quit         CTRL+C       Quit VLC.
 199   open         CTRL+O       Open a file.
 200   add_file     CTRL+A       Add a file.
 201   load_skin    CTRL+S       Change skin.
 202