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: only one which must match the ID of a window.
 123
 124  - VLC_WINDOW_CLOSE:
 125    Action    : close a window with a fading effect if selected.
 126    Parameters: only one who must match the ID of a window.
 127
 128  - CTRL_SET_SLIDER:
 129    Not supported yet.
 130
 131  - CTRL_SET_TEXT:
 132    Not supported yet.
 133
 134  - CTRL_ID_VISIBLE:
 135    Action    : hide/show a control.
 136    Parameters:
 137      1: ID of the control to hide/show.
 138      2: Describe what to do. Nothing is showing control. TRUE is the same. FALSE
 139         is hiding control. CHANGE is switching between this to state.
 140
 141  - CTRL_ID_ENABLED:
 142    Not supported yet.
 143
 144  - CTRL_ID_MOVE:
 145    Action    : moves a control.
 146    Parameters:
 147      1: ID of the control to move.
 148      2: horizontal offset of movement.
 149      3: vertical offset of movement.
 150
 151  - PLAYLIST_ID_DEL:
 152    Action    : remove items from playlist.
 153    Parameters:
 154      1: ID of the playlist.
 155
 156
 157 What to do with event ?
 158 =======================
 159
 160 When creating your event, you must assign an ID to each of them.
 161 Now you have to associate events with controls.
 162 Some attributes of some controls are supposed to be filled with those IDs. That
 163 is to say that when the action correspounding to the attribute will be done,
 164 the event associated will be executed. The best exemple is assigning an event
 165 to the 'onclick' attribute of a button control. The event will be executed when
 166 clicking on the button.
 167 You can execute several events. To do this you just have to separate them with
 168 semicolon.
 169 Exemple:
 170   <ButtonControl [...] onclick="event1;event2;event3"/>
 171
 172
 173 Do I have to create every event for each skin ?
 174 ===============================================
 175
 176 No, a set of predefined events are present. Here they are with their ID and
 177 shortcut.
 178
 179   ID           Shortcut     Description
 180
 181   tray         CTRL+T       Hide or show in the system tray.
 182   taskbar      CTRL+B       Hide or show in the taskbar.
 183   play         X            Play.
 184   pause        C            Pause.
 185   stop         V            Stop.
 186   next         B            Next file.
 187   prev         Z            Previous file.
 188   fullscreen   F            Switch to fullscreen mode.
 189   mute                      Mute the sound.
 190   volume_up
 191   volume_down
 192   quit         CTRL+C       Quit VLC.
 193   open         CTRL+O       Open a file.
 194   add_file     CTRL+A       Add a file.
 195   load_skin    CTRL+S       Change skin.
 196