Web page updated.
[jspeed] / www / theme-howto.html
index 36257d0..2966ddc 100644 (file)
@@ -4,8 +4,11 @@
 \r
 <head>\r
 \r
-<title>jSpeed - Highly customizable speedometer application</title>\r
-<meta http-equiv="content-type" content="text/html; charset=utf-8" />\r
+<title>jSpeed - Theme howto</title>\r
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<meta name="description" content="Make your own theme for jSpeed by following this easy howto." />
+<meta name="keywords" content="theme,howto,themes,speedometer,jspeed,maemo" />
+<meta name="robots" content="index, follow" />\r
 <script type="text/javascript" src="http://code.jquery.com/jquery-1.4.2.min.js"></script>\r
 <script type="text/javascript" src="fancybox/jquery.mousewheel-3.0.2.pack.js"></script>\r
 <script type="text/javascript" src="fancybox/jquery.fancybox-1.3.1.js"></script>\r
@@ -20,6 +23,7 @@
 <ul id="mainmenu">\r
        <li><a href="http://jspeed.garage.maemo.org/">Info</a></li>\r
        <li><a href="#download">Download</a></li>\r
+       <li><a href="http://jspeed.garage.maemo.org/documentation.html">Documentation</a></li>\r
        <li><a href="http://jspeed.garage.maemo.org/themes.html">Themes</a></li>\r
        <li class="selected"><a href="http://jspeed.garage.maemo.org/theme-howto.html">Theme howto</a></li>\r
 </ul>\r
                                <a href="#tag-pointer">Tag: pointer</a>\r
                        </li>\r
                        <li>\r
+                               <a href="#tag-compass">Tag: compass</a>\r
+                       </li>\r
+                       <li>\r
                                <a href="#tag-text">Tag: text</a>\r
                        </li>\r
                </ul>\r
        </li>\r
 </ul>\r
 \r
-<p>jSpeed theme files (ie. default.jspeed) are just <strong>regular zip-files</strong> renamed to .jspeed. The path for theme files is /home/user/.jspeed/themes.</p>\r
+<p>jSpeed theme files (e.g. default.jspeed) are just <strong>regular zip-files</strong> renamed to .jspeed. The path for theme files is /home/user/.jspeed/themes.</p>\r
 \r
-<p>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:</p>\r
+<p>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.</p> \r
+\r
+<p>A simple theme.xml could look like this:</p>\r
 \r
 <pre class="code">\r
 &lt;theme&gt;\r
        <td>Defines the z-index of an element. An element with bigger zpos gets painted over an element with smaller zpos.</td>\r
        <td><pre>&lt;zpos&gt;5&lt;/xpos&gt;</pre></td>\r
 </tr>\r
+<tr>\r
+       <td>visiblewhen</td>\r
+       <td>Defines when element should be visible. Possible values are <strong>always</strong> (default), <strong>poivisible</strong> (show only when there is a poi (e.g. a speed camera) in view) and <strong>speedexceeded</strong> (show only when speed threshold is exceeded and speed alarm is enabled).</td>\r
+</tr>\r
 <tr class="color">\r
        <td>effect</td>\r
        <td>Defines an effect to used with the element. See <a href="#effects">effects</a> for more details.</td>\r
 \r
 <h4 id="effects">Effects</h4>\r
 \r
-<p>Each element can contain one effect which is used every time the element is painted or updated.</p>\r
+<p>Each element can contain one effect which is used every time the element is painted or updated. <strong>Note: </strong>There are some bugs in effect redrawing in Qt especially on 24-bit png-images.</p>\r
 \r
 <table class="spec">\r
 <tr class="color">\r
        &lt;yoffset&gt;0&lt;/yoffset&gt;\r
        &lt;radius&gt;35&lt;/radius&gt;\r
        &lt;color&gt;#a5efff&lt;/color&gt;\r
-&lt;/effect&gt;\r
-       </pre>\r
+&lt;/effect&gt;</pre>\r
        </td>\r
 </tr>\r
 <tr>\r
 &lt;/effect&gt;</pre>\r
        </td>\r
 </tr>\r
+<tr>\r
+       <td>flicker</td>\r
+       <td>\r
+               <strong>interval: </strong>sets the flickering interval of an element in milliseconds.<br />\r
+       </td>\r
+       <td>\r
+               <pre>&lt;effect name="flicker"&gt;\r
+       &lt;interval&gt;500&lt;/interval&gt;\r
+&lt;/effect&gt;</pre>\r
+       </td>\r
+</tr>\r
 </table>\r
 \r
 <h3 id="tag-rectangle">Tag: rectangle</h3>\r
 </pre>\r
 \r
 \r
+<p>Another example, shows a flickering speed camera warning image when there is a speed camera in view.</p>\r
+\r
+<pre class="code">\r
+&lt;image&gt;\r
+       &lt;src&gt;speedcamera.png&lt;/src&gt;\r
+       &lt;xpos&gt;15&lt;/xpos&gt;\r
+       &lt;ypos&gt;50&lt;/ypos&gt;\r
+       &lt;visiblewhen&gt;poisivible&lt;/visiblewhen&gt;\r
+       &lt;effect name="flicker"&gt;\r
+               &lt;interval&gt;400&lt;/interval&gt;\r
+       &lt;/effect&gt;\r
+&lt;/image&gt;\r
+</pre>\r
+\r
+<p>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 <a href="http://www.irfanview.com/">IrfanView</a> 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:</p>\r
+\r
+<div class="imageinfo">\r
+<img src="img/16M.png" alt="16.7 Million colors" />\r
+<p>16.7 million colors</p>\r
+</div>\r
+\r
+<div class="imageinfo">\r
+<img src="img/256.png" alt="256 colors" />\r
+<p>256 colors</p>\r
+</div>\r
+\r
 \r
 \r
