themehowto.txt

FreeAMP(MP3播放)程序源代码-用来研究MP3解码

which will pop open the web browser and go to that web page. If the
URL attribute is not specified, the button will open the browser to
http://www.freeamp.org


The ButtonControl will need to include the <Info>, <Position>, and
<ControlBitmap> and optionally include the <ChangeWindow> or <TogglePanel>
tags.

MultiStateControl:
------------------

A MultiStateControl is just like a button, but it can take on different
states. The PlayPause button is implemented as a MultiStateControl and it
therefore doubles as the Pause button as well:

    <MultiStateControl Name="PlayPause" NumStates="2">
    
The NumStates attribute defines how many different states a button
can have. This number depends on the type of control that is being
implemented. The PlayPause and the Shuffle controls will always have 2 states
(Play/Pause, ShuffleNone/Shuffle) and the Repeat control will always 
have 3 states (RepeatNone,RepeatOne,RepeatAll).    

The ButtonControl will need to include the <Info>, <Position>, and
<ControlBitmap> tags.


TextControl:
------------

A text control is an area where some information is displayed:

    <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">  

SliderControls are also used to control the equalizer channels:

    <SliderControl Name="Eq1" Notch="50%" NotchWidth="4">  

The Name can either be Volume, Seek, Balance, Preamp, or Eq0 - Eq9 
for the Equalizer sliders. The optional Notch and NotchWidth attributes
allow the theme designer to specify a 'notch' that can be used as a 
default position for a slider. When the user moves the slider across
the notch position, the slider will snap to the notch postion. The
eq sliders use notches in order to make it easier to set all the eq
sliders to the neutral 50% position. Notch defines the slider percentage
where the notch should be located, and NotchWidth defines the
total width of the Notch. When the slider thumb is inside this NotchWidth
zone, the slider remains snapped to the Notch center.

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:
--------------

A VSliderControl is just a vertical version of the SliderControl. Please
refer to the SliderControl docs above.

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.

If you intend on submitting your themes to the FreeAmp.org page, please
fill out the ThemeInfo tag completely. The script on our web page that
automatically generates the themes page will open up each theme and pull
out the ThemeInfo to display that on the theme page. If you don't fill out
the ThemeInfo tag, you will not get credit for your theme.

Headlines:
----------

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:
   
   <Panel> (required)

<Panel>

   -- specifies a panel and a background bitmap
   
   Attributes:
   
   Name -- The name of the Panel. Each Windows must defined one Panel.
   Bitmap -- The bitmap to use as the background
   Rect -- The rectangular area of the background bitmap to use as the
           panel surface.