X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fskins%2Fskins2-howto.xml;h=5ad8c5c42b57296b68697d4dd197e005594e8a5d;hb=547247da8dca865ce18d42ad4efdf40345393235;hp=9dcfd5a0d198d35ffa263a7e005a3844b7a7ffa0;hpb=18c84cde7f93f81a21113d55a79843a3ef3b44a0;p=vlc diff --git a/doc/skins/skins2-howto.xml b/doc/skins/skins2-howto.xml index 9dcfd5a0d1..5ad8c5c42b 100644 --- a/doc/skins/skins2-howto.xml +++ b/doc/skins/skins2-howto.xml @@ -10,7 +10,7 @@ HowTo create your own skin -2004 +2004-2006 the VideoLAN project @@ -41,6 +41,7 @@ website. + VLC Skin XML Bezier @@ -65,24 +66,6 @@ difficulty to understand how VLC skins work. - -Bezier curves - -One cool thing with VLC sliders is that they are not necessarily rectilinear, but they can follow any Bezier curve. So if you want to have a slider moving on a half-circle, or even doing a loop, you can! - -This is not the place to explain how Bezier curves work (see http://astronomy.swin.edu.au/~pbourke/curves/bezier/ for a nice introduction), the main thing to know is that a Bezier curve can be characterized by a set of points. Once you have them (thanks to the CurveMaker utility for example), you just need to enter the list of points in the points attribute. Here is an example with 3 points: points="(2,50),(45,120),(88,50)". - -Bezier curves can be used with the Slider and Anchor tags: - - - For sliders, it defines the curve followed by the cursor of the slider. This curve is of course invisible, so if you want a visible background for your Slider you need to provide it yourself using the Image tag. - For anchors, the use of Bezier curves is more anecdotic. Its purpose is to have non-ponctual anchor, the whole curve becoming the anchor. In this case, a ponctual anchor (and only a ponctual one) can be attracted by any point of the curve, if it is in its range of action. In fact, you can consider the curve as an easy way to define at once many anchors that share the same properties (except their position, of course :)). - - -The coordinates are relative to the upper-left corner of the control (i.e. to its x and y attributes). - - - The bitmaps @@ -101,7 +84,7 @@ difficulty to understand how VLC skins work. XML is a markup language, like HTML. It won't be explained here any further, please use Google if you don't know what XML is. You'll see, it is rather easy to understand. -The XML file used for the VLC skins follows a predefined DTD. You can find this DTD in VLC SVN, and its reading is strongly advised, since it contains the default values used for the parameters. A skin that does not follow the DTD with which VLC was compiled won't be loaded by VLC (and it might even crash it...). +The XML file used for the VLC skins follows a predefined DTD. You can find this DTD in VLC Git, and its reading is strongly advised, since it contains the default values used for the parameters. A skin that does not follow the DTD with which VLC was compiled won't be loaded by VLC (and it might even crash it...). For a better undestanding of what follows, you should have a look at the DTD and/or at an example of valid XML skin. @@ -321,12 +304,12 @@ difficulty to understand how VLC skins work. width - Width of the layout. this value is required since VLC is not (yet?) able to calculate it using the sizes and positions of the controls. + Initial width of the layout. This value is required since VLC is not (yet?) able to calculate it using the sizes and positions of the controls. Required. height - Height of the layout. this value is required since VLC is not (yet?) able to calculate it using the sizes and positions of the controls. + Initial height of the layout. This value is required since VLC is not (yet?) able to calculate it using the sizes and positions of the controls. Required. @@ -353,25 +336,65 @@ difficulty to understand how VLC skins work. Group - Adds an offset to the elements it contains. A Group is only supposed to ease the job of the skin designer, who can adjust the position of a group of controls without modifying all the coordinates, but you can ignore it if you want (only one Group is necessary, inside the Window tag). Group tags can be nested. + Add an offset to the elements it contains. A Group is only supposed to ease the job of the skin designer, who can adjust the position of a group of controls without modifying all the coordinates, but you can ignore it if you want (only one Group is necessary, inside the Layout tag). Group tags can be nested. Note that Group elements are deprecated, since Panel elements are more powerful. x - Try and guess. + Horizontal offset, relative to the container box (see the Layout model for more details). Default value: 0 y - What do you think? + Vertical offset, relative to the container box (see the Layout model for more details). Default value: 0 + + Panel + A Panel can be seen as an enhanced Group. It also adds an offset to the elements it contains, but in addition it becomes their reference for the lefttop, rightbottom, xkeepratio and ykeepratio attributes. Panel tags can be nested. Since VLC 0.9.0. + See the common attributes. + + x + Same as the x attribute of the common attributes. + + + y + Same as the y attribute of the common attributes. + + + width + Initial width of this container box (see the Layout model for more details). + Required. + + + height + Initial height of this container box (see the Layout model for more details). + Required. + + + lefttop + Same as the lefttop attribute of the common attributes. + + + rightbottom + Same as the rightbottom attribute of the common attributes. + + + xkeepratio + Same as the xkeepratio attribute of the common attributes. + + + ykeepratio + Same as the ykeepratio attribute of the common attributes. + + + Anchor Create a "magnetic point" (or curve) in the current window. If an anchor of another window enters in the range of action of this anchor, the 2 anchors will automatically be on the same place, and the windows are "sticked". Each anchor has a priority (priority attribute), and the anchor with the highest priority is the winner, which means that when moving its window all the other anchored windows will move too. To break the effect of 2 anchored windows, you need to move the window whose anchor has the lower priority. x - Is it really necessary to explain ? + Is it really necessary to explain? Default value: 0 @@ -419,34 +442,34 @@ difficulty to understand how VLC skins work. x - Horizontal offset of the control, relative to the parent tag (usually Group or Layout). + Horizontal offset of the control, relative to the container box (see the Layout model) or to the parent Group. Default value: 0 y - Vertical offset of the control, relative to the parent tag (usually Group or Layout). + Vertical offset of the control, relative to the container box (see the Layout model) or to the parent Group. Default value: 0 lefttop - Indicate to which corner of the Layout the top-left-hand corner of this control is attached, in case of resizing. Possible values are 'lefttop', 'leftbottom', 'righttop' and 'rightbottom'. + Indicate to which corner of the container box the top-left-hand corner of this control is attached, in case of resizing. Possible values are 'lefttop', 'leftbottom', 'righttop' and 'rightbottom'. See the Layout model for more details. Default value: lefttop rightbottom - Indicate to which corner of the Layout the bottom-right-hand corner of this control is attached, in case of resizing. + Indicate to which corner of the container box the bottom-right-hand corner of this control is attached, in case of resizing. See the Layout model for more details. Default value: lefttop xkeepratio - When set to true, the behaviour of the horizontal resizing is changed. Instead of taking into account the lefttop and rightbottom attributes to determine how the control will be moved/resized, only its initial position inside the Layout matters. For example, if initially the space to the left of the control is twice as big as the one to its right, this will stay the same during any horizontal resizing. The width of the control stays constant. - This attribute can be particularly useful to keep a control centered in the layout, without resizing it (to resize it, you would rather use the lefttop/rightbottom attributes). + When set to true, the behaviour of the horizontal resizing is changed. Instead of taking into account the lefttop and rightbottom attributes to determine how the control will be moved/resized, only its initial position inside the container box matters. For example, if initially the space to the left of the control is twice as big as the one to its right, this will stay the same during any horizontal resizing. The width of the control stays constant. + This attribute can be particularly useful to keep a control centered in the container box, without resizing it (to resize it, you would rather use the lefttop/rightbottom attributes). See the Layout model for more details. Available since VLC 0.8.6. Default value: false ykeepratio When set to true, the behaviour of the vertical resizing is changed. Instead of taking into account the lefttop and rightbottom attributes to determine how the control will be moved/resized, only its initial position inside the Layout matters. For example, if initially the space to the top of the control is twice as big as the one to its bottom, this will stay the same during any vertical resizing. The height of the control stays constant. - This attribute can be particularly useful to keep a control centered in the layout, without resizing it (to resize it, you would rather use the lefttop/rightbottom attributes). + This attribute can be particularly useful to keep a control centered in the container box, without resizing it (to resize it, you would rather use the lefttop/rightbottom attributes). See the Layout model for more details. Available since VLC 0.8.6. Default value: false @@ -506,6 +529,11 @@ difficulty to understand how VLC skins work. Action executed when the button is clicked. See Actions for a list of possible actions. Default value: none + + tooltiptext + Tooltip associated with the button. See also Text variables. + Default value: + @@ -607,7 +635,7 @@ difficulty to understand how VLC skins work. Slider - Create a slider. + Create a slider. This element can be used alone, or can contain a SliderBackground element. See the common attributes. up @@ -646,6 +674,38 @@ difficulty to understand how VLC skins work. + + + SliderBackground + Set of background images associated to a slider (it must be a sub-element of a Slider). The displayed image depends on the value of the corresponding slider; if the SliderBackground contains n images, the image #m will be displayed, where m = n * (slider value). A SliderBackground actually contains a single image, which is divided into a grid to build all the sub-images. All the sub-images of the grid have the same size, and can be separated by unused pixel lines or rows if needed (this is called "padding"). + See the common attributes. + + image + Identifiant of a Bitmap; image containing the sub-images used to draw the background of the slider. + Required. + + + nbhoriz + Number of sub-images in the horizontal direction. + Default value: 1 + + + nbvert + Number of sub-images in the vertical direction. + Default value: 1 + + + padhoriz + Horizontal padding: number of unused pixel rows between two sub-images. + Default value: 0 + + + padvert + Vertical padding: number of unused pixel lines between two sub-images. + Default value: 0 + + + RadialSlider Create a circular slider from a list of images with the different possible positions. @@ -932,7 +992,7 @@ difficulty to understand how VLC skins work. dvd.nextChapter(): Go to the next chapter of the DVD (since VLC 0.8.5). - dvd.previousTitle(): Go to the previous chapter of the DVD (since VLC 0.8.5). + dvd.previousChapter(): Go to the previous chapter of the DVD (since VLC 0.8.5). dvd.rootMenu(): Go to the root menu of the DVD (since VLC 0.8.5). @@ -943,6 +1003,12 @@ difficulty to understand how VLC skins work. WindowID.hide(): Hide the Window whose id attribute is 'WindowID'. + + WindowID.maximize(): Maximize the Window whose id attribute is 'WindowID'. Since VLC 0.9.0. + + + WindowID.unmaximize(): Unmaximize the Window whose id attribute is 'WindowID'. Since VLC 0.9.0. + WindowID.setLayout(LayoutID): Change the layout of the Window whose id attribute is 'WindowID', using the Layout whose id attribute is 'LayoutID'. @@ -1045,6 +1111,9 @@ difficulty to understand how VLC skins work. dvd.isActive: True when a DVD is currently playing. This variable can be used to display buttons associated to the dvd.* actions only when needed (since VLC 0.8.5). + + WindowID.isMaximized: True when the window whose id is "WindowID" is maximized, false otherwise (since VLC 0.9.0). + WindowID.isVisible: True when the window whose id is "WindowID" is visible, false otherwise. @@ -1082,6 +1151,38 @@ difficulty to understand how VLC skins work. + +Layout model + +Placing the controls on a window is easy, using their x and y attributes, but these positions become insufficient for a resizable window. Some controls (or groups of controls) should stay centered in the window, others should follow the right side of the window, others should change their size automatically, etc... To handle these various behaviours, the layout model followed by the skins engine is a model based on nested boxes. + +There are 2 kinds of boxes: + + + + simple boxes: These boxes cannot contain other boxes. All the visible controls are simple boxes: Image, Button, Checkbox, Text, Slider, RadialSlider, Playlist, Playtree, Video. + + + container boxes: These boxes can contain other boxes. Only two XML tags create container boxes: Panel and Layout. The Layout tag is necessarily the top-level box for the current layout, and cannot be contained, but Panel elements can be contained. + + + +A box inside a container box always defines how it should react when its container box is resized. Two different mechanisms are provided: corners anchoring (useful when resizing of the inner box is wanted, for example) and constant ratio (mainly useful to keep the inner box centered inside its parent): + + + corners anchoring: The top-left-hand corner (TL) and the bottom-right-hand corner (BR) of the inner box are "tied" to corners of the container box (TL, TR, BL or BR). When any resizing occurs, tied corners move together, which can move or resize the inner box. For example, if the TL corner of the inner box is tied to the TL corner of the container (let's write it TL/TL), and if the BR corner of the inner box is also tied to the TL corner of the container box (BR/TL), the inner box will not be resized, and will always stay at the same place (this is the default behaviour). If we have TL/TL and TL/BL, the inner box is resized vertically when its container is resized. If we have TL/TR and BR/TR, the inner box moves with the TR corner of its container. We could even define TL/BR and BR/TL, in which case increasing the size of the container box would shrink the size of the inner box... until it disappears completely! + + This mechanism is controlled by the lefttop and rightbottom attributes of the controls. + + + constant ratio: When a box doesn't fill completely its container box, there is space on the top, bottom, left and right of the inner box. It is possible to force the ratio between the space on the top and the space on the bottom (or the one on the left and the one on the right) to be constant. Any resizing of the container box will then move the inner box accordingly, and the size of the inner box will never change (it overrides the corners anchoring mechanism). The horizontal and vertical ratios being independent, it is for example possible to keep only the horizontal ratio constant, in which case the inner box can still resize vertically (depending on its attributes for the corners anchoring, of course). + + This mechanism is controlled by the xkeepratio and ykeepratio attributes of the controls. + + + + + @@ -1104,6 +1205,24 @@ difficulty to understand how VLC skins work. + +Bezier curves + +One cool thing with VLC sliders is that they are not necessarily rectilinear, but they can follow any Bezier curve. So if you want to have a slider moving on a half-circle, or even doing a loop, you can! + +This is not the place to explain how Bezier curves work (see http://astronomy.swin.edu.au/~pbourke/curves/bezier/ for a nice introduction), the main thing to know is that a Bezier curve can be characterized by a set of points. Once you have them (thanks to the CurveMaker utility for example), you just need to enter the list of points in the points attribute. Here is an example with 3 points: points="(2,50),(45,120),(88,50)". + +Bezier curves can be used with the Slider and Anchor tags: + + + For sliders, it defines the curve followed by the cursor of the slider. This curve is of course invisible, so if you want a visible background for your Slider you need to provide it yourself using a SliderBackground or Image tag. + For anchors, the use of Bezier curves is more anecdotic. Its purpose is to have non-ponctual anchor, the whole curve becoming the anchor. In this case, a ponctual anchor (and only a ponctual one) can be attracted by any point of the curve, if it is in its range of action. In fact, you can consider the curve as an easy way to define at once many anchors that share the same properties (except their position, of course :)). + + +The coordinates are relative to the upper-left corner of the control (i.e. to its x and y attributes). + + + Tools and advice @@ -1111,7 +1230,7 @@ difficulty to understand how VLC skins work. Generating Bezier curves -To generate easily Bezier curves, you can use the curve-maker (sorry, this is for Windows users only). Basically, you add and remove points at will, and you can move them to see how the curve evolves. When you have reached the perfect curve, you just have to copy-paste the list of abscissas and ordinates to form the points attribute of your Slider or Playlist. The curve-maker also allows to load a .bmp file, this could be useful if you want to follow a specific pattern of a slider, for example. +To generate easily Bezier curves, you can use the CurveMaker utility (sorry, this is for Windows users only). Basically, you add and remove points at will, and you can move them to see how the curve evolves. When you have reached the perfect curve, you just have to copy-paste the list of abscissas and ordinates to form the points attribute of your Slider or Anchor. The curve-maker also allows to load a .bmp file, this could be useful if you want to follow a specific pattern of a slider, for example. This tool was made for the first version of the skins and has not been modified since then. This explains why it does not use PNG files and why it does not generate directly the value of the points attribute. @@ -1132,26 +1251,17 @@ VLC is able to give warnings and error messages about a loaded skin if it finds Relative paths - - -For the Bitmap tags, do not use absolute paths but relative paths (they are relative to the XML file directory), so that your skin can be reused by anybody without a particular file structure. - + For the Bitmap tags, do not use absolute paths but relative paths (they are relative to the XML file directory), so that your skin can be reused by anybody without a particular file structure. Get inspiration - - -In order to use plainly the possibilities given, you should look at how existing skins are made, it may give you ideas for your own skins... - + In order to use plainly the possibilities given, you should look at how existing skins are made, it may give you ideas for your own skins... You can also consult on the wiki a list of features usually expected from a skin. Submit your skin! - - -Once your skin is finished, you can share it with other people. The easiest way is probably to send it by email to vlc -at- videolan -dot- org, so that we can put it on the website with the other ones. - + Once your skin is finished, you can share it with other people. The easiest way is probably to send it by email to vlc -at- videolan -dot- org, so that we can put it on the website with the other ones. You can also post it in the skins forum. Feel free to ask for support there if you have any problems...