Appearance Manager Documentation Thread.

[Fatman_do]

For information on how to use Appearance Manager within GB-PVR, see the Users Guide

Appearance Manager Skin Development.

The Appearance Manager plugin has several requirements that must be considered when creating a skin.
[SIZE="5"]
Directory Structure[/SIZE]

Under the skin named directory, include the following directories:

\Appearance
\Appearance\Backgrounds
\Appearance\ButtonSets
\Appearance\Languages
\Appearance\SkinEffects

Directories Explained

\Appearance

This folder contains the skin.xml file and typically any other optional image files that you may want displayed. Optional image files can be located in another directory and called in the skin.xml file using proper skinning path methods.
Example: <DrawImage filename="..\Images\EyeChart.png" loc="10,10" size="220,220"/>

\Appearance\Backgrounds

This folder is where background sub-folder options are located. If you want only a few background options, you must still place them in a sub-folder.
Example:
\Appearance\Backgrounds\Skin-X\
background-1.jpg
background-2.jpg
background-3.jpg

File names can be anything .jpg

Providing additional folders results in those sub-folder names being displayed in the top button in the appearance manager plugin. The user then can cycle through those directories using left or right arrow keys or buttons.

Example:
\Appearance\Backgrounds\Colors\
Black.jpg
Blue.jpg
Green.jpg
\Appearance\Backgrounds\Skin-X\
background-1.jpg
background-2.jpg
background-3.jpg

\Appearance\ButtonSets
This folder is where menu buttons sub-folder options are located. If you want only one button option, you must still place them in a sub-folder.
Example:
\Appearance\ButtonSets\None\
MainButtonSelected.png (Required)
MainButtonNormal.png (Required)

Additional buttons that the skin uses can be included here using the same names as called by the skin.

Adding additional sub-folders with different buttons will result in those buttons being displayed by appearance manager when the user presses left or right arrow keys or buttons.

\Appearance\ButtonSets\None\
MainButtonSelected.png
MainButtonNormal.png
\Appearance\ButtonSets\Black Jack\
MainButtonSelected.png
MainButtonNormal.png

\Appearance\Languages
This is where sub-folders with language.xml files are located.
This is optional and not required. Language files can be downloaded from the SkinPacks wiki page.

\Appearance\SkinEffects
Skin effects are static images that are displayed over the top of the background images.
Repeat the same method with directories here as well.
Example:
\Appearance\SkinEffects\Black Jack\
\Appearance\SkinEffects\None\

Additionally, list plugin sub directories under these folders for specific skin effects created. More info will be included in the SkinEffects section later.
[SIZE="5"]
Required Image Files[/SIZE]

Without the following files, Appearance Manager will report errors when attempting to run.

Located in the skin "root" directory, Appearance Manager looks for the following files:

MainButtonNormal.png
MainButtonSelected.png
MainBackground.jpg
Background.jpg

In the skin's \Main Menu directory:

se.png


This is the end of the required section.

[Old Dog]

The skin you are using now has a subdirectory for it's main menu, if you use the TV Guide, there is a subdirectory for it, ditto for the weather plugin. Appearance Manger has it's own subdirectory too. Enough said.

Well, not quite. There are a couple of note worthy features about the Appearance subdirectory. The most obvious is the rather full subdirectory structures that are rooted in Appearance. If you examine these directories, you'll find several that are empty! Empty directories in the Appearance directory tree serve a special purpose which we will discuss as the associated topics arise. Till then--Never delete empty directories in the Appearance subdirectory structures!

The other interesting feature in the Appearance directory is the skin.xml. While it serves the same function as all other skin.xml files, it is unique in that it is usually designed to look as much like the main menu as possible. It uses the same buttons, positioned and sized the same, etc.

BTW, if there is no Appearance\skin.xml, the Appearance button will not be displayed in your main menu.

-David

[Old Dog]

Since this is a tutorial, I have created an AM Tutorial Skin. If you want to work through the tutorial as it unfolds, then you should download the skin now...
http://starling08.home.mindspring.com/AM-Tutorial.zip

Of course an Appearance Manager enabled skin requires AM.
AM is available as a separate download from the wiki.
http://gbpvr.com/pmwiki/uploads/Plugin/Appearance.zip

