Theme howto

jSpeed theme files (e.g. default.jspeed) are just regular zip-files renamed to .jspeed. The path for theme files is /home/user/.jspeed/themes.

Each of these zip-files contains at least one file called theme.xml, which contains all the information required to draw the theme. Theme file may also contain image files and fonts required for the theme.

A simple theme.xml could look like this:

<theme>
	<mainscreen orientation="landscape">
		<text>
			<xpos>100</xpos>
			<ypos>100</ypos>
			<data>{SPEED}</data>
			<size>36</size>
		</text>
	</mainscreen>
</theme>

This would print the current speed on screen at position (100, 100) using default font and font size 36. This kind of theme would only work in landscape mode. If one would like the get the theme to also work in portrait mode, there should be another <mainscreen> tag with orientation="portrait" and maybe different positions for speed display.

Mainscreen and detailscreen tags

Each theme.xml must contain at least one <mainscreen> tag like in the example above. jSpeed contains also a detail screen which automatically contains specific speed, time and trip data. The font color and background of this screen can be changed similarly using <detailscreen> tag. Detail screen can also be themed differently in portrait and landscape mode, or the same specification can apply to both portrait and landscape mode by setting attribute orientation="both" on detailscreen tag.

Here's the source code of jSpeed's default theme. The specific explanation of all possible tags is below.

<theme> 
<detailscreen orientation="both" color="#fff">
	<image>
		<xpos>0</xpos>
		<ypos>0</ypos>
		<src>background.png</src>
	</image>
</detailscreen>
<mainscreen orientation="landscape">
	<image>
		<xpos>0</xpos>
		<ypos>0</ypos>
		<src>background.png</src>
	</image>
	<text>
		<data>000</data>
		<font>digital7.ttf</font>
		<size>320</size>
		<xpos>100</xpos>
		<ypos>75</ypos>
		<color>#17202b</color>
		<align>right</align>
		<width>600</width>
	</text>
	<text>
		<data>{SPEEDUNIT}</data>
		<xpos>520</xpos>
		<ypos>402</ypos>
		<font>Nokia Sans Bold</font>
		<size>24</size>
		<color>#fff</color>
		<bold>true</bold>
		<uppercase>true</uppercase>
		<effect name="dropshadow">
			<xoffset>0</xoffset>
			<yoffset>0</yoffset>
			<radius>35</radius>
			<color>#a5efff</color>
		</effect>
	</text>
	<text>
		<data>{SPEED}</data>
		<font>digital7.ttf</font>
		<size>320</size>
		<xpos>100</xpos>
		<ypos>75</ypos>
		<color>#fff</color>
		<align>right</align>
		<width>600</width>
		<format>%.0f</format>
		<effect name="dropshadow">
			<xoffset>0</xoffset>
			<yoffset>0</yoffset>
			<radius>35</radius>
			<color>#a5efff</color>
		</effect>
	</text>
</mainscreen>
<mainscreen orientation="portrait">
	<image>
		<xpos>0</xpos>
		<ypos>0</ypos>
		<src>background.png</src>
	</image>
	<text>
		<data>000</data>
		<font>digital7.ttf</font>
		<size>250</size>
		<xpos>0</xpos>
		<ypos>260</ypos>
		<color>#17202b</color>
		<align>right</align>
		<width>470</width>
	</text>
	<text>
		<data>{SPEEDUNIT}</data>
		<xpos>330</xpos>
		<ypos>522</ypos>
		<font>Nokia Sans Bold</font>
		<size>22</size>
		<color>#fff</color>
		<bold>true</bold>
		<uppercase>true</uppercase>
		<effect name="dropshadow">
			<xoffset>0</xoffset>
			<yoffset>0</yoffset>
			<radius>35</radius>
			<color>#a5efff</color>
		</effect>
	</text>
	<text>
	<data>{SPEED}</data>
		<font>digital7.ttf</font>
		<size>250</size>
		<xpos>0</xpos>
		<ypos>260</ypos>
		<color>#fff</color>
		<align>right</align>
		<width>470</width>
		<format>%.0f</format>
		<effect name="dropshadow">
			<xoffset>0</xoffset>
			<yoffset>0</yoffset>
			<radius>35</radius>
			<color>#a5efff</color>
		</effect>
        </text>
</mainscreen>
</theme>

Tag specification

As you can see on the example above, each detailscreen and mainscreen tags consists of other tags that cause something to be drawn on the screen. Each tag contains specific options to alter its look.

Common options

Common options that work on all tags are listed below.

