Difference between revisions of "How to create a theme"

From OsirisWiki
Jump to: navigation, search
(Created page with '== 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 ...')
 
(Full Restore)
 
(9 intermediate revisions by 2 users not shown)
Line 8: Line 8:
  
 
Each state contains a definition for a BoxTile image of the Background, ProgressBar, Overlay, HoverOverlay, and PressedOverlay.
 
Each state contains a definition for a BoxTile image of the Background, ProgressBar, Overlay, HoverOverlay, and PressedOverlay.
 +
 +
The skin information is defined with a <code>Theme</code> root element.
 +
 +
<source lang="xml">
 +
<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>
 +
</source>
 +
 +
== States ==
 +
The <States></States> section contains definitions for 5 states:
 +
# Default
 +
# Discharging
 +
# LowBattery
 +
# CriticalBattery
 +
# Charging
 +
 +
The Default section would be defined as:
 +
<source lang="xml">
 +
<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>
 +
</source>
 +
 +
* <code>Font</code> ''(optional)'': Specifies the font name, size, and style.  If not specified, the user's default font ''(see [[Preferences#BatteryBar_font|Preferences]])'' is used.
 +
* <code>TextColor</code>: The color of the text shown.  Is is defined as A,R,G,B or R,G,B.
 +
* <code>TextShadow</code>: If <code>True</code>, a shadow is drawn underneath the text
 +
* <code>Padding</code>: 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 <code>left, top, right, bottom</code>.
 +
* <code>Background, ProgressBar, Overlay, HoverOverlay, PressedOverlay</code>: 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.
 +
: <code>Overlay</code>: Normal state
 +
: <code>HoverOverlay</code>: When the mouse is hovering over the bar
 +
: <code>PressedOverlay</code>: When the mouse button is pressed on the bar
  
 
== Images ==
 
== Images ==
Line 17: Line 73:
  
 
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.
 
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
 +
<source lang="xml">
 +
<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>
 +
</source>
 +
 +
* <code>CornerTopLeft</code> through <code>Center</code>: 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 <code>Center</code> image).
 +
 +
* <code>Margin</code>: 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 <code>left, top, right, bottom</code>.
 +
 +
== ProgressBar ==
 +
The <code>ProgressBar</code> is a BoxTile with some additional properties
 +
 +
<source lang="xml">
 +
<ProgressBar>
 +
<Center>Charging\center.png</Center>
 +
<Margin>5,4,8,4</Margin>
 +
<Clipping>0,0,8,0</Clipping>
 +
<BorderIsOutside>True</BorderIsOutside>
 +
</ProgressBar>
 +
</source>
 +
 +
* <code>Center</code>: 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 <code>Center</code> image.
 +
* <code>Margin</code>: 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.
 +
* <code>Clipping</code>: 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 <code>State</code> image.  This is very useful when using <code>BorderIsOutside</code>.
 +
* <code>BorderIsOutside</code>: The size of the progress bar image is determined by <code>width * percentage</code>, so at 50% battery, the progress bar will fill 50% of the area within the <code>Margin</code>.  If you use border images in the progress bar, they will be drawn within the progress bar's width.  If this value is <code>True</code>, the <code>Center</code> image will be equal to the <code>width * percentage</code> 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.

Latest revision as of 13:30, 26 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.