themehowto.txt

freeamp有名的媒体播放器

    <TextControl Name="Time">

The name of the TextControl is used to identify what information gets
displayed in the field. You can specify Title, Info, BufferInfo, and
Time TextControls. NOTE: For the Time field, you can hit the '@' key and
FreeAmp will put the time '23:59:59' into the time field so you can test
the size of the time field. (Time fields that are too small end up 
marqueeing back and forth and that looks nasty)

A TextControl will need to include the <Position> and <Style> tags.


SliderControl:
--------------

SliderControls are used to control volume and seek position:

    <SliderControl Name="Volume">  

The Name can either be Volume or Seek. The SliderControl needs to 
define the <Info>, <Position>, and <ControlBitmap> tags. The only
bitmaps associated with a slider control are the bitmaps for the
thumb of the slider control. The actual frame of the control is part
of the background bitmap. The thumb bitmap is specified by the
<ControlBitmap> tag and has three states:

    Normal, MouseOver, and Disabled

VSliderControl:
--------------

VSliderControls are used to control volume and seek position. A VSlider
is arranged vertically, where a normal Slider is horizontal:

    <VSliderControl Name="Volume">  

The Name can either be Volume or Seek. The VSliderControl needs to 
define the <Info>, <Position>, and <ControlBitmap> tags. The only
bitmaps associated with a VSlidercontrol are the bitmaps for the
thumb of the slider control. The actual frame of the control is part
of the background bitmap. The thumb bitmap is specified by the
<ControlBitmap> tag and has three states:

    Normal, MouseOver, and Disabled

Info:
-----

The Info tag is used to give the user feedback about a control:

    <Info Desc="Stop the player" Tip="Stop"/>

The text contained in the Desc attribute is displayed in the Info
TextControl when the user moves the mouse over the control that
specifies the Info tag. And, once we get tooltips implemented,
the Tip attribute will define the text shown in the tooltip when
the mouse hovers over a button.

For a MultiStateControl, set Desc and Tip attribute strings for each of
the states can be seperated by '||'. The play/pause button <Info>
tag looks like this:

    <Info Desc="Play the current track||Pause the current track" 
          Tip="Play||Pause"/>

If the Desc and Tip attributes are not seperated by '||' then the
entire Desc and Tip attribute text will be shown for all states of the
button.
          

Position:
---------

The position tag includes the Rect attribute to indicate where the
control should be placed on the background bitmap:

    <Position Rect="202,122,234,155"/>

The coordinates specified in the Rect attribute are in background bitmap
coordinates. In the example above, the button will be placed 202 
pixels to the right of the left edge of the control bitmap and
122 pixels below the top edge of the control bitmap.

In beta 4, the theme designer should also be able to specify a Pos
instead of a Rect, and the size of the button will be determined
from the information given in the ControlBitmap tag.


ControlBitmap:
--------------

The ControlBitmap tag specifies the bitmap to use for a control:

    <ControlBitmap Rect="237,148,288,163" Name="Buttons"/>
    
The coordinates specified in the Rect attribute are in "Buttons" bitmap
coordinates. In the above case, the control bitmap starts 237 pixels
to the right of the left edge of the Buttons bitmap, and 148 pixels
below the top edge of the Buttons bitmap.

The x2 and y2 coordinates of the control bitmap depend on how many 
'frames' the control expects in the ControlBitmap. For instance, the 
regular ButtonControl has 4 frames (Normal, MouseOver, Pressed and 
Disabled) and the ControlBitmap for a ButtonControl should be 4 times as 
wide as the specified Rect from the Position tag.

For instance:

    <Position Rect="182,100,246,115"/>
    <ControlBitmap Rect="0,203,259,218" Name="Buttons"/>

The Position Rect specifies a rectangular region that is 65 pixels
wide and 16 pixels high. (Remember that Rects are x2,y2 inclusive,
which means that you need to calculate the width like: w = x2 - x1 + 1.
Same goes for height)

Therefore the ControlBitmap needs to 65 * 4 = 260 pixels wide,
and 16 pixels high. If the control bitmap starts at 0,203 then you
arrive at: Rect="0,203,259,218"

For a SliderControl and VSliderControl thumb, you will need 3 frames. 
For a MultiStateControl you will need the ControlBitmap to be 4 frames 
wide and n frames high where n is the value defined by the NumStates 
attribute. State 0 will be in the first row of bitmaps, state 1 in 
the second row and so on.

Style:
------

The Style tag is used to define the style of a TextControl:

   <Style Align="Left" Font="Serif" Bold="Yes" Color="#FF00FF"/>

The Style tag must define the Font attribute which identifies 
the font (defined by the <Font> tag) to use. The Style tag may
also have an Align (Left, Center, Right), a Bold (Yes, No),
a Italic (Yes, No), an Underline (Yes, No) attribute, and a Color
tag that uses #RRGGBB colors in hex just like HTML does. Only the 
Font attribute is required, the others are optional.


