themehowto.txt

这是一个mp3的源代码

                        FreeAmp Theme HOWTO
                        -------------------
                            written by
                            Robert Kaye
                         ([e-mail])
        $Id: ThemeHowTo.txt,v 1.15 2000/01/10 22:28:03 robert Exp $

INTRODUCTION

FreeAmp 2.0 supports fully customizable themes -- anyone with experience
in Photoshop/Gimp and HTML should be able to create their own Themes.
These themes are platform independent -- they will look exactly the same
on Windows as they will on Linux. 

Unlike WinAmp, FreeAmp themes are not limited to having one layout for the 
controls. The FreeAmp window can be any shape and the button layouts
can be anything the theme designer desires. Care to leave out some 
buttons or display items you don't care for? Go ahead leave them out --
FreeAmp doesn't care.

This HOWTO will get you started writing themes for FreeAmp. Please note
that this HOWTO is still in the beta stages, much like FreeAmp 2.0.
If you find any problems with this HOWTO, please mail [e-mail]
with your comments, or better yet head over to Bugzilla and enter a 
bug report <http://www.freeamp.org/bugzilla>.


GETTING STARTED

To get started working on FreeAmp themes, I recommend that you 
grab FreeAmp.fat from the themes directory in your FreeAmp
installation and decompile it using the supplied program MakeTheme:
(If MakeTheme is not in the distribution for some reason, you can
get it from the FreeAmp website)

   MakeTheme -d freeamp.fat

Take a brief look at the theme.xml file and the bitmaps that get
unpacked. Or you can look at Appendix B. :-) Then read on.


THEMES

A theme consists of at least four files that get packaged into one
.fat file:

  1) A bitmap for buttons/controls
  2) A background bitmap for the player
  3) theme.xml, which is an XML document that describes the layout 
     of the theme
  4) A title.txt file which contains a descriptive name of the
     theme. Only the first line of this file is used.

Don't be scared by the XML -- in this case you might as well call it
an HTML-like syntax, which sounds less intimidating. :-)

A theme designer creates these three or more files in a separate 
directory and then points FreeAmp to these files. 

The ThemePath preference should point to the theme directory or a 
completed .fat file. To do this under Linux, edit the ThemePath preference 
in ~/.freeamp/preferences, or under Windows edit the 
HKEY_CURRENT_USER/Software/FreeAmp/FreeAmp v2.0/Main/ThemePath 
registry value to point to your theme directory.

If your theme supports the ReloadTheme button, you can edit the
theme on disk and then click the ReloadTheme button to re-parse and
reload the theme without exiting FreeAmp.

When you are done with your theme and want to ship it off to the
FreeAmp theme repository or to your friends, package it up using
the MakeTheme program bundled with FreeAmp. Simply do:

    MakeTheme mytheme.fat theme.xml title.txt *.bmp
    
in your theme directory. You can then add the mytheme.fat in
the options dialog to load your theme. 

Note: The .fat format is simple (no symlinks, no directories) 
implementation of a tar'ed, gzipped file. If you prefer you can
do:

    tar -czf mytheme.fat theme.xml title.txt *.bmp
    
It will give you the same result. NOTE: You must use _gzip_ not
the windows based pkzip or winzip.


BITMAPS