-<h3 id="tag-pointer">Tag: pointer</h3>\r
+<h3 id="tag-pointer" class="clear">Tag: pointer</h3>\r
 \r
 <p>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).</p>\r
 \r
 </tr>\r
 <tr class="color">\r
        <td>zerospeed</td>\r
-       <td>The minimum speed in km/h of a pointer (usually 0).</td>\r
+       <td>The minimum speed of a pointer in km/h (usually 0).</td>\r
        <td><pre>&lt;zerospeed&gt;0&lt;/zerospeed&gt;</pre></td>\r
 </tr>\r
 <tr>\r
 \r
 \r
 \r
+<h3 id="tag-compass">Tag: compass</h3>\r
+\r
+<p>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).</p>\r
+\r
+<table class="spec">\r
+<tr class="color">\r
+       <th class="col1">Option</th>\r
+       <th>Definition</th>\r
+       <th class="col3">Example</th>\r
+</tr>\r
+<tr>\r
+       <td>src</td>\r
+       <td>The image file used to draw the compass.</td>\r
+       <td><pre>&lt;src&gt;pointer.png&lt;/src&gt;</pre></td>\r
+</tr>\r
+<tr class="color">\r
+       <td>xrotationpoint</td>\r
+       <td>The compass rotates around the point defined with xrotationpoint and yrotationpoint. It is usually located inside the compass image.</td>\r
+       <td><pre>&lt;xrotationpoint&gt;200&lt;/xrotationpoint&gt;</pre></td>\r
+</tr>\r
+<tr>\r
+       <td>yrotationpoint</td>\r
+       <td>The compass rotates around the point defined with xrotationpoint and yrotationpoint. It is usually located inside the compass image.</td>\r
+       <td><pre>&lt;yrotationpoint&gt;12&lt;/yrotationpoint&gt;</pre></td>\r
+</tr>\r
+</table>\r
+\r
+<p>Example:</p>\r
+\r
+<pre class="code">\r
+&lt;compass&gt;\r
+       &lt;src&gt;pointer.png&lt;/src&gt;\r
+       &lt;xpos&gt;400&lt;/xpos&gt;\r
+       &lt;ypos&gt;320&lt;/ypos&gt;\r
+       &lt;xrotationpoint&gt;100&lt;/xrotationpoint&gt;\r
+       &lt;yrotationpoint&gt;100&lt;/yrotationpoint&gt;\r
+&lt;/compass&gt;\r
+</pre>\r
+\r
+\r
+\r
 <h3 id="tag-text">Tag: text</h3>\r
 \r
 <p>Draws a text block on the screen.</p>\r
 </tr>\r
 <tr>\r
        <td>data</td>\r
-       <td>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:<br/>\r
+       <td>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:<br/>\r
        <strong>{TRIP}: </strong>Trip value.<br />\r
        <strong>{TOTAL}: </strong>Total travelled kilometers or miles.<br />\r
        <strong>{SPEED}: </strong>Current speed.<br />\r
        <strong>{SPEEDUNIT}: </strong>Speed unit (km/h or mph).<br />\r
        <strong>{TIME}: </strong>Current time, formatted according to timeformat tag.<br />\r
        <strong>{DATE}: </strong>Current date, formatted according to dateformat tag.<br/>\r
+       <strong>{POIDISTANCE}: </strong>Distance to the nearest poi (e.g. speed camera). Empty if there is no poi in view<br />\r
+       <strong>{ANGLE}: </strong>Angle of current direction in degrees. 0 means north.<br />\r
+       <strong>{LATITUDE}: </strong>Current latitude.<br />\r
+       <strong>{LONGITUDE}: </strong>Current longitude.<br />
+       <strong>{ALTITUDE}: </strong>Current altitude (in meters or feet).<br />
+       <strong>{DISTANCEUNIT}: </strong>Unit for altitude and poidistance fields (m or ft).<br />\r
        </td>\r
        <td><pre>&lt;data&gt;{SPEED}&lt;/data&gt;</pre></td>\r
 </tr>\r
 <tr class="color">\r
        <td>format</td>\r
-       <td>Special fields trip, total, speed, maxspeed and avgspeed will be printed according to this format. This field should be in <a href="http://en.wikipedia.org/wiki/Printf">prinf</a> format.</td>\r
+       <td>Special fields trip, total, speed, maxspeed, avgspeed, poidistance, angle, latitude and longitude will be printed according to this format. This field should be in <a href="http://en.wikipedia.org/wiki/Printf">prinf</a> format.</td>\r
        <td><pre>&lt;format&gt;%.1f&lt;/format&gt;</pre></td>\r
 </tr>\r
 <tr>\r
 </tr>\r
 <tr>\r
        <td>font</td>\r
-       <td>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").</td>\r
+       <td>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").</td>\r
        <td><pre>&lt;font&gt;arial.ttf&lt;/font&gt;</pre></td>\r
 </tr>\r
 <tr class="color">\r
@@ -583,4 +679,4 @@ Copyright © 2010 Jesse Hakanen | <a href="&#109;&#97;&#105;&#108;&#116;&#111;&#
 \r
 </body>\r
        \r
-</html>
\ No newline at end of file
+</html>