ChangeWindow:
-------------

A ChangeWindow tag is used to specify that a button should change
the theme to a different window layout:

   <ChangeWindow Window="WindowShade">
   
The Window attribute defines which layout to activate when the user
clicks on this button. This layout must be defined in the current
theme.
   

ThemeInfo:
----------

The ThemeInfo tag allows the theme designers to give the theme a
name and to give themselves some credit. Pressing 'C' in the theme
ui or clicking on the Credits button brings up the credits in the
Title TextControl:

   <ThemeInfo Name="FreeAmp Theme" Author="Bill Bull & Robert Kaye" 
              EMail="[e-mail]" WebPage="http://www.freeamp.org"
              Misc="Based on artwork made from scanning my butt"/>

The Name attribute is the name of the theme, and the Author attribute
is the name of the Author(s). The EMail and WebPage attributes are
for authors to let the theme users know where to contact them and
which web page may have more info about the author/theme. The Misc
field is for whatever miscellaneous credit information you'd like to
include. Only the Name attribute is required.


Headlines: (Added for 2.0.2, updated for 2.0.5)
----------

FreeAmp now has the capabilities to download headlines from popular
websites such as Slashdot. The Headlines tag defines where to download
the headlines and what data to display:

<Headlines URL="http://www.slashdot.org/slashdot.xml"
           XMLPath="/backslash/story/title"
           XMLURLPath="/backslash/story/url"
		   DownloadInterval="3600"
		   ChangeInterval="10"/>

This Headlines tag shows the headlines from Slashdot in the 'HeadlineInfo'
TextField. The URL attribute specifies the HTTP location of the XML document 
that contains the headlines. This currently only works with XML documents
retrieved via HTTP! The XMLPath attribute defines which text fields to show 
as headlines. In this case each <title> tag that is nested inside of a 
<story> tag, which is in turn nested inside a <backslash> tag will be 
considered a headline. The XMLURLPath attribute defines which XML fields are 
URLs associated with the headlines. There must be an XMLURLPath field for 
every headline, otherwise the headline URLs will not function. For example, 
examine the following XML example:

    <?xml version="1.0"?><backslash
    xmlns:backslash="http://slashdot.org/backslash.dtd">
 
    <story>
       <title>Final Fantasy Movie Trailers</title>
       <url>http://slashdot.org/articles/00/03/07/0058211.shtml</url>

Given the above Headlines tag, it will show 'Final Fantasy Move Trailers'
in the HeadlineInfo field and if the user clicks on that text field,
FreeAmp will open a browser to http://slashdot.org/articles/00... 

The DownloadInterval attribute detemines how often the headlines should be 
downloaded, and the ChangeInterval attribute determines how quickly FreeAmp 
should flip through the headlines. Both intervals are specified in seconds, 
and in the example above, the headlines are grabbed once an hour and each 
headline is displayed for 10 seconds. All attributes except XMLURLPath 
are required.

The headlines are actually displayed in a TextField called HeadlineInfo.


QUICK REFERENCE

<Bitmap>
   -- specifies a bitmap for use in the theme
   
   Attributes:   

   Name -- The name of the bitmap as referenced by other controls
   File -- The file where this bitmap can be found
   TransColor -- An HTML color specification for use as the transparent color  
   
   Subtags:
   
   None.

<Font>

   -- specifies a font for use in the theme
   
   Attributes:   

   Name -- The name of the bitmap as referenced by other controls
   Face -- A comma separated list of font faces to use
   File -- The filename of the font to load from the theme package [optional]

   Subtags:
   
   None.

<Window>

   -- specifies a window layout.
   
   Attributes:
   
   Name -- The name of the window. Each theme must define a 'MainWindow'.

   Subtags:
   
   <BackgroundBitmap> (required)
   <Controls> (required)

<BackgroundBitmap>

   -- specifies which bitmap to use as the background bitmap
   
   Attributes:
   
   Name -- The name of the bitmap to use for the background
   Rect -- The which section of the bitmap to use as the background
   
   Subtags:
   
   None.
   

<Controls>
   
   -- specifies which controls to place in the window
   
   Attributes:
   
   None.
   
   Subtags:

   <MultiStateControl>
   <ButtonControl>
   <TextControl>
   <SliderControl>
   <VSliderControl>

   
<ButtonControl>

   -- specifies a name button control
   
   Attributes:
   
   Name -- the name of the control. See Appendix A for a list of
           possible control names.
   URL -- For the 'Logo' button only. This specifies the web page to
          go to if the user clicks on the button. Defaults to 
          http://www.freeamp.org if not specified.        

   Subtags:
   
   <Info> (required)
   <Position> (required)
   <ControlBitmap> (required) 

<TextControl>

   -- specifies a text display area