How to write a Bemused skin
Introduction
You can customise the way Bemused looks with skins. A skin consists of an image file (in PNG format) and accompanying description, with which you can specify the following aspects of the "Control" view:
- Background image
- Position and images for the 5 buttons
- Position, direction and images for the volume slider
- Images for the shuffle and repeat indicators
- Position, colour and font of the track name and time indicators
You can also specify the foreground, background and selected item colours for the "Browse" view. Skins are fairly easy to write; this page aims to give an introduction to the process.
Elements of a skin
A skin can either be for Bemused's "full-screen" mode, or its "in window" mode. You should try to provide both, so the user can choose the size they prefer. The names of skin files must conform to the following format:
- [Name of skin]_iw.png - the image file for "in window" mode
- [Name of skin]_iw.txt - the description file for "in window" mode
- [Name of skin]_fs.png - the image file for "full screen" mode
- [Name of skin]_fs.txt - the description file for "full screen" mode
[Name of skin] is the name that will be displayed to the user when installing or uninstalling the skin. Note that it can include spaces.
Skins are installed by simply sending them to the phone, running Bemused and selecting "Install skin" from the settings.
Format of a skin image file
The following picture illustrates the different elements of a skin image file:
The image consists of the background (at the top), followed by extra information about the buttons, volume slider, shuffle and repeat. The size of the background depends on whether the skin is full-screen or not. For an in-window skin, the background will be 176 x 144 pixels big. For a full-screen skin, it will be 176 x 188 pixels big. The total size of the image also depends on the size of the buttons and other elements. Don't worry if the image is too big; it will be cropped to the size of the window.
As you can see, the elements below the background image represent the buttons in "focused" and "pressed" states. Note that there is some unused space to the right and the bottom of the image. Below the two rows of buttons is the final row of controls, which contains the volume slider, the volume slider mask, and repeat and shuffle images.
Unlike all the other elements of a skin image, the volume slider has a mask as well. This means that you can make sliders which are partly transparent. The mask is the same size as the slider, and there's only one thing to know about it: black represents transparency. Any other colour represents opacity.
Note that all of these elements can be any size you like (within the limits of screen size). Bemused will calculate their size and position from the values specified in the skin description file. It's very important to get these values exactly right; being one pixel off can make a big difference.
Format of a skin description file
A skin description file consists of a list of attributes and parameters. The format of these is:
[attribute]: [parameter 1] [parameter 2] ... [new line]
Attribute names are not case-sensitive. Only decimal numbers (ie. not hexadecimal) can be used for parameters. Colour parameters are 3 numbers in the range 0-255. For example, red would be specified by "255 0 0".
The following attributes can be used:
- Author: [string] -
Specifies the name of the author of this skin.
- Buttons: [top X] [top Y] [bottom X] [bottom Y] -
Specifies the co-ordinates of the rectangle which encloses the five buttons.
- HighlightBackgroundColour: [red] [green] [blue] -
Specifies the colour to use for the background of the highlight in the "Browse" view.
- HighlightForegroundColour: [red] [green] [blue] -
Specifies the colour to use for the foreground of the highlight in the "Browse" view.
- Repeat: [top X] [top Y] [bottom X] [bottom Y] -
Specifies the co-ordinates of the "repeat" indicator.
- Shuffle: [top X] [top Y] [bottom X] [bottom Y] -
Specifies the co-ordinates of the "shuffle" indicator.
- TextBackgroundColour: [red] [green] [blue] -
Specifies the colour to use for the background in the "Browse" view.
- TextForegroundColour: [red] [green] [blue] -
Specifies the colour to use for the text in the "Browse" view.
- TrackName: [top X] [top Y] [bottom X] [bottom Y] -
Specifies the co-ordinates of the rectangle which encloses the track name.
- TrackNameColour: [red] [green] [blue] -
Specifies the colour to use for the track name.
- TrackNameFont: [font number] -
Specifies the font to use for the track name. See below for a list of fonts.
- TrackTime: [top X] [top Y] [bottom X] [bottom Y] -
Specifies the co-ordinates of the rectangle which encloses the track time.
- TrackTimeColour: [red] [green] [blue] -
Specifies the colour to use for the track time.
- TrackTimeFont: [font number] -
Specifies the font to use for the track time. See below for a list of fonts.
- Volume: [top X] [top Y] [bottom X] [bottom Y] [slider width] [slider height] -
Specifies the co-ordinates of the rectangle in which the volume slider moves, and the width and height of the slider. Note that the volume slider can be set to move at any angle using these co-ordinates.
Font numbers are mapped to fonts using the following scheme:
- Title font (largest)
- Dense font (smallest)
- Legend font (second smallest)
- Annotation font
- Symbol font
- Normal font (second largest)
Note that, if an attribute isn't specified in a skin description file, Bemused will use the default value. However, you shouldn't rely on this, as the defaults may change in the future.
Tips
- Try to use as few colours as possible. The more colours you use, the larger the size of the skin.
- Users don't really like being confused. Try to make your skin easy to use and logical.
- To get started, why not try modifying an existing skin?
And finally... good luck!