doc/skins/skins-howto.txt

   1 Note: This document is short and highly incomplete. If you want to write a new,
   2 decent one, it will be more than welcome!
   3
   4
   5
   6 Basic principles
   7 ================
   8
   9 A skin (or theme, the two words have almost the same meaning) for VLC is made
  10 of many BMP files (Windows Bitmap format) containing all the images needed, and
  11 of an XML file describing how these images should be displayed, what happens
  12 when the user clicks on a button, etc.
  13
  14 Those of you who have already done skins for other softwares shouldn't have too
  15 many difficulties to understand how all this works.
  16
  17
  18
  19 Bezier curves
  20 =============
  21
  22 One cool thing with VLC sliders is that they are not necessarily rectilinear,
  23 but they can follow any Bezier curve. So if you want to have a slider moving
  24 on a half-circle, or even doing a loop, you can !
  25
  26 This is not the place to explain how these curves work, the only thing to know
  27 is that a Bezier curve can be caracterised by a set of points. Once you have
  28 them (thanks to the graphical utility presented at the end of this file, for
  29 example), you just need to enter the list of abscissas in the 'abs' attribute
  30 and the list of ordinates (in the same order...) in the 'ord' attribute. The
  31 separator is the coma. Example: abs="2,45,88" ord="50,120,50"
  32
  33 Bezier curves are used for the SliderControl and the PlaylistControl tags.
  34
  35
  36
  37 The bitmaps
  38 ===========
  39
  40 Basically, you need one bitmap file by state of control. For example, with a
  41 image control you'll need 1 image, with a button 2 images (or 3 if you provide
  42 the disabled state). A slider will also need 2, one for the static part and
  43 another for the mobile part. Of course, the same bitmap file can be used for
  44 many controls, provided you want to display the same image!
  45
  46 The bitmap format doesn't allow a transparent color, but in the XML file you
  47 can specify a color that will be considered as transparent wherever it appears
  48 in the bitmap file.
  49
  50
  51
  52 The XML file
  53 ============
  54
  55 XML is a markup language, like HTML. It won't be explained here any further,
  56 please use Google if you don't know what is XML. You'll see, it's rather easy
  57 to understand.
  58
  59 The XML file used for the VLC skins follows a predefined DTD. You can find this
  60 DTD in VLC CVS, and its reading is strongly advised, since it contains most of
  61 the default values used for the parameters. A skin that doesn't follow the DTD
  62 with which VLC was compiled won't be loaded by VLC (and it might even crash
  63 it...).
  64
  65 For a better comprehension of what follows, you should have a look at the DTD
  66 (in modules/gui/skin/parser/dkin.dtd) and/or at an example of valid xml skin
  67 (such as modules/gui/skin/skins/default/theme.xml).
  68
  69 OK, let's go for an enumeration of the different tags and theor attributes :
  70
  71  - Theme: The main tag.
  72    Attributes:
  73      - magnet: allows to select the range of action (in pixels) of magnetism
  74        with border of screen : that is to say when the distance between the
  75        border of the screen and a window is less than this value, the window
  76        will stick to the border. 0 means no magnetism.
  77        Default is "9".
  78
  79  - ThemeInfo: You can enter here some information about you (but this
  80    information is currently unused by VLC...)
  81    Attributes :
  82      - name: not yet supported.
  83      - author: not yet supported.
  84      - email: not yet supported.
  85      - webpage: not yet supported.
  86
  87  - Bitmap: Associates a bitmap file with a name (=identifiant) that will be
  88    used by the various controls. Obviously, you need one Bitmap tag for each
  89    bitmap file you have.
  90    Attributes:
  91      - id: this is the name of the bitmap that will be used with controls
  92        (2 bitmaps shouldn't have the same name).
  93      - alphacolor: this is the transparency color of the bitmap. It must be
  94        indicated with the following format: "#RRGGBB" (where RR stands for the
  95        hexadecimal value of the red component, GG for the green one, and BB for
  96        the blue one).
  97      - file: this attribute is used to indicate the path and name of the bitmap
  98        file used. This path can be absolute (but you should avoid it as often as
  99        possible), or relative to the path of the xml file.
 100
 101  - Event: An action that will be associated to a control later.
 102    Attributes :
 103      - id: this is the name of the event that will be used with controls.
 104        (2 events shouldn't have the same name).
 105      - event: see events-howto.txt
 106      - key: this is the shortcut key associated with the event. This means that
 107        the event will be executed when hitting the correspounding key. It must
 108        be indicated with the following format : "MOD+L" where "MOD" is the
 109        modifier key ("CTRL" or "ALT") and "L" is the letter in uppercase
 110        ("MOD+" is optionnal).
 111        Default is "none".
 112
 113  - Font: Declares a font to be used in a TextControl or PlaylistControl.
 114    Attributes :
 115       - id: this is the name of the font that will be used with controls.
 116         Default is "default". (2 fonts shouldn't have the same name).
 117       - font: this is the name of the font
 118         Default is "arial".
 119       - size: this is the size of the font in points (pt).
 120         Default is "12".
 121       - color: this is the color of the font with the following format,
 122         "#RRGGBB" (see Bitmap).
 123         Default is "#000000" (black).
 124       - weight: this is the weight of the font. It must be between 0 and 1000
 125         Default is "400" (normal weight). Fewer is thinner...
 126       - italic: sets if the font must be in italic format.
 127         Default is "false".
 128       - underline: sets if the font must be underlined.
 129         Default is "false".
 130
 131  - Window: A window that will appear on screen.
 132       - id: this is the name of the window (it will be only used for events
 133         but it is important: 2 windows shouldn't have the same name).
 134       - visible: sets if the window should appear or not at the launch of VLC.
 135         Default is "true".
 136       - x: sets the left position of the window.
 137         Default is "0".
 138       - y: sets the top position of the window.
 139         Default is "0".
 140       - fadetime: sets the time in milliseconds of the hide/show fading
 141         transition.
 142         Default is "500".
 143       - alpha: sets the transparency of the window. It must be between 1 and
 144         255. 1 is nearly total transaprency and should be avoided. 255 is total
 145         opacity.
 146         Default is "255". You should use high values.
 147       - movealpha: sets the transparency of the window when the window is
 148         moving. Same range as alpha.
 149         Default is "255".
 150       - dragdrop: sets if drag and drop of media files is allowed in this
 151         window.
 152         Default is "true".
 153       - playondrop: sets if a drop file is played directly (true) or only
 154         enqueud (false). This has no effect if dragdrop is set to "false".
 155         Default is "true".
 156
 157  - ControlGroup: Adds an offset to the elements it contains. A ControlGroup is
 158    only supposed to ease the job of the skin designer, who can adjust the
 159    position of a group of controls without modifying all the coordinates, but
 160    you can ignore it if you want (only one ControlGroup is necessary, just
 161    inside Window). ControlGroup tags can be nested.
 162    Attributes :
 163      - x: try and guess.
 164        Default is "0".
 165      - y: what do you think ?
 166        Default is "0".
 167
 168  - Anchor: Creates a "magnetic point" in the current Window. If an anchor of
 169    another Window enters in the range of action of this anchor, the 2 anchors
 170    will automatically be on the same place, and the windows are "sticked". Each
 171    anchor has a priority ('priority' attribute), and the anchor with the
 172    highest priority is the winner, which means that when moving its Window all
 173    the other anchored Windows will move too. To break the effect of 2 linked
 174    anchors, you need to move the Window whose anchor has the lower priority.
 175    Attributes :
 176      - x: is it really necessary to explain ?
 177        Default is "0".
 178      - y: ...
 179        Default is "0".
 180      - priority: priority of anchor (see the previous description).
 181        No default, must de defined!
 182      - range: Range of action of the anchor in pixels.
 183        Default is "10".
 184
 185  - ImageControl, ButtonControl, CheckBoxControl, TextControl, SliderControl,
 186    PlaylistControl: The various visual controls that constitute a Window. They
 187    share some properties: 'x' and 'y' for the position, 'visible' for the
 188    initial state, 'id' for identifying them (only needed if you want to create
 189    an event acting on this particular control) and 'help' for a short
 190    description of the control that could be displayed in a special TextControl
 191    (see below). All the controls can also accept events, and you have the
 192    possibility to associate many events to a control at once, separing them
 193    with semicolons.
 194
 195  - ImageControl: Creates a simple image. Useful for backgrounds.
 196      - image: this attribute must be set to an identifiant of a Bitmap tag.
 197      - onclick: the 'event' attribute can be used to associate an event to the
 198        image (the event is triggered by a click on the image).
 199        Typical use: an Event made with 'WINDOW_MOVE(window)' (where 'window' is
 200        the id of a Window) can be associated to an ImageControl of this
 201        Window. Hence the Window can be moved via the image...
 202
 203  - ButtonControl: Creates a button.
 204      - up: identifiant of a Bitmap. Used for drawing the up state of the
 205        button.
 206      - down: identifiant of a Bitmap. Used for drawing the down state of the
 207        button.
 208      - disabled : identifiant of a Bitmap. Used for drawing the disabled state
 209        of the button.
 210      - onclick: event executed when clicking on the button.
 211        Default is "none".
 212      - onmouseover: event executed when the mouse cursor enters the button.
 213        Default is "none".
 214      - onmouseout: event executed when the mouse cursor leaves the button.
 215        Default is "none".
 216      - tooltiptext : used to display a tooltip.
 217        Default is "none" (no tooltip).
 218
 219  - CheckBoxControl: Creates a checkbox, i.e. a button with 2 states
 220    (checked/unchecked). So you need 6 images for a full-featured checkbox: each
 221    state has a basic image, an image corresponding to a click not yet released,
 222    and an image for the disabled control. If you supply only the basic images,
 223    the other ones will be identical.
 224    Attributes:
 225      - img1: identifiant of a Bitmap. Used for drawing control in state 1.
 226      - clickimg1: identifiants of a bitmap. Used for drawing control when
 227        clicking on it in state 1.
 228        Default is the value of 'img1' attribute.
 229      - img2: identifiant of a Bitmap. Used for drawing control in state 2.
 230      - clickimg2: identifiant of a Bitmap. Used for drawing control when
 231        clicking on it in state 2.
 232        Default is the value of 'img2' attribute.
 233      - disabled1: identifiant of a Bitmap. Used for drawing control in state 1
 234        when disabling.
 235        Default is the value of 'img1' attribute.
 236      - disabled2: identifiant of a Bitmap. Used for drawing control in state 1
 237        when disabling.
 238        Default is the value of 'img2' attribute.
 239      - onclick1: event executed when clicking on the control in state 1.
 240        Default is "none".
 241      - onclick2: event executed when clicking on the control in state 2.
 242        Default is "none".
 243      - onmouseover1: event executed when the mouse cursor enters the button in
 244        state 1.
 245        Default is "none".
 246      - onmouseout1: event executed when the mouse cursor leaves the button in
 247        state 1.
 248        Default is "none".
 249      - onmouseover2: event executed when the mouse cursor enters the button in
 250        state 2.
 251        Default is "none".
 252      - onmouseout2: event executed when the mouse cursor leaves the button in
 253        state 2.
 254        Default is "none".
 255
 256  - TextControl: Creates a text.
 257    Attributes:
 258      - font: the font to use, which must be one of the Font identifiants.
 259      - text: the text to display.
 260      - align: either 'left' or 'center' or 'right'.
 261        Default is "left".
 262      - scroll: if set to 'true', the text will scroll if it does not fit into
 263        the 'scrollspace'.
 264        Default is "true".
 265      - scrollspace: size in pixel between two occurrences of the text when
 266        scrolling.
 267        Default is "20".
 268      - display: this value is a bit special, it allows to have a text
 269        auto-updated by VLC. Possible values are 'time', 'left_time',
 270        'total_time', 'file_name' (for the current file name with its path),
 271        'title' (for the file name without the path) and 'help' (for a help
 272        about the controls that defined their 'help' attribute).
 273        You can specify several types by separating them with semicolons. To
 274        switch between then, just double click on the text.
 275        Useful to switch between 'time' and 'left_time'.
 276      - width: Width of the text in pixels. If set to "0", the width is
 277        automatically calculated to fit with the current text.
 278        Default is "0".
 279
 280  - SliderControl: Creates a slider. The 'abs' and 'ord' attributes are needed
 281    for the Bezier curve that the slider will follow. 'up' and 'down' are the
 282    images of the slider. The 'tooltiptext' attribute works, and the slider will
 283    automatically append the percentage of the position.
 284    Attributes:
 285      - type: two 'types' of sliders are predefined: 'time' for a slider
 286        allowing to seek in the stream, and 'volume' for a volume slider.
 287        Default is "time".
 288      - up: identifiant of a Bitmap.
 289      - down: identifiant of a Bitmap.
 290      - abs: see SliderControl description and bezier curve description.
 291      - ord: see SliderControl description and bezier curve description.
 292      - tooltiptext: used to display a tooltip.
 293        Default is "none" (no tooltip).
 294
 295  - PlaylistControl: Creates a playlist. This tag must contain a SliderControl
 296    tag (to allow scrolling in the playlist). If the playlist contains entries
 297    wider than the list width, an automatic tooltip will appear with
 298    the full name of the entry. The other attributes are rather easy to
 299    understand...
 300    Attributes:
 301      - width: width of the list in pixels. This is the whole width for file
 302        name, number of files in the playlist and info text.
 303        Default is "200".
 304      - infowidth: width of the info text in pixels.
 305        Default is "50".
 306      - font: the font to use, which must be one of the Font identifiants.
 307      - playfont: the font to use for current playing file, which must be one of
 308        the Font identifiants.
 309        Default is "none".
 310      - selcolor: color in "#RRGGBB" format of the selected files.
 311        Default is "#0000FF" (blue).
 312      - abs: see PlaylistControl description and bezier curve description.
 313      - ord: see PlaylistControl description and bezier curve description.
 314
 315
 316
 317 Compression
 318 ===========
 319
 320 Once your skin is finished, instead of keeping many bitmap files and the XML
 321 file, you can compress them in a .tar.gz archive (Winzip and UmtimateZip can do
 322 it perfectly, for example). Before doing so, don't forget to rename your XML
 323 file into "theme.xml", or VLC won't be able to read it... Then rename your
 324 compressed file with the .vlt extension and... that's all! VLC can load
 325 directly skins with the .vlt extension.
 326
 327
 328
 329 Tools and advice
 330 ================
 331
 332  - To generate easily Bezier curves, you can use the curve-maker. Basically,
 333    you add and remove points at will, and you can move them to see how the
 334    curve evolves. When you have reached the perfect curve, you just have to
 335    copy-paste the list of abscissas and ordinates into the 'abs' and 'ord'
 336    attributes of your SliderControl or PlaylistControl. The curve-maker also
 337    allows to load a bitmap, this could be useful if you want to follow a
 338    specific pattern of a slider, for example.
 339
 340  - When you are creating your skin, you may want to see the VLC messages where
 341    some errors are logged. For this, open a dos window, go to the directory
 342    where VLC is installed, and type "vlc -I skin -v --extraintf logger". This
 343    should open VLC and a log window (what's more, the logs should be saved in a
 344    file called vlc-log.txt). The interesting lines are those with "skin
 345    interface"...
 346
 347  - For the Bitmap tags, don't use absolute paths but relative paths (they are
 348    relative to the XML file directory), so that your skin can be reused by
 349    anybody without a particular file structure.
 350
 351  - To fully use the possibilities given, you should look at how other skins are
 352    made, it's often very useful.
 353
 354
 355 Good luck!
 356