Option Definition Example
xpos Defines the x-position of an element in pixels 
<xpos>80</xpos>
ypos Defines the y-position of an element in pixels. 
<ypos>40</xpos>
zpos Defines the z-index of an element. An element with bigger zpos gets painted over an element with smaller zpos. 
<zpos>5</xpos>
visiblewhen Defines when element should be visible. Possible values are always (default), poivisible (show only when there is a poi (e.g. a speed camera) in view) and speedexceeded (show only when speed threshold is exceeded and speed alarm is enabled).
effect Defines an effect to used with the element. See effects for more details. 
<effect name="blur">
	<radius>20</radius>
</effect>

Effects

Each element can contain one effect which is used every time the element is painted or updated. Note: There are some bugs in effect redrawing in Qt especially on 24-bit png-images.

Effect name Possible options Example
blur radius: changes the blur radius. Bigger radius will cause the element to be blurred more. 
<effect name="blur">
	<radius>20</radius>
</effect>
dropshadow radius: changes the shadow radius. Bigger radius will cause the element to have bigger and more spread shadow.
color: sets the color of the shadow.
xoffset: shadow's x-distance from the element.
yoffset: shadow's y-distance from the element
 
<effect name="dropshadow">
	<xoffset>0</xoffset>
	<yoffset>0</yoffset>
	<radius>35</radius>
	<color>#a5efff</color>
</effect>
opacity opacity: sets the opacity of an element. Value of 1.0 means totally visible and value of 0.0 totally invisible.
 
<effect name="opacity">
	<opacity>0.8</opacity>
</effect>
flicker interval: sets the flickering interval of an element in milliseconds.
 
<effect name="flicker">
	<interval>500</interval>
</effect>

Tag: rectangle

Rectangle tag draws an rectangle with specified size and color on the screen. Possible options for rectangle are listed below.

Option Definition Example
width Defines the width of the rectangle. 
<width>600</width>
height Defines the height of the rectangle. 
<height>400</height>
color Defines color of the rectangle. Color must be in hexadecimal form. 
<color>#2e94b5</color>

Example:

<rectangle>
	<xpos>100</xpos>
	<ypos>100</ypos>
	<width>300</width>
	<height>200</height>
	<color>#fff</color>
</rectangle>

Tag: image

Draws an image on specific location on the screen. The image file should be placed in the same .jspeed file as theme.xml.

Option Definition Example
width Image is resized to this width. If width is set to 0, it is calculated automatically from height to constrain proportions. If both width and height are set to 0 or are not set at all, the image will be painted in its original size. 
<width>600</width>
height Image is resized to this width. If height is set to 0, it is calculated automatically from width to constrain proportions. 
<height>400</height>

Example:

<image>
	<xpos>100</xpos>
	<ypos>100</ypos>
	<width>300</width>
</image>

Another example, shows a flickering speed camera warning image when there is a speed camera in view.

<image>
	<src>speedcamera.png</src>
	<xpos>15</xpos>
	<ypos>50</ypos>
	<visiblewhen>poisivible</visiblewhen>
	<effect name="flicker">
		<interval>400</interval>
	</effect>
</image>

Images in theme files should be saved in 256 colors because the dithering in Qt/Maemo is not very good. You can do that in example in IrfanView by selecting Image -> Decrease color depth. Just make sure that "Use Floyd-Steinberg dithering" is selected. Although 256 colors may not sound much, it is enough for most of the images. Here's the difference between gradient at 16.7 million colors and 256 colors on the N900's screen:

16.7 Million colors

16.7 million colors

256 colors

256 colors

Tag: pointer

Draws a pointer which moves according to current speed. Can be used to draw analog speedometers. The image file should be placed in the same .jspeed file as theme.xml. The xpos and ypos of a pointer are specified as the rotation point of the pointer on screen (usually somewhere in the middle of the screen).

Option Definition Example
src The image file used to draw the pointer. 
<src>pointer.png</src>
zerospeed The minimum speed of a pointer in km/h (usually 0). 
<zerospeed>0</zerospeed>
fullspeed The maximum speed of a pointer in km/h. (usually the maximum speed value in analog speedometer). 
<fullspeed>220</fullspeed>
zeroangle When speed is at zerospeed or lower, the pointer is rotated this much in degress from its original state. 
<zeroangle>-30</zeroangle>
fullangle When speed is at fullspeed or higher, the pointer is rotated this much in degress from its original state. 
<fullangle>210</fullangle>
xrotationpoint The pointer rotates around the point defined with xrotationpoint and yrotationpoint. It is usually located inside the pointer image. 
<xrotationpoint>200</xrotationpoint>
yrotationpoint The pointer rotates around the point defined with xrotationpoint and yrotationpoint. It is usually located inside the pointer image. 
<yrotationpoint>12</yrotationpoint>

