ThrottleLauncher Theme Design

ThrottleLauncher Theme Design

From ThrottleWiki

Jump to: navigation, search

Contents

Theme structure

A ThrottleLauncher theme is divided in two different kind of files:

  • The setups: this files contain the functionality of the theme. They contain references to pages, rows, icons, text elements, events applications, skins, etc.
  • The skins:are files that are referenced from the setups files and that contain visual information like colors, backgrounds, fonttypes and similar. The skins are referenced by it's folder name and that folder must contain a skin.xml file that's the main entry point for the skin.

Frequently the setup files will be located directly inside the theme folder. It's mandatory to have a file named "config.xml" that is the entry point of the whole theme. This config.xml file may have references to other xml files for each page that the theme contains.


A typical config.xml file looks like this:

<?xml version="1.0" encoding="utf-8"?>
<root>
<configuration
  name="..."
  ... >
  <variables>
    <variable name="..." ... />
    <variable name="..." ... />
     ...
   </variables>
  <param name="value" />
  <param name="value" />
  ...
</configuration>
 <page ... />
 <page ... />
  ...
 <footer ...>
  ...
 </footer>
</root>

First Steps

To start playing with ThrottleLauncher theming I recommend opening an existing theme and doing small modifications to it to feel conftable with the syntax and the tags. If you open a config.xml file you'll see two diferent sections:

  • The configuration section: it's used to define the general settings for the theme and to define the configurable variables that the theme is going to use. This variables can be included in the configuration interface so users without any knowledge of xml can easily customize the theme. Also the configuration section includes some data about the theme itself and the author. A typical configuration section could be this one:
<configuration name="" recomendedHeight="271" hideBottomBar="false" description="" minthrottleversion="" comments="" createdby="">
		<variables>
			<var name="sep4" description="UI Tweaks" default="" type="separator" />
			<var name="activateeffect" description="fade in" default="true" type="boolean" />		
		</variables>
	<param name="VGACompatibility" value="true"/>
	<param name="skin" value="Setups\Touchflo3d\skins\dark\back" />
</configuration>
  • The main theme section: The main theme section contains the theme structure. At first level it contains a list of pages and an optional footer element that will be usually located at the bottom.

The configuration section

As said the configuration section defines the global variables and settings for the whole theme, within the configuration tag.

Configuration parameters

It may contain several params tags with the following syntax:

<param name="PARAMNAME" value="PARAMVALUE"/>

The most common property names you can specify are:

  • Mandatory
    • VGACompatibility: measures specified in the theme will be multiplied by two if the device is VGA. This will cause the png's to scale only if it's necessary. For example if you define in the theme an icon of 32x32 and you use a png that is 32x32, if you have VGACompatibility set to true, when the device is VGA the icon will measure 64x64 and the icon will be double scaled. On the opposite if you define VGACompatibility=true and you define the icon in the theme as 32x32 but you include a 64x64 png file, the icon will be scaled down to 32x32 on non VGA devices but it will be painted without any scaling in VGA.
    • skin: defines the path of the folder of the skin to use. Relative to the app folder.
  • Optional
    • fps: defines the FramesPerSecond that the app is able to paint. The minimun value recommended is 8 and the maximum is 24. The smaller the value, the less battery consumption the app will have but the animations will be less smooth
    • speeddecreaserate: factor that sets how fast the speed will be decreased in kinetic scrolling. IMPORTANT: set a value greater than 1.
    • speedinitmultiply: factor that multiplies the value of your finger speed when starting kinetic scrolling.
    • osdenabled: If true, the OSD top bar will be shown when an element is selected. By default the value is false.
    • imagecontactnophoto: Relative path to the image to be used if there's no contact photo.
    • minclicktime: Min lapse time in miliseconds between the mouse down and up events to perform a click over the pressed element.
    • pagechangeanimation: defines the animation used to change pages.
    • clearbackbuffers: defines if when a page is exited it's and it's row's backbuffer's will be freed. This will save some memory but will make page changing a little bit slower.
    • keeppagebackbuffer: if clearbackbuffers is specified will make it only to free the row's backbuffers and keep the page one. This will save less memory but page changing will be faster. Though if you change page and scroll immediately you will notice a little bit of flickering.
    • vibrateefects: if true, it allows the device to vibrate with some user actions. Currently the vibration is only used by the WheelOfFortune scrolling mode.
    • showselectedpage: if true icons that target to pages will be marked as selected.
    • gohometimeout: will make the app go to the home page (the first one on the config.xml) after waiting for the specified time.
    • activateeffect: if true a fade in effect will be applied when the app activates.
    • truetransparency: rows will not be backbuffered (saving memory and painting directly over the background) but scrolling will be a lot slower.
    • faketransparency: rows will be backbuffered and the row back color will be replaced by the background. Scrolling will also be a little bit slower.
  • Only used by the standalone app:
    • status: Only used by the stand alone app. Two possible values. 0: normal (will show title bar and button bar of the app). 1: Maximized (will show the app fullscreen).
    • appear: Only used by the stand alone app. Boolean value. Defines if the animation from down to top when the app got focus is activated.

Variables section

For a theme you can define variables that can be changed by the theme user. You can use those variables on the theme on almost any place by using #@VARNAME#. The variables section is wrapped by the "variables" tag that's contained inside the configuration section using the following syntax:

<variables>
	<var name="VARNAME_1" description="VARDESCRIPTION_1" default="DEFAULTVALUE_1" type="VARTYPE_1" />
	<var name="VARNAME_2" description="VARDESCRIPTION_2" default="DEFAULTVALUE_2" type="VARTYPE_2" />
	....
	<var name="VARNAME_N" description="VARDESCRIPTION_N" default="DEFAULTVALUE_N" type="VARTYPE_N" />
<variables>