All controls in FreeAmp are bitmaps, and to keep things simple
for all platforms all bitmaps are Windows bitmap format (BMP). 
(Sorry, all you Linux fans. :-( ) It doesn't matter which bit depth 
your theme bitmaps are, but usually 256 color bitmaps will suffice 
while keeping the size of the theme down.

For each bitmap the theme designer can specify a color which will
be used as the transparent color in the bitmap. All pixels in that
bitmap that are deemed to be transparent, will never be shown on
a FreeAmp theme. This allows theme designers to create arbitrarily
shaped FreeAmp windows and controls.

Each bitmap is given a name -- other controls will refer back to
this name in the theme.xml file.


FONTS

TrueType fonts are used both on Linux and Windows. If you use some fancy 
font in a theme, there is a good chance that other people will not have 
that font on their machine. In that case, you should include your font 
in the theme package. Please make sure that you have the right to
distribute that font with theme. If you are unsure of the rights regarding
fonts, you may want to use Microsoft's WebFonts, which you can redistribute.

A font is given a name, which TextControl controls will refer back to.


RECTS

All throughout a theme descriptions Rect attributes are used. A Rect
specifies a rectangular region on a bitmap. The Rect is defined as

   Rect="x1,y1,x2,y2"
   
Where x2 and y2 are inclusive of the Rect.


THEME.XML

The actual theme file is an XML document. Right now FreeAmp only
supports XML documents encoded in ISO8859/1 (and even that has
not been thoroughly tested). Just assume that the theme.xml
file is a regular text file.

XML differs from HTML in quite a few respects, but if you are
familiar with HTML you should have no problem with XML. Just think
as a theme as a special kind of HTML document.

There are two major differences between HTML and XML. First, XML 
is case sensitive. So ButtonControl is not the same as buttoncontrol.
Second, XML has the concept of an empty tag where the two following
constructs are equivalent:

   <Info Desc="Subvert the dominant paradigm"> </Info>

   <Info Desc="Subvert the dominant paradigm"/>

The default FreeAmp theme makes copious use of the empty tag construct
since many theme details are specified using attributes. 'Desc' in the 
example above is an attribute to the Info tag. Attributes values *must*
always be enclosed by double quotes and the attribute names are
case sensitive as well.

Also, we currently do not have a DTD specified for these XML files.
Once we get out of beta, I will bring this HOWTO and a DTD up to
the latest and greatest info.

TITLE.TXT

The file TITLE.TXT should contain one line of text that gives the theme
a descriptive name. This text will be shown in the options dialog
when all the available themes are listed. Note: Only the first line
of text of this file will be used.

Bitmap:
-------

To specify a bitmap for use with a theme you might use:

<Bitmap Name="Background" File="background.bmp" TransColor="#FF0000"/>

This give the bitmap the name 'Background' and it tells FreeAmp
that the bitmap resides in background.bmp, and that the Transparent
color is primary red. The TransColor attribute specifies the color
that is transparent. Just like HTML it does this with the triple
hex notation with the # symbol. #FF0000 is red because it specifies all
red, no green and no blue.

You will want to specify one bitmap for the main background of your
FreeAmp theme and one bitmap for buttons. You can use as many bitmaps
as you like, but loading your theme om FreeAmp will be slower if you
have many bitmaps. 


Font:
-----

To specify a font:

<Font Name="San Serif" Face="Arial,Helvetica" File="verdana.ttf"/>

The Name attribute specifies the given name for this font that 
TextControls will use. The Face attribute specifies which font to use.
This can be a comma separated list. FreeAmp will first attempt to
find a font named Arial, and if it can't find that it will attempt
to font font called Helvetica and so on. If FreeAmp can't find any
of the specified fonts, it will use the default font. 

If the File attribute is given, the system will load the given font 
file before attempting to use the font. This allows theme designers to 
embed their favorite TrueType fonts in their themes. If you intend to
make your Theme available to others (and we hope you will!) please
make sure that you have the rights to distribute the fonts you embed
in your themes.


Window:
-------

FreeAmp supports different windows in the same theme. The theme
that ships with beta 4 only has one window, but later themes will
have support for window shades and other cool layouts. 

The default window that FreeAmp opens a theme in is called 'MainWindow'.
You may define as many other windows as you care -- make sure to
include a ChangeWindow button to allow the user to change between
windows. (See below for details)

To specify the main window, use this construct:

<Window Name="MainWindow">

A Window cannot be an empty tag. Inside the Window tag you will need to
define <BackgroundBitmap> and <Controls>.


BackgroundBitmap:
-----------------

This tag tells FreeAmp which bitmap to use a the background for this
window:

    <BackgroundBitmap Name="Background" Rect="0, 0, 327, 191"/>

The attributes include the Name, which refers to a name of a Bitmap
as defined above, and a Rect which specifies the a rectangular area of
the bitmap to use as the background.


Controls:
---------

This tag has no attributes. It is a container for all the controls
that are to be placed on a window. Inside of the Controls tag you may
include <MultiStateControl>, <ButtonControl>, <TextControl>,
<SliderControl> and <VSliderControl> tags.


ButtonControl:
--------------

Ok, now we're getting to the heart of FreeAmp themes. A ButtonControl
presents a button to the user. The button may have 4 different states:
 
    Normal, MouseOver, Pressed, and Disabled
    
A ControlBitmap (see below) will define bitmaps for each of these
states. The ButtonControl tag only has one attribute:

    <ButtonControl Name="Stop">

The Name of the button is corresponds to a function in FreeAmp. In the
case above, the control is tied to the Stop function. If the user presses
this button the player will stop playing. See Appendix A at
the end of this howto for a list of buttons that can be defined.
The one exception to this rule are buttons that define a <ChangeWindow>
tag. These buttons are used to switch to a different window layout
and should use a name is not used by FreeAmp. I suggest that you use
the name of the window layout that the ChangeWindow switches to. (Don't
you hate people who end their sentences in prepositions?) 

Buttons can be any arbitrary shape if the source bitmap specifies a
transparent color with the TransColor attribute. Any portion of a button
that is visible will be considered to be part of the active area of the
button. When the user moves the mouse over an active portion of the
button, a hint for that button is displayed in the Info text field.
If the user clicks on the active area of a button it will be
interpreted as a button press.

For the 'Logo' button the theme designer can specifiy a 'URL' attribute,
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> tag.

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

A MultiStateControl is just like a button, but it can take on different