Example:

<pointer>
	<src>pointer.png</src>
	<zeroangle>-20</zeroangle>
	<fullangle>210</fullangle>
	<zerospeed>0</zerospeed>
	<fullspeed>230</fullspeed>
	<xpos>400</xpos>
	<ypos>355</ypos>
	<xrotationpoint>278</xrotationpoint>
	<yrotationpoint>14</yrotationpoint>
</pointer>

Tag: compass

Draws a compass which is always rotated so that the top of the compass image points to north. The xpos and ypos of a pointer are specified as the rotation point of the compass on screen (usually somewhere in the middle of the screen).

Option Definition Example
src The image file used to draw the compass. 
<src>pointer.png</src>
xrotationpoint The compass rotates around the point defined with xrotationpoint and yrotationpoint. It is usually located inside the compass image. 
<xrotationpoint>200</xrotationpoint>
yrotationpoint The compass rotates around the point defined with xrotationpoint and yrotationpoint. It is usually located inside the compass image. 
<yrotationpoint>12</yrotationpoint>

Example:

<compass>
	<src>pointer.png</src>
	<xpos>400</xpos>
	<ypos>320</ypos>
	<xrotationpoint>100</xrotationpoint>
	<yrotationpoint>100</yrotationpoint>
</compass>

Tag: text

Draws a text block on the screen.

Option Definition Example
data The actual textual data. Can be a plain text (e.g. "Speed:") or a special field (e.g. "{SPEED}"). Special fields are automatically updated to contain their value in unit which is specified in settings. Special fields can also be combined (e.g. "{SPEED} {SPEEDUNIT}"). Possible special fiels are listed below:
{TRIP}: Trip value.
{TOTAL}: Total travelled kilometers or miles.
{SPEED}: Current speed.
{MAXSPEED}: Maximum speed.
{AVGSPEED}: Average speed.
{UNIT}: Distance unit (km or mi).
{SPEEDUNIT}: Speed unit (km/h or mph).
{TIME}: Current time, formatted according to timeformat tag.
{DATE}: Current date, formatted according to dateformat tag.
{POIDISTANCE}: Distance to the nearest poi (e.g. speed camera). Empty if there is no poi in view
{ANGLE}: Angle of current direction in degrees. 0 means north.
{LATITUDE}: Current latitude.
{LONGITUDE}: Current longitude.
{ALTITUDE}: Current altitude (in meters or feet).
{DISTANCEUNIT}: Unit for altitude and poidistance fields (m or ft).
 
<data>{SPEED}</data>
format Special fields trip, total, speed, maxspeed, avgspeed, poidistance, angle, latitude and longitude will be printed according to this format. This field should be in prinf format. 
<format>%.1f</format>
width The width of the text block. 
<width>200</width>
align Text align inside the text block (left, center or right). 
<align>right</align>
color Text color in hexadecimal form. 
<color>#000000</color>
size Text size in pixels. 
<size>20</size>
font Text font. Can be a font file inside the theme file (e.g. "somefont.ttf") or a name of a font intalled in system (e.g. "Tahoma"). 
<font>arial.ttf</font>
bold Sets bold text. 
<bold>true</bold>
italic Sets italic text. 
<italic>true</italic>
uppercase Prints all letters in UPPERCASE. 
<uppercase>true</uppercase>
letterspacing Sets the spacing between letters. 
<letterspacing>150</letterspacing>
timeformat Special field time will be printed according to this format. See Qt QTime manual for possible expressions. 
<timeformat>hh:mm</timeformat>
dateformat Special field date will be printed according to this format. See Qt QDate manual for possible expressions. 
<dateformat>dd.MM.yyyy</dateformat>

Example:

<text>
	<data>{SPEED}</data>
	<font>digital7.ttf</font>
	<size>320</size>
	<xpos>100</xpos>
	<ypos>75</ypos>
	<color>#fff</color>
	<align>right</align>
	<width>600</width>
	<format>%.0f</format>
	<effect name="dropshadow">
		<xoffset>0</xoffset>
		<yoffset>0</yoffset>
		<radius>35</radius>
		<color>#a5efff</color>
	</effect>
</text>

Download

jSpeed can be downloaded from Maemo extras-devel repository.

License

jSpeed is licensed under the terms of the GNU General Public License.

Links