XML Elements

From Winamp Developer Wiki
Revision as of 10:03, 26 September 2008 by Pjn123 (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

What is Elements?

Elements are the sub-atomic particles of the chemistry of Wasabi UI development. They represent the binding of fonts, colors, and raster graphics to id's which are then referenced by the actual objects of the system. The definition of elements should occur hierarchically within an <elements> tag. Because elements are intended to be referenced by GuiObjects, specifying elements without ids is a meaningless endeavour. A simple sample of each possible type of element would look like this:

<elements>
	<color id="myindigo" value="64,32,128"/> 
	<bitmap id="mybitmap" file="mybitmap.png" x="104" y="0" h="90" w="244" gammagroup="Backgrounds"/>
	<bitmapfont id="mybitfont" file="myfont.png" charwidth="9" charheight="13" hspacing="3" vspacing="1"/>
	<truetypefont id="myttfont" file="impact.ttf"/>
	<elementalias id="newelemid" target="mybitmap"/>
</elements>


<bitmap/>

The bitmap element defines a raster buffer of the given pixel size, sliced out of the given raster graphics file. In general, we use the .png graphics format for our bitmap graphics, however Wasabi's "supported formats" are determined entirely at startup by the registration of image loader services (see Extending Wasabi: Image Loaders). If the sizing values (x/y/h/w) are not specified, the bitmap defines a buffer equivalent to the entire graphics file. Its specific parameters are:

  • id - (string) A unique string, that is used to identify the element when used by the object.
  • file - (string) A path to the bitmap file the image is in. If it begings with disk name (C:/.../filename) then the path is absolute, otherwise (folder1/.../filename) the path is relative to skin folder (don't confuse with inclusion of xml files where path is relative to parent xml file)
  • x - (int) A coordinate x of the image defined inside the bitmap file (x coordinate of the cropped area).
  • y - (int) A coordinate y of the image defined inside the bitmap file (y coordinate of the cropped area).
  • w - (int) Width of the image defined inside the bitmap file (width of the cropped area).
  • h - (int) Height of the image defined inside the bitmap file (height of the cropped area).
  • gammagroup - (id) The id of the gammagroup the bitmap will be changed by when using color themes.


You can also use these internal bitmaps without declaring them:

  • $wallpaper - This is the current background of Windows.
<layer x="" y="" image="$wallpaper"/>

<bitmapfont/>

The bitmapfont element specifies the information required to pull a fixed-width font set out of a raster graphic file. Bitmap fonts always begin their series with ascii character '0' and can go for as many characters as you desire. Any ascii characters not represented by a cell in the graphics file will display as blanks. The required specific parameters are:

  • id - (string) A unique string, that is used to identify the element when used by the object.
  • file - (str) The name of the raster graphics file from which to load.
  • charwidth - (int) The width of each glyph cell in pixels.
  • charheight - (int) The height of each glyph cell in pixels.
  • hspacing - (int) The extra overlap distance for each glyph cell, in pixels, on the horizontal axis.
  • vspacing - (int) The extra overlap distance for each glyph cell, in pixels, on the vertical axis.


<truetypefont/>

The truetypefont element specifies a TTF file to be registered with the system. Note that most of the font-using GuiObjects in the system request Arial, which is not usually defined. Any request for an undefined font name will default to the list of OS-installed fonts. This allows a skin to define a truetypefont element with the id of "arial" which will automatically become the default for most objects displaying text. The specific parameter for this element is:

  • id - (string) A unique string, that is used to identify the element when used by the object.
  • file - (str) The name of the true type font file to load.


<color/>

  • id - (string) A unique string, that is used to identify the element when used by the object.
  • value - (string-"int,int,int") A comma delimited list of 3 integers in the range 0-255 corresponding to the individual red, green, and blue elements that define a "truecolor" value.
  • gammagroup - (str) The id of a gammagroup to which this element is assigned.


<elementalias/>

The bitmapfont element specifies the information required to pull a fixed-width font set out of a raster graphic file. Bitmap fonts always begin their series with ascii character '0' and can go for as many characters as you desire. Any ascii characters not represented by a cell in the graphics file will display as blanks. The required specific parameters are:

  • id - (string) A unique string, that is used to identify the element when used by the object.
  • target - (str) The id of the element to alias.


<cursor/>

The cursor element specifies the information required to create your own cursor that you can use in your skin.

  • bitmap - (str) Same as the file param for <bitmap/>
  • hotspot_x - (int) The X position of the hotspot.
  • hotspot_y - (int) The Y position of the hotspot.
<cursor id="cursor.h" bitmap="pictures/cursor_h.png" hotspot_x="10" hotspot_y="4"/>