AM needs the Common GBPVR Utilites library which you can download from the Wiki.
http://gbpvr.com/pmwiki/uploads/Developm...lities.zip

(In the future, I hope to eliminate this dependency.)

BTW, compare the previous post's time with this one. It took 2 hours and four minutes to create this new skin.

-David

[Old Dog]

Now that you have the AM Tutorial skin installed, take a quick look around.

[Old Dog]

Okay, time to get your feet wet...

Bring up your AM-Tutorial skin, select and press the Appearance button.

Select the Sky Blue background for the Main Menu and the Royal Blue background for the plugins.

Save your selections which should look something like this...

[Old Dog]

Using Window's explorer, poke around until you find the "AM Tutorial\Appearance\Backgrounds\Colors" directory.

Select the RubyWine, LightBlue, and Blue jpg files and open them with a graphics file viewer or editor.
You should recognize these as the backgrounds you have been using thus far in this tutorial.

These files are examples of optimal AM background files. What makes them optimal is the abundant lack of detail. No wispy contrails, no scratchy brushed metal, or crackly carbon fibers--nothing but pure rich color.

By using plain color backgrounds we have created a new selection dimension for the end user. Remember AM is all about choices. When it comes to backgrounds and colors, the GBPVR Blue skin gives the end user ONE choice. Here you see nine choices for the main menu and nine for the sub menus, 18 choices, so easy to create. Somewhere, in one of my posts, I pointed out that The Collection had over 10,000 combinations. I lied. I think there are really over a million.

Most skinners probably don't think about purple to often. I know I don't and I've never seen a purple Contour. Pop over to the Wiki and take a look at the Chameleon skin. I think the purple one is the coolest example on the page and I don't really care for purple.
http://gbpvr.com/pmwiki/pmwiki.php/Skin/Chameleon

When giving the end user choices, be sure to give them choices they like, not just ones you like!

What would GBPVR be without the Christmas Collection or even the Floral Collection? Yes, AM supports wallpaper backgrounds in a simple elegant manner. However, we will set aside this topic for now so that we can move on to areas of more interest to the skinner looking to get on with their new masterpiece.

[Fatman_do]

[SIZE="5"]Skinning .xml Guidelines[/SIZE]

For reference, all skinning examples will follow the xml files provided in the AM Tutorial skin.

The following things should be taken into consideration in your .xml files for your skin:

\main menu\skin.xml should use the following items in bold as a baseline.

<CompositeImage name="Background" size="720,480">
<!-- Appearance Mangager requires MainBackground.jpg in the skin's root directory (one up from here) -->
<DrawImage filename="..\MainBackground.jpg" loc="0,0" size="720,480"/>
<!-- Appearance Mangager requires the skin effect se.png in the main menu directory -->
<DrawImage filename="se.png" loc="0,0" size="720,480"/>
</CompositeImage>

<CompositeImage name="SelectedButtonImage" size="240,35">
<!-- Appearance Mangager requires MainButtonSelected.png in the skin's root directory (one up from here) -->
<DrawImage filename="..\MainButtonSelected.png" loc="0,0" size="240,35"/>
<DrawTextWithOutline text="@buttonText" loc="40,1" size="240,35" fillColor="#1A1000" borderColor="Beige" outlineWidth="1" textStyle="SelectedButtonText" align="Left"/>
</CompositeImage>

<CompositeImage name="NormalButtonImage" size="240,35">
<!-- Appearance Mangager requires MainButtonNormal.png in the skin's root directory (one up from here) -->
<DrawImage filename="..\MainButtonNormal.png" loc="0,0" size="240,35"/>
<DrawTextWithOutline text="@buttonText" loc="40,1" size="240,35" fillColor="Beige" borderColor="#1A1000" outlineWidth="1" textStyle="ButtonText" align="Left"/>
</CompositeImage>

<CompositeImage name="CenteredSelectedButtonImage" size="240,35">
<!-- Appearance Mangager requires MainButtonSelected.png in the skin's root directory (one up from here) -->
<DrawImage filename="..\MainButtonSelected.png" loc="0,0" size="240,35"/>
<DrawTextWithOutline text="@buttonText" loc="40,1" size="240,35" fillColor="#1A1000" borderColor="Beige" outlineWidth="1" textStyle="SelectedButtonText" align="Left"/>
</CompositeImage>

