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!
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.
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.
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 !
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"
33 Bezier curves are used for the SliderControl and the PlaylistControl tags.
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!
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
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
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
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).
69 OK, let's go for an enumeration of the different tags and theor attributes :
71 - Theme: The main tag.
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.
78 - log: not yet supported.
80 - ThemeInfo: You can enter here some information about you (but this
81 information is currently unused by VLC...)
83 - name: not yet supported.
84 - author: not yet supported.
85 - email: not yet supported.
86 - webpage: not yet supported.
88 - Bitmap: Associates a bitmap file with a name (=identifiant) that will be
89 used by the various controls. Obviously, you need one Bitmap tag for each
92 - id: this is the name of the bitmap that will be used with controls
93 ( 2 bitmaps shouldn't have the same name).
94 - alphacolor: this is the transparency color of the bitmap. It must be
95 indicated with the following format: "#RRGGBB" (where RR stands for the
96 hexadecimal value of the red component, GG for the green one, and BB for
98 - file: this attribute is used to indicate the path and name of the bitmap
99 file used. This path can be absolute (but you should avoid it as often as
100 possible), else it will be relative to the path of the xml file.
102 - Event: An action that will be associated to a control later.
104 - id: this is the name of the event that will be used with controls.
105 (2 events shouldn't have the same name).
106 - event: see event.howto.
107 - key: this is the shortcut key associated with the event. This means that
108 the event will be executed when hitting the correspounding key. It must
109 be indicated with following format : "MOD+L" where MOD is "CTRL" or "ALT"
110 if control or alt keys or associated the key and "L" is the letter and
111 must be in uppercase format ("MOD+" is optionnal).
114 - Font: Declares a font to be used in a TextControl or PlaylistControl.
116 - id: this is the name of the event that will be used with controls
117 Default is "default". (2 fonts shouldn't have the same name).
118 - font: this is the name of the font
120 - size: this is the size of the police in point
122 - color: this is the color of the font with the following format,
123 "#RRGGBB" (see bitmap).
124 Default is "#000000" (black).
125 - weight: this is the weight of the font. It must be between 0 and 1000
126 Default is "400" (normal weight). Fewer is thinner...
127 - italic: sets if the font must be in italic format.
129 - underline: sets if the font must be underlined.
132 - Window: A window that will appear on screen.
133 - id: this is the name of the window (it will be only used for events
134 but it is important : 2 windows shouldn't have the same name).
135 - visible: sets if the window should appear or not at the launch of VLC.
137 - x: sets the left position of the window.
139 - y: sets the top position of the window.
141 - fadetime: sets the time in milliseconds of the hide/show fading
144 - alpha: sets the transparency of the window. It must be between 1 and
145 255. 1 is nearly total transaprency and should be avoid. 255 is total
147 Default is "255". You should use high values.
148 - movealpha: sets the transparency of the window when the window is
149 moving. Same range as alpha.
151 - dragdrop: sets if drag and drop of media files is allowed in this
155 - ControlGroup: Adds an offset to the elements it contains. A ControlGroup is
156 only supposed to ease the job of the skin designer, who can adjust the
157 position of a group of controls without modifying all the coordinates, but
158 you can ignore it if you want (only one ControlGroup is necessary, just
159 inside Window). ControlGroup tags can be nested.
163 - y: what do you think ?
166 - Anchor: Creates a "magnetic point" in the current Window. If an anchor of
167 another Window enters in the range of action of this anchor, the 2 anchors
168 will automatically be on the same place, and the windows are "sticked". Each
169 anchor has a priority ('priority' attribute), and the anchor with the
170 highest priority is the winner, which means that when moving its Window all
171 the other anchored Windows will move too. To break the effect of 2 linked
172 anchors, you need to move the Window whose anchor has the lower priority.
174 - x: is it really necessary to explain ?
178 - priority: priority of anchor (see the previous description).
179 No default, must de defined !!!
180 - range: Range of action in pixel of the anchor.
183 - ImageControl, ButtonControl, CheckBoxControl, TextControl, SliderControl,
184 PlaylistControl: The various visual controls that constitute a Window. They
185 share some properties: 'x' and 'y' for the position, 'visible' for the
186 initial state, 'id' for identifying them (only needed if you want to create
187 an event acting on this particular control) and 'help' for a short
188 description of the control that could be displayed in a special TextControl
189 (see below). All the controls can also accept events, and you have the
190 possibility to associate many events to a control at once, separing them
193 - ImageControl: Creates a simple image. Usefull for backgrounds.
194 - image: this attribute must be set to an identifiant of a Bitmap tag.
195 - onclick: the 'event' attribute can be used to associate an event to the
196 image (the event is triggered by a click on the image).
197 Typical use: an Event made with 'WINDOW_MOVE(window)' (where 'window' is
198 the name of a Window) can be associated to an ImageControl of this
199 Window. Hence the Window can be moved via the image...
201 - ButtonControl: Creates a button.
202 - up: identifiants of a bitmap. Used for drawing the up state of the
204 - down: identifiants of a bitmap. Used for drawinf the down state of the
206 - disabled : identifiants of a bitmap. Used for drawing the disabled state
208 - onclick: event executed when clicking on the button.
210 - tooltiptext : used to display a tooltip.
211 Default is "none". (no tooltip).
213 - CheckBoxControl: Creates a checkbox, i.e. a button with 2 states
214 (checked/unchecked). So you need 6 images for a full-featured checkbox: each
215 state has a basic image, an image corresponding to a click not yet released,
216 and an image for the disabled control. If you supply only the basic images,
217 the other ones will be identical.
219 - img1: identifiants of a bitmap. Used for drawing control in state 1.
220 - clickimg1: identifiants of a bitmap. Used for drawing control when
221 clicking on it in state 1.
222 Default is the value of 'img1' attribute.
223 - img2: identifiants of a bitmap. Used for drawing control in state 2.
224 - clickimg2: identifiants of a bitmap. Used for drawing control when
225 clicking on it in state 2.
226 Default is the value of 'img2' attribute.
227 - disabled1: identifiants of a bitmap. Used for drawing control in state 1
229 Default is the value of 'img1' attribute.
230 - disabled2: identifiants of a bitmap. Used for drawing control in state 1
232 Default is the value of 'img2' attribute.
233 - onclick1: event executed when clicking on the control in state 1.
235 - onclick2: event executed when clicking on the control in state 2.
238 - TextControl: Creates a text.
240 - font: the font to use, which must be one of the Font identifiants.
241 - text: the text to display.
242 - align: either 'left' or 'center' or 'right'.
244 - scroll: if set to 'true', the text will scroll if it does not fit into
247 - scrollspace: size in pixel between two occurences of the text when
250 - display: this value is a bit special, it allows to have a text
251 auto-updated by VLC. Possible values are 'time', 'left_time',
252 'total_time', 'file_name' (for the current file name) and 'help'
253 (for a help about the controls that defined their 'help' attribute).
254 You can specify several type by separating them with semicolons. TO
255 switch between then, just double click on the text.
256 Usefull to switch betxeen 'time' and 'left_time'.
257 - width: Width of the text in pixel. If set to "0", the width is
258 automatically calculated to fit with the current text.
261 - SliderControl: Creates a slider. The 'abs' and 'ord' attributes are needed
262 for the Bezier curve that the slider will follow. 'up' and 'down' are the
263 images of the slider. The 'tooltiptext' attribute works, and the slider will
264 automatically append the percentage of the position.
266 - type: two 'types' of sliders are predefined: 'time' for a slider
267 allowing to seek in the stream, and 'volume' for a volume slider.
269 - up: identifiants of a bitmap.
270 - down: identifiants of a bitmap.
271 - abs: see SliderControl description and bezier curve description.
272 - ord: see SliderControl description and bezier curve description..
273 - tooltiptext: see button.
274 Default is "none". Disable tooltip.
276 - PlaylistControl: Creates a playlist. This tag must contain a SliderControl
277 tag (to allow scrolling in the playlist). If the playlist contains entries
278 wider than the list width, an automatic tooltip will appear with
279 the full name of the entry. The other attributes are rather easy to
282 - width: width in pixel of the list. This is the whole width for file
283 name, number of file in the playlist and info text.
285 - infowidth: width in pixel of the info text.
287 - font: the font to use, which must be one of the Font identifiants.
288 - playfont: the font to use for current playing file, which must be one of
289 the Font identifiants.
291 - selcolor: color in "#RRGGBB" format of the selected files.
292 Default is "#0000FF" (blue).
293 - abs: see PlaylistControl description and bezier curve description.
294 - ord: see PlaylistControl description and bezier curve description.
301 Once your skin is finished, instead of keeping many bitmap files and the XML
302 file, you can compress them in a .tar.gz archive (Winzip and UmtimateZip can do
303 it perfectly, for example). Before doing so, don't forget to rename your XML
304 file into "theme.xml", or VLC won't be able to read it... Then rename your
305 compressed file with the .vlt extension and... that's all! VLC can load
306 directly skins with the .vlt extension.
313 - To generate easily Bezier curves, you can use the curve-maker. Basically,
314 you add and remove points at will, and you can move them to see how the
315 curve evolves. When you have reached the perfect curve, you just have to
316 copy-paste the list ob abscissas and ordinates in the 'abs' and 'ord'
317 attributes of your SliderControl or PlaylistControl. The curve-maker also
318 allows to load a bitmap, this could be useful if you want to follow a
319 specific pattern of a slider, for example.
321 - When you are creating your skin, you may want to see the VLC messages where
322 some errors are logged. For this, open a dos window, go to the directory
323 where VLC is installed, and type "vlc -I skin -v --extraintf logger". This
324 should open VLC and a log window (what's more, the logs should be saved in a
325 file called vlc-log.txt). The interesting lines are those with "skin
328 - For the Bitmap tags, don't use absolute paths but relative paths (they are
329 relative to the XML file directory), so that your skin can be reused by
330 anybody without a particular file structure.
332 - To fully use the possibilities given, you should look at how other skins are
333 made, it's often very useful.