themehowto.txt

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

                        FreeAmp Theme HOWTO
                        -------------------
                            written by
                            Robert Kaye
                         ([e-mail])
        $Id: ThemeHowTo.txt,v 1.19 2000/11/02 14:34:54 robert Exp $
                    (Updated for version 2.1.0)

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.

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 unzip it using your favorite ZIP program. A FreeAmp
theme file is just a ZIP file with the extension changed from .zip to
.fat. Some older themes may need to get unpackaged with the MakeTheme
tool that is available fromt he freeamp.org website.

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. Please place only a simple descriptive name in this file.
     Use the ThemeInfo tag in theme.xml for giving detailed theme credits.
     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.1/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
any stinking zip program you can find. Rename the resultant .zip
file to have a .fat extension and you're done.

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

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 a <Panel>.


Panel & TogglePanel:
--------------------

Each window needs to have at least one Panel. Panels can be linked to
buttons which open and close the panels. The main FreeAmp theme is
implemented using 3 panels: The top portion of the player that contains
the display area, the equalizer section and the buttons on the bottom of
the player. To specify a simple panel that does not does not have any
pop-out panels, use the following:

  <Panel Name="Default" Bitmap="Background" Pos="0,0" Rect="0,0,327,95"
         ZOrder="1">

This specifies a panel named 'Default', using the Rect (0,0,327,95) area
of bitmap 'Background' as the background. Pos specifies the panel will be 
located at the logical theme origin and the default ZOrder of 1. If
you do not plan on having panels that open/close you will need to
simply make sure the background bitmap rects are correct, and you can 
simply ignore Pos and ZOrder and set them to the defaults shown above.

If you'd like to have fancy panels that pop open/closed to expose/hide
features, you need to define multiple Panel tags inside the Window tag.
For instance, the lower Panel in the freeamp theme is defined as follows:

    <Panel Name="PlayerBottom" Bitmap="Background"
           Rect="0, 95, 327, 161" Pos="0,95" TogglePos="0,170" ZOrder="2"
           OnCloseHide="Equalizer" OnOpenShow="Equalizer">

Name, Bitmap and Rect are the same as in the example above. Pos indicates
where the panel will be placed when the panel is closed (not toggled). When
the user toggles the panel, the panel will be moved to the TogglePos. Upon
toggling the panel again, the panel moves back to Pos. One panel should
be specified as the base panel, and other panels should then be specified
in relation to the base panel.

ZOrder specifies the how overlapping Panels will be ordered. If two
or more panels overlap, the panel with the highest ZOrder value will
be shown on top and the panel with the lowest ZOrder will be shown
at the bottom.

Optionally, you can specify to show or hide other panels when a panel
gets toggled. The OnOpenShow, OnOpenHide, OnCloseShow, and OnCloseHide
attributes specified other panels to show/hide when the current panel is
opened/closed. In the example above, the Equalizer panel is hidden when
the PlayerBottom panel is closed, and the same Equalizer panel is shown
when the PlayerBottom panel is opened.

When you have a panel that can be opened or closed, you will need to
create a button that will open/close the panel when the button is
pressed. This button can be of any name (make sure to not use one
of the names that is already used by other components), but it must
contain a TogglePanel tag:

   <TogglePanel Panel="PlayerBottom"/>

When the user clicks this button the PlayerBottom panel will get toggled. 

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


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,