Notes:

• DrawTextWithOutline is used in the AM Tutorial, but is not a requirement.
  
• Button sizes are also up to the skinner's preferences as well.
  
• Appearance Manager copies button images (no renaming) to the skin root directory. This is the reason for "..\MainButtonNormal.png", ect.
  
• Appearance Manager renames backgrounds selected from the plugin to "MainBackground.jpg" and "Background.jpg" and places them in the skin root directory as well.
  
• SkinEffects are located in the plugin directories and are named "se.png" (no preceeding "..\"). Appearance Manager renames these files appropriately when copied from the \Appearance\SkinEffects directories.
  

\baseskin.xml should use the following items in bold as a baseline.

<CompositeImages>
[COLOR="SeaGreen"]<!--The main menu buttons in this skin are different in size and shape, so they must be defined separately in "mainmenu\skin.xml".-->

<!-- image used for a selected button -->[/COLOR]
<CompositeImage name="SelectedButtonImage" size="135,28">
<!-- Appearance Mangager recommends that button image files be kept in the skin's root directory (one up from here) File name is arbitrary. -->
<DrawImage filename="..\SelectedButton.png" loc="0,0" size="135,28"/>
<DrawTextWithOutline text="@buttonText" loc="6,0" size="135,28" fillColor="#1A1000" borderColor="Beige" outlineWidth="1" textStyle="SelectedButtonText" align="Left"/>
</CompositeImage>

<!-- image used for a normal button -->
<CompositeImage name="NormalButtonImage" size="135,28">
<!-- Appearance Mangager recommends that button image files be kept in the skin's root directory (one up from here) File name is arbitrary. -->
<DrawImage filename="..\NormalButton.png" loc="0,0" size="135,28"/>
<DrawTextWithOutline text="@buttonText" loc="6,0" size="135,28" fillColor="Beige" borderColor="#1A1000" outlineWidth="1" textStyle="ButtonText" align="Left"/>
</CompositeImage>

<!-- image used for a popup selected button -->
<CompositeImage name="PopupSelectedButtonImage" size="124,28">
<!-- Appearance Mangager recommends that button image files be kept in the skin's root directory (one up from here) File name is arbitrary. -->
<DrawImage filename="..\PopupSelectedButton.png" loc="0,0" size="124,28"/>
<DrawTextWithOutline text="@buttonText" loc="0,0" size="124,28" fillColor="#1A1000" borderColor="Beige" outlineWidth="1" textStyle="SelectedButtonText" align="Center"/>
</CompositeImage>

<!-- image used for a popup normal button -->
<CompositeImage name="PopupNormalButtonImage" size="124,28">
<!-- Appearance Mangager recommends that button image files be kept in the skin's root directory (one up from here) File name is arbitrary. -->
<DrawImage filename="..\PopupNormalButton.png" loc="0,0" size="124,28"/>
<DrawTextWithOutline text="@buttonText" loc="0,0" size="124,28" fillColor="Beige" borderColor="#1A1000" outlineWidth="1" textStyle="ButtonText" align="Center"/>
</CompositeImage>
</CompositeImages>

Notes:

• Button names "NormalButton.png", ect. are common to most AM skins, but the names you choose here can be anything.
  
• .png files named to match button names used here (and in plugins) must also exsist in the skin root directory.
  
• Include .png files for these button names in the proper \Appearance\ButtonSets sub directory as well.
  
• Text format and button sizes here are skinner's preference here as well.
  

Now, lets take a look at a typical plugin skin.xml that uses the same guidelines as above.

<CompositeImages>
<CompositeImage name="Background" size="720,480">
<!--Appearance Mangager requires Background.jpg in the skin's root directory (one up from here)-->
<DrawImage filename="..\Background.jpg" loc="0,0" size="720,480"/>
<!--Optional per plugin. Appearance Mangager recommends the skin effect se.png in the plugin's directory -->
<DrawImage filename="se.png" loc="0,0" size="720,480"/>
<Element name="VisualizationsPosition" loc="62,220" size="130,105"/>
</CompositeImage>

[COLOR="SeaGreen"] <!--
<CompositeImage name="SelectedButtonImage" size="135,28">
<DrawImage filename="..\SelectedButton.png" loc="0,0" size="135,28"/>
<DrawText text="@buttonText" loc="0,2" size="135,28" textStyle="SelectedButtonText" align="Center" />
</CompositeImage>

<CompositeImage name="NormalButtonImage" size="135,28">
<DrawImage filename="..\NormalButton.png" loc="0,0" size="135,28"/>
<DrawText text="@buttonText" loc="0,2" size="135,28" textStyle="ButtonText" align="Center" />
</CompositeImage>
-->[/COLOR]

Notes:

• Background image uses "..\Background.jpg"
  
• se.png is located in plugin directory, NOT "..\se.png"
  
• Buttons are commented out so the plugin will use those that are in BaseSkin.xml.
  
• If buttons are needed that are specific to this plugin, those lines would be used with proper "..\<Name of Your Button>.png"
  

This is the end of the skinning .xml section.

[Fatman_do]

[SIZE="5"]Image Guidelines[/SIZE]

Browse through the directory structure of the AM Tutorial skin's Appearance folder to familiarize yourself much better than can be described here.

Backgrounds

• To review, Appearance Manager expects and creates "Mainbackground.jpg" and "Background.jpg" in the skin root directory.
  
• In the \Appearance\Backgrounds directory, you must provide at least one directory with .jpg images in it of any name.
  
• Skins for all plugins need to point back to the skin root directory for the backgrounds "..\Mainbackground.jpg" & "..\Background.jpg"
  
• Backgrounds can be solid colors, simple images, or elaborate "wallpaper".
  

ButtonSets

• Appearance Manager expects "MainButtonNormal.png" and "MainButtonSelected.png" to be in the skin root directory and the \Appearance\ButtonSets\ sub-directories.
  
• You can use just these two names, but it is recommended that you use different image files for plugins than the mainmenu.
  
• Plugin buttons can be nothing more than renamed copies of the mainmenu buttons.
  
• Appearance manager will copy all images in the \Appearance\ButtonSets\ sub-directories to the skin root directory, so any other images you want to be interchangeable could be placed here as well.
  

SkinEffects

• Appearance Manager expects "se.png" files in the skin's \main menu folder, and will create "se.png" in all plugin subfolders that are listed in the \Appearance\SkinEffects\ sub-directories.
  
• SkinEffect files in those sub-directories must begin with the "se-" prefix.
  
• Any "se-<yournames>.png" found will be copied to the correct directory and renamed "se.png"

Skin Effects: Blank Plugin-Directories

• If you provide blank plugin-directories, as in the \AM Tutorial\Appearance\SkinEffects\None\Music Library directory, Appearance Manager will search for "se-Default.png" located in that "root" sub-directory (in this example \AM Tutorial\Appearance\SkinEffects\None\.
  
• If the file is not located up one level, Appearance manager will see if there is a "se-Default.png" in the \AM Tutorial\Appearance\SkinEffects\ directory.
  
• Appearance manager will then copy "se-Default.png" with the name of "se.png" to the skin plugin directories match the empty ones in the SkinEffects sub-folder.
  

[Old Dog]

So where did those magical contrails, the finely brushed metal, and cool carbon fibers go?

1. They blew away
   
2. rust
   
3. Ron Popeil made fishing poles out of them
   
4. They're Skin Effects!
   

Bring up your AM-Tutorial skin, select and press the Appearance button.

Select the Skin Effect button then Arrow-Left or Arrow-Right until the Black bezel at the top of the menu screen disappears. (You just removed the skin effects.)

Save your changes and return to the main menu.

[Old Dog]

Open the following files with PhotoShop...

• AM Tutorial\Appearance\SkinEffects\Black Jack\Main Menu\se-BlackJack-Main.png
  
• AM Tutorial\Appearance\SkinEffects\Black Jack\Search\se-BlackJack-Search.png
  
• AM Tutorial\Appearance\SkinEffects\Black Jack\Recordings\se-BlackJack-Recordings.png
  

These are skin effect files. More than anything else, these files establish the charater of your skin. By changing skin effects the appearance of your pvr program can range from GBPVR Blue to anything imaginable, how about a Purple Chameleon Contour.

Note that the graphics components in a skin effect file are static, they don't change position, size, or color while using the plugin.