Revision as of 00:27, 18 November 2010

>== Structure of a theme == A theme consists of two parts, 1) an XML definition file, and 2) image files

Theme XML Definition File

The theme definition file, usually named theme.xml, defines how the theme will look and what images files will be used.

The theme definition contains 5 states, Default, Discharging, LowBattery, CriticalBattery, and Charging.

Each state contains a definition for a BoxTile image of the Background, ProgressBar, Overlay, HoverOverlay, and PressedOverlay.

The skin information is defined with a Theme root element.

<Theme>
	<Author>Author Name</Author>
	<Date>1/22/2009</Date>
	<Description>Theme description (not currently used)</Description>
	<Name>ThemeName (shown in the Themes list)</Name>
	<Version>1.0</Version>
	<States>
	</States>
</Theme>

States

The <States></States> section contains definitions for 5 states:

1. Default
2. Discharging
3. LowBattery
4. CriticalBattery
5. Charging

The Default section would be defined as:

<Default>
	<Font>
		<Name>Segoe UI</Name>
		<Size>11</Size>
		<Style>Regular</Style>
	</Font>
	<TextColor>200, 255, 255, 255</TextColor>
	<TextShadow>True</TextShadow>
	<Padding>1</Padding>
	<Background>
	</Background>
	<ProgressBar>
	</ProgressBar>
	<Overlay>
	</Overlay>
	<HoverOverlay>
	</HoverOverlay>
	<PressedOverlay>
	</PressedOverlay>
</Default>

• Font (optional): Specifies the font name, size, and style. If not specified, the user's default font (see Preferences) is used.
• TextColor: The color of the text shown. Is is defined as A,R,G,B or R,G,B.
• TextShadow: If True, a shadow is drawn underneath the text
• Padding: Specifies how far from the edge of the drawing area the text should be centered. Defined either as a single value (applies to all four edges) or as left, top, right, bottom.
• Background, ProgressBar, Overlay, HoverOverlay, PressedOverlay: BoxTile definitions used to draw the final State image. Each of the sections is optional.

The state is drawn by first drawing the Background, then the ProgressBar, then the appropriate Overlay.

Overlay: Normal state

HoverOverlay: When the mouse is hovering over the bar

PressedOverlay: When the mouse button is pressed on the bar

Images

Images in a BatteryBar theme are defined as BoxTiles.

A BoxTile image is made up of 9 separate images, 4 borders (top, left, bottom, right), 4 corners (top-left, top-right, bottom-left, bottom-right) and 1 center image.

The easiest way to create a BoxTile image is to first create a full-size version of the image and then slice the image into the 9 corresponding parts.

The 4 corner images are drawn exactly as-is. The 4 border images are tiled. The top and bottom images are titled horizontally and the left and right images are tiled vertically. The center image is stretched vertically and tiled horizontally.

BoxTile XML

Below is a sample XML for the Background BoxTile

<Background>
	<CornerTopLeft>Background\topleft.png</CornerTopLeft>
	<CornerTopRight>Background\topright.png</CornerTopRight>
	<CornerBottomLeft>Background\bottomleft.png</CornerBottomLeft>
	<CornerBottomRight>Background\bottomright.png</CornerBottomRight>
	<LeftBorder>Background\left.png</LeftBorder>
	<RightBorder>Background\right.png</RightBorder>
	<TopBorder>Background\top.png</TopBorder>
	<BottomBorder>Background\bottom.png</BottomBorder>
	<Center>Background\center.png</Center>
	<Margin>0,3,0,3</Margin>
</Background>

• CornerTopLeft through Center: defines a path, relative to the XML file, where the image is location. Each image is optional. Only images that are specified will be drawn (for example, some BoxTiles only specify the Center image).

• Margin: Defines the number of pixels from the edge of the drawing surface where the BoxTile is to be drawn. Defined either as a single value (applies to all four edges) or as left, top, right, bottom.

ProgressBar

The ProgressBar is a BoxTile with some additional properties

<ProgressBar>
	<Center>Charging\center.png</Center>
	<Margin>5,4,8,4</Margin>
	<Clipping>0,0,8,0</Clipping>
	<BorderIsOutside>True</BorderIsOutside>
</ProgressBar>

• Center: All 9 BoxTile images (corners, borders, and center) are available for the progress bar and can be defined here. This example is only using the Center image.
• Margin: Defines how far from the edge to draw the image. For a progress bar, this is usually the same Margin as the background PLUS the size of the borders so that the progress bar is drawn inside of the background's borders.
• Clipping: Defines a cropping area for the progress bar. In the example above, the progress bar will be cropped so that the progress bar will never cover the far right 8 pixels of the State image. This is very useful when using BorderIsOutside.
• BorderIsOutside: The size of the progress bar image is determined by width * percentage, so at 50% battery, the progress bar will fill 50% of the area within the Margin. If you use border images in the progress bar, they will be drawn within the progress bar's width. If this value is True, the Center image will be equal to the width * percentage at the borders will be added ouside. This is very useful to adding shadows or similar effects to the progress bar without affecting its size.