Theme howto
jSpeed theme files (ie. 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> |
| 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.
| 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> |
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>
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 in km/h of a pointer (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: text
Draws a text block on the screen.
| Option | Definition | Example |
|---|---|---|
| data | The actual textual data. Can be a plain text (ie. "Speed:") or a special field (ie. "{SPEED}"). Special fields are automatically updated to contain their value in unit which is specified in settings. 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. |
<data>{SPEED}</data> |
| format | Special fields trip, total, speed, maxspeed and avgspeed 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 (ie. "somefont.ttf") or a name of a font intalled in system (ie. "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>