Chapter 2 - List of objects params and actions

Objects :

Container
Layout
Group
Button
ToggleButton
Layer
AnimatedLayer
Slider
Vis
EqVis
Text
Edit
ComponentBucket
Component

 

Containers and Layouts

Whenever you see a window in Winamp3, its appearance is defined by a Layout, and belongs to a Container. A container can hold many different layouts of the same window, for example the equalizer container can hold a normal equalizer and a windowshaded equalizer. Using the SWITCH and TOGGLE actions, buttons and layers can ask a container to switch to a specific layout, or to show and hide a container, whatever the visible layout is.

The default skin is composed of the following containers and layouts :

Container xml params

* indicates mandatory parameter

* id="component_id" : Component id, if id="main", action="CLOSE" will close the application, also, the main container is the master dock window
* name="Component name" : Component name as it appears in the context menu
dynamic="1" : Specifies that this container is not to be created at load time but is merely a template to be instantiated later (via script or on demand for components)
component="guid:default" : Specify which component can be held by this container, "guid:default" = all components
default_x="0", default_y="0" : Default position for the first time the skin is loaded. Note that the whole player (all windows) is then centered on the screen.
default_visible="1" : Show this container the first time the skin is loaded

Layout xml params

* id="layout_id" : Layout id, to be used with SWICTH and TOGGLE actions
* background="bitmap.id" : Specifies which bitmap to use for background and shape
move="0" : Do not move the layout when mouse is clicked on it
drawbackground="0" : Do not draw background at all, not fully supported yet

Gui Objects xml params

Gui objects are buttons, layers, sliders, vis, and all the elements that compose your layout.Most of them are interactive objects, like sliders, which you can link to Winamp3 functions like seeking, volume, but you could also create objects than you plan to use in scripts and whose behaviour will not automatically be linked to Winamp functions (chapter 7). All Gui objects are blended together using each image's alpha channel. The first object in the layout is the bottom most object in the rendering. The last object is the topmost object. This is important to know as an object getting clicked prevents all objects behind it from getting the click (there is an exception to that with ghost layers, which do not trap mouse events and can therefore cover the entire layout without interfering with the other objects).

All GUI objects have the following xml params :

id="object_id" : Set object id
x="0", y="0", w="10", h="10 : set object coordinates, can be negative
relatx="1", relaty="1", relatw="1", relath="1" : set coordinate relative to max (ie x="-10", relatx="1" with layout width of 50 will position x at 40)
tooltip="tip" : set mouse tooltip

When w and h are ignored and the object has an image loaded (see individual objects xml params), the width and height of the object will be automatically set by the normal size of the image. If w and h cannot be automatically guessed, the skin loader will generate an error

Button xml params

image="image.id" : set image for normal state
downImage="image.id" : set image for clicked state
action="SWITCH" : set button action (see list of actions below)
param="param" : set button action parameter (see list of actions below)

ToggleButton xml params

activeImage="image.id" : set image for On state
- inherits xml params from Button

Layer xml params

image="image.id" : set image to paint
tile="1" : tile the image instead of stretching it if w>image's width
ghost="1" : Do not get mouse events (clickthrough)
sysregion="1" : Pass region information down to the desktop. If the layer is above a transparent part of the layout, the layout's region will be updated so the layer is visible

resize="top" : let the user resize the layout from the top, possible values: top, bottom, left, right, topleft, topright, bottomleft, bottomright
scale="bottomright" : let the user scale the window from the bottome-right corner, same possible values as resize
move="1" : let the user move the layout when layer is clicked
dblclkaction="SWITCH;layoutid" : switch to layout when double clicked
alpha="127" : set alpha to 127/255

AnimatedLayer xml params

autoreplay="1" : replay animation when done
autoplay="1" : start animation when skin starts
speed="20" : 20ms per frame
frameheight="50" : specify that the image has a vertical animation with each frame 50 pixel tall
framewidth="50" : specify that the image has an horizontal animation with each frame 50 pixel wide
realtime="1" : do not defer redrawing, uses more cpu
- inherits xml params from Layer

If you do not use autoplay="1", you will need to start the animation via a script (chapter 7)

Slider xml params

barleft="image.id" : Left/Top part of slider background bar
barmiddle="image.id" : Middle part of slider background bar
barright="image.id" : Right/Bottom part of slider background bar
thumb="image.id" : Slider's thumb image
downthumb="image.id" : Slider's thumb image when clicked
hoverthumb="image.id" : Slider's thumb image when hovered
orientation="V" : Set slider vertical, possible values : V, VERTICAL, H, HORIZONTAL

Vis xml params

colorband1="255,255,255" : BGR value for band 1
...
colorband16="255,255,255" : BGR value for band 16
colorbandpeak="255,255,255" : color for peak
colorosc1="255,255,255" : oscilloscope color 1
...
colorosc5="255,255,255" : oscilloscope color 5

EqVis xml params

gamma="127" : set alpha (!) to 127/255
colortop="255,255,255" : Eq curve top color
colormiddle="255,255,255" : Eq curve middle color
colorpreamp="255,255,255" : Eq curve bottom color

Text xml params

display="info" : Automatically display info, possible values for info : SONGNAME, SONGINFO, SONGARTIST, SONGTITLE, SONGALBUM, TIME, COMPONENTBUCKET. The later links the text to all component buckets in the layout if no cbsource param is set
ticker="1" : Auto-scroll the text if everything doesn't fit
default="text" : default text contents
font="font.id" : text font
fontsize="12" : text size
align="left" : alignment, possible values: LEFT, RIGHT, CENTER
color="255,255,255" : text color
shadowcolor="255,255,255" : text shadow color
shadowx="2", shadowy="2" : set shadow distance to 2,2. If unspecified or 0,0, no shadow is drawn
timeroffstyle="1" : 0 = " : ", 1 = "00:00", 2 = " "
timecolonwidth="5" : if text is a timer, set width of the colon char to 5
nograb="1" : if you don't want to allow the user to grab and drag the scrolling text
showlen="1" : if display="SONGNAME", also show length of song
forcefixed="1" : force fixed with even for truetype font
bold="1" : use bold text (unsupported for bitmap fonts)
cbsource="componentbucketid" : link to specific component bucket

Edit xml params

text="default_text" : set default contents
action="MB_URL" : Link object to minibrowser

ComponentBucket xml params

leftmargin="2" : set left margin to 2 pixels
rightmargin="2" : set right margin to 2 pixels
spacing="2" : set spacing between items to 2 pixels

Component xml params

param="guid:default" : accept all components
noshowcmdbar="1" : do not show component command bar

List of actions

PREV : Jump to previous song in playlist
PLAY : Play from beginning
PAUSE : Pause current song
STOP : Stop playing
NEXT : Jump to next song in playlist
EJECT : Bring up open file window
EJECT_URL : Bring up open url window
EJECT_DIR : Bring up open directory window
SEEK : Auto-seek to slider position
VOLUME : Auto-set volume to slider position
MINIMIZE : Minimize application
CLOSE : Close layout (Close application if container id="main")
SWITCH : Switch to layout, PARAM="layoutid" | for layer actions, use "SWITCH;layoutid"
TOGGLE : Toggle container, PARAM="containerid"
SYSMENU : Open general context menu
MB_FORWARD : Send forward message to minibrowser
MB_BACK : Send back message to minibrowser
MB_URL : Link Edit object to minibrowser
EQ_TOGGLE : Toggle EQ
EQ_PREAMP : Toggle Preamp
EQ_BAND : Link slider to EQ band, PARAM="n", 1 < n < 10
CB_NEXT : Send next command to component bucket, CBTARGET="componentbucketid", if left out, button will control all compbucket in tje layout
CB_PREV : Send previous command to component bucket, same param as CB_NEXT
RELOAD_SKIN : Reload current skin
VOLUME_UP : Volume up
VOLUME_DOWN : Volume down
REWIND_5S : Rewind 5s
FFWD_5S : Fast forward 5s
text_larger : Make text larger
text_smaller : Make text smaller