blob: 2ecd98efc146cfb0e5378e8cba3afcc81965d19d [file] [log] [blame]
Dominik Riebeling36a31332006-04-09 21:22:42 +00001% $Id$ %
Alex Parker40782d52010-05-13 08:13:31 +00002\chapter{\label{ref:wps_tags}Theme Tags}
3Themeing is discussed in detail in section \reference{ref:ConfiguringtheWPS},
4what follows is a list of the available tags.
5
Alex Parker15258e02010-09-17 19:13:20 +00006\note{The ``bar-type tags'' (such as \%pb, \%pv, \%bl etc.) can be further
7 themed -- see \reference{ref:bar_tags}.}
8
Dominik Riebeling36a31332006-04-09 21:22:42 +00009\section{Status Bar}
Michael Chicoine65dc4f22010-03-23 12:02:20 +000010\begin{tagmap}
Alex Parker0c1f3e62010-03-21 10:20:19 +000011 \config{\%we} & Display Status Bar\\
12 \config{\%wd} & Hide Status Bar\\
13 \config{\%wi} & Display the inbuilt Status Bar in the current viewport\\
Dominik Riebeling36a31332006-04-09 21:22:42 +000014\end{tagmap}
15These tags override the player setting for the display of the status bar.
Alexander Levin0a241402009-03-23 21:46:49 +000016They must be noted on their own line (which will not be shown in the WPS).
Martin Arver94c12892006-03-23 14:11:52 +000017
Marianne Arnoldfa632112010-10-29 17:52:20 +000018\section{Hardware Capabilities}
19\begin{tagmap}
20 \config{\%cc} & Check for presence of a real time clock, returns ``c''
21 when used unconditionally\\
22 \config{\%tp} & Does this target have a radio?\\
23 \config{\%Tp} & Indicates that the target has a touchscreen\\
24\end{tagmap}
25With the above tags it is possible to find out about the presence of certain
26hardware and make the theme adapt to it. This can be very useful for designing
27a theme that works on multiple targets with differing hardware capabilities, e.g.
28targets that do and do not have a clock. When used conditionally, the ``true''
29branch is completely ignored if it does not apply.
30
31Example:
32\config{\%?cc<\%cH:\%cM|No clock detected>}
33
34
Alexander Levin0a241402009-03-23 21:46:49 +000035\section{Information from the track tags}
Michael Chicoine65dc4f22010-03-23 12:02:20 +000036 \begin{tagmap}
Alexander Levin0a241402009-03-23 21:46:49 +000037 \config{\%ia} & Artist\\
38 \config{\%ic} & Composer\\
Tomer Shalev13ef6772010-01-08 14:03:43 +000039 \config{\%iA} & Album Artist\\
Alexander Levin0a241402009-03-23 21:46:49 +000040 \config{\%id} & Album Name\\
Tomer Shalev13ef6772010-01-08 14:03:43 +000041 \config{\%iG} & Grouping\\
Alexander Levin0a241402009-03-23 21:46:49 +000042 \config{\%ig} & Genre Name\\
43 \config{\%in} & Track Number\\
44 \config{\%it} & Track Title\\
Tomer Shalev13ef6772010-01-08 14:03:43 +000045 \config{\%iC} & Comment\\
Alexander Levin0a241402009-03-23 21:46:49 +000046 \config{\%iv} & ID3 version (1.0, 1.1, 2.2, 2.3, 2.4, or empty if not an ID3 tag)\\
47 \config{\%iy} & Year\\
Tomer Shalev13ef6772010-01-08 14:03:43 +000048 \config{\%ik} & Disc Number\\
Dominik Riebeling36a31332006-04-09 21:22:42 +000049 \end{tagmap}
50Remember that this information is not always available, so use the
51conditionals to show alternate information in preference to assuming.
Martin Arver94c12892006-03-23 14:11:52 +000052
Alexander Levin0a241402009-03-23 21:46:49 +000053These tags, when written with a capital ``I'' (e.g. \config{\%Ia} or \config{\%Ic}),
Alex Parkerab563da2009-09-20 16:48:45 +000054show the information for the next song to be played.
55
56\nopt{lcd_charcell}{
57 \section{Viewports}
Michael Chicoine65dc4f22010-03-23 12:02:20 +000058 \begin{tagmap}
59 \nopt{lcd_non-mono}{%
Alexander Levin67f25a42010-07-02 18:54:09 +000060 \config{\%V(x,y,[width],\tabnlindent[height],[font])}
Alexander Levin6d4637c2010-03-27 15:52:27 +000061 & See section \ref{ref:Viewports}\\}
Alex Parkerab563da2009-09-20 16:48:45 +000062
63 \nopt{lcd_color}{\opt{lcd_non-mono}{%
Alexander Levin67f25a42010-07-02 18:54:09 +000064 \config{\%V(x,y,[width],\tabnlindent[height],[font])}\newline
65 \config{\%Vf([fgshade])}\newline
66 \config{\%Vb([bgshade])}
Alexander Levin6d4637c2010-03-27 15:52:27 +000067 & See section \ref{ref:Viewports}\\}}
Alex Parkerab563da2009-09-20 16:48:45 +000068
69 \opt{lcd_color}{%
Alexander Levin67f25a42010-07-02 18:54:09 +000070 \config{\%V(x,y,[width],\tabnlindent[height],[font])}\newline
71 \config{\%Vf([fgcolour])}\newline
Alex Parker77a78ee2011-08-19 11:43:51 +000072 \config{\%Vb([bgcolour])}\newline
73 \config{\%Vg(start,end \tabnlindent[,text])}
Alexander Levin6d4637c2010-03-27 15:52:27 +000074 & See section \ref{ref:Viewports}\\}
Alex Parker77a78ee2011-08-19 11:43:51 +000075
76 \opt{lcd_non-mono}{%
77 \config{\%Vs(mode[,param])}
78 & See section \ref{ref:Viewports}\\}
79
Alex Parkerecb21112010-08-02 21:21:33 +000080 \config{\%Vl('identifier',\newline\dots)} & Preloads a viewport for later
81 display. `identifier' is a single lowercase letter (a-z) and the `\dots'
82 parameters use the same logic as the \%V tag explained above.\\
Alex Parkerab563da2009-09-20 16:48:45 +000083
Alex Parker64d4ddf2010-06-20 12:58:41 +000084 \config{\%Vd('identifier')} & Display the `identifier' viewport. E.g.
Alexander Levin15d0ac02010-07-02 19:55:47 +000085 \config{\%?C<\%Vd(a)|\%Vd(b)>}
Alexander Levinac00d262010-03-26 22:12:39 +000086 will show viewport `a' if album art is found, and `b' if it isn't.\\
Alex Parker6d549df2010-05-13 08:13:37 +000087
Alex Parker49f2fce2010-06-20 16:27:41 +000088 \config{\%Vi('label',\dots)} &
Alexander Levin9f95a0b2010-05-13 08:41:01 +000089 Declare a Custom UI Viewport. The `\dots' parameters use the same logic as
Alex Parker6d549df2010-05-13 08:13:37 +000090 the \config{\%V} tag explained above. See section \ref{ref:Viewports}.\\
91
Alex Parker49f2fce2010-06-20 16:27:41 +000092 \config{\%VI('label')} & Set the Info Viewport to use the viewport called
Alex Parker6d549df2010-05-13 08:13:37 +000093 label, as declared with the previous tag.\\
Jonathan Gordon2c71aa92012-02-28 22:26:32 +110094
Alexander Levin5db58fc2012-03-02 19:58:45 +010095 \config{\%VB} & Draw this viewport on the backdrop layer.\\
Alex Parkerab563da2009-09-20 16:48:45 +000096 \end{tagmap}
Alex Parker1b0c77f2010-06-20 12:58:09 +000097
98 \section{Additional Fonts}
99 \begin{tagmap}
Alex Parker49f2fce2010-06-20 16:27:41 +0000100 \config{\%Fl('id',filename)} & See section \ref{ref:multifont}.\\
Alex Parker1b0c77f2010-06-20 12:58:09 +0000101 \end{tagmap}
102
Jonathan Gordon014a08c2012-03-15 22:50:17 +1100103 \section{Misc Coloring Tags}
104 \begin{tagmap}
105 \config{\%dr(x,y,width,height,[color1,color2])} & Color a rectangle. \\
106 \end{tagmap}
107 width and height can be - to fill the viewport. If no color is
108 specified the viewports foreground color will be used. If two
109 colors are specified it will do a gradient fill.
Alex Parkerab563da2009-09-20 16:48:45 +0000110}
Alexander Levin0a241402009-03-23 21:46:49 +0000111
Dominik Riebeling36a31332006-04-09 21:22:42 +0000112\section{Power Related Information}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000113 \begin{tagmap}
Alexander Levin12427102010-07-02 19:32:48 +0000114 \config{\%bl} & Numeric battery level in percents.
115 Can also be used in a conditional:
Alexander Levin15d0ac02010-07-02 19:55:47 +0000116 \config{\%?bl<-1|0|1|2|\ldots|N>},
Alexander Levin0a241402009-03-23 21:46:49 +0000117 where the value $-1$ is used when the battery level isn't
Magnus Holmgren0b921582010-08-12 09:50:29 +0000118 known (it usually is). The value $N$ is only used when the
119 battery level is exactly 100 percent.
Alexander Levin12427102010-07-02 19:32:48 +0000120 An image can also be used, the proportion of the image
Magnus Holmgren0b921582010-08-12 09:50:29 +0000121 shown corresponds to the battery level:
Alex Parker64d4ddf2010-06-20 12:58:41 +0000122 \config{\%bl(x,y,[width],[height],image.bmp)}\\
Alexander Levin0a241402009-03-23 21:46:49 +0000123 \config{\%bv} & The battery level in volts\\
124 \config{\%bt} & Estimated battery time left\\
125 \config{\%bp} & ``p'' if the charger is connected (only on targets
126 that can charge batteries)\\
127 \config{\%bc} & ``c'' if the unit is currently charging the battery (only on
128 targets that have software charge control or monitoring)\\
129 \config{\%bs} & Remaining time of the sleep timer (if it is set)\\
Dominik Riebeling36a31332006-04-09 21:22:42 +0000130 \end{tagmap}
Martin Arver94c12892006-03-23 14:11:52 +0000131
Alexander Levin0a241402009-03-23 21:46:49 +0000132\section{Information about the file}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000133 \begin{tagmap}
Martin Arverf21f9142006-05-08 21:32:44 +0000134 \config{\%fb} & File Bitrate (in kbps)\\
Alexander Levin15d0ac02010-07-02 19:55:47 +0000135 \config{\%fc} & File Codec (e.g. ``MP3'' or ``FLAC'').
136 This tag can also be used in a conditional tag:
137 \config{\%?fc<mp1|mp2|mp3|aiff|wav|ogg|\newline
Andree Buschmanna884ec22011-11-28 18:45:33 +0000138 flac|mpcsv7|a52|wavpack|alac|aac|shn|sid|adx|nsf|\newline
139 speex|spc|ape|wma|wmpapro|mod|sap|realaudiocook|\newline
140 realaudioaac|realaudioac3|realaudioatrac3|cmc|\newline
141 cm3|cmr|cms|dmc|dlt|mpt|mpd|rmt|tmc|tm8|tm2|\newline
142 omaatrac3|smaf|au|vox|wave64|tta|wmavoice|mpcsv8|\newline
143 aache|ay|gbs|hes|sgc|vgm|kss|unknown>}.
144 The codec order is as shown above.\\
Martin Arverf21f9142006-05-08 21:32:44 +0000145 \config{\%ff} & File Frequency (in Hz)\\
Andree Buschmann53cf63f2010-04-14 19:44:07 +0000146 \config{\%fk} & File Frequency (in kHz)\\
Martin Arverf21f9142006-05-08 21:32:44 +0000147 \config{\%fm} & File Name\\
148 \config{\%fn} & File Name (without extension)\\
149 \config{\%fp} & File Path\\
Alexander Levin0a241402009-03-23 21:46:49 +0000150 \config{\%fs} & File Size (in Kilobytes)\\
151 \config{\%fv} & ``(avg)'' if variable bit rate or empty string if constant bit rate\\
Alexander Levina43fbbb2010-07-01 18:55:43 +0000152 \config{\%d(N)} & N-th segment from the end of the file's directory
153 (N can be 1, 2, 3, \dots)\\
Dominik Riebeling36a31332006-04-09 21:22:42 +0000154 \end{tagmap}
Alexander Levina43fbbb2010-07-01 18:55:43 +0000155Example for the \config{\%d(N)} commands: If the file is
Alex Parker64d4ddf2010-06-20 12:58:41 +0000156``/Rock/Kent/Isola/11 - 747.mp3'', \config{\%d(1)} is ``Isola'',
157\config{\%d(2)} is ``Kent'' and \config{\%d(3)} is ``Rock''.
Alexander Levin0a241402009-03-23 21:46:49 +0000158
Alex Parker64d4ddf2010-06-20 12:58:41 +0000159These tags, when written with the first letter capitalized (e.g. \config{\%Fn}
160or \config{\%D(2)}), produce the information for the next file to be played.
Martin Arver94c12892006-03-23 14:11:52 +0000161
Dominik Riebeling36a31332006-04-09 21:22:42 +0000162\section{Playlist/Song Info}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000163 \begin{tagmap}
Alexander Levin12427102010-07-02 19:32:48 +0000164 \config{\%pb} & Progress Bar.
Martin Arver94c12892006-03-23 14:11:52 +0000165 \opt{player}{
Alexander Levin12427102010-07-02 19:32:48 +0000166 This will display a one character ``cup''
Martin Arverec60a052006-03-29 18:40:42 +0000167 that empties as the time progresses.}
Nils Wallménius12eb0582008-03-23 22:07:09 +0000168 \opt{lcd_bitmap}{
Alexander Levin12427102010-07-02 19:32:48 +0000169 This will replace the entire line with a progress bar.
170 You can set the position, width and height of the progressbar
171 (in pixels) and load a custom image for it:
Alex Parker64d4ddf2010-06-20 12:58:41 +0000172 \config{\%pb(x,y,[width],[height],image.bmp)}} \\
Dominik Riebelingeef96942007-04-07 22:48:11 +0000173 \opt{player}{%
Martin Arverf21f9142006-05-08 21:32:44 +0000174 \config{\%pf} & Full-line progress bar \& time display\\
Dominik Riebelingeef96942007-04-07 22:48:11 +0000175 }%
Alexander Levind8f5f512010-07-02 18:57:57 +0000176 \config{\%px} & Percentage played in song\\
177 \config{\%pc} & Current time in song\\
178 \config{\%pe} & Total number of playlist entries\\
Dominik Riebelingeef96942007-04-07 22:48:11 +0000179 \nopt{player}{%
180 \config{\%pm} & Peak Meter. The entire line is used as %
181 volume peak meter.\\%
Alex Parkerc16deb32011-01-13 18:09:46 +0000182 \config{\%pL} & Peak meter for the left channel. Can be used as a value, %
183 a conditional tag or a bar tag.\\
184 \config{\%pR} & Peak meter for the right channel. Can be used as a value, %
185 a conditional tag or a bar tag.\\
Dominik Riebelingeef96942007-04-07 22:48:11 +0000186 }%
Alexander Levind8f5f512010-07-02 18:57:57 +0000187 \config{\%pn} & Playlist name (without path or extension)\\
188 \config{\%pp} & Playlist position\\
189 \config{\%pr} & Remaining time in song\\
Alexander Levin0a241402009-03-23 21:46:49 +0000190 \config{\%ps} & ``s'' if shuffle mode is enabled\\
Alexander Levind8f5f512010-07-02 18:57:57 +0000191 \config{\%pt} & Total track time\\
Alexander Levin12427102010-07-02 19:32:48 +0000192 \config{\%pv} & Current volume (in dB). Can also be used in a conditional:
Alex Mayer659e5992012-12-04 01:10:59 -0500193 \config{\%?pv<Mute|\ldots|0 dB|Above 0 dB>}\newline
194 Mute is 0\% volume, \ldots is the values between Mute and max, 0 dB is max volume, and Above 0 dB is amplified volume
Alexander Levin12427102010-07-02 19:32:48 +0000195 \opt{lcd_bitmap}{This can also be used like \%pb to provide a continuous scale:
Alex Parker64d4ddf2010-06-20 12:58:41 +0000196 \config{\%pv(x,y,[width],[height],image.bmp)}} \\
Alex Parkerbbb2dd52010-03-21 10:20:09 +0000197 \config{\%pS} & Track is starting. An optional number gives how many seconds
198 the tag remains true for after the start of the track. The default is
Alexander Levin12427102010-07-02 19:32:48 +0000199 10 seconds if no number is specified.
Alexander Levin11e792b2010-09-24 19:07:42 +0000200 \config{\%?pS(7)<in the first 7 seconds of track|in
Alexander Levin15d0ac02010-07-02 19:55:47 +0000201 the rest of the track>}\\
Alex Parkerbbb2dd52010-03-21 10:20:09 +0000202 \config{\%pE} & Track is ending. An optional number gives how many seconds
Alex Parker7e84cca2010-03-22 20:41:14 +0000203 before the end of the track the tag becomes true. The default is
Alexander Levin12427102010-07-02 19:32:48 +0000204 10 seconds if no number is specified.
Alexander Levin11e792b2010-09-24 19:07:42 +0000205 \config{\%?pE(7)<in the last 7 seconds of track|in
Alexander Levin15d0ac02010-07-02 19:55:47 +0000206 the rest of the track>}\\
Alexander Levin12427102010-07-02 19:32:48 +0000207 \config{\%Sp} & Current playback pitch\\
Dominik Riebeling36a31332006-04-09 21:22:42 +0000208 \end{tagmap}
Alex Parkerd7cb3b12010-07-31 12:47:12 +0000209
210\section{Playlist Viewer}
211 \begin{tagmap}
Jonathan Gordond23d7a12010-08-14 15:27:46 +0000212 \config{\%Vp(start,code to render)} & Display the playlist viewer in
Alex Parkerd7cb3b12010-07-31 12:47:12 +0000213 the current viewport.\\
214 \end{tagmap}
215
216 \begin{itemize}
217 \item `start' is the offset relative to the currently playing track for the
218 playlist to display from (0 the current track, 1 is the next track, etc.).
Jonathan Gordond23d7a12010-08-14 15:27:46 +0000219 \item `code to render' is a line of skin code which will be displayed for
Alex Parker964a5e62011-08-09 14:39:32 +0000220 each line in the viewer. All text tags are supported (including conditionals
Jonathan Gordond23d7a12010-08-14 15:27:46 +0000221 and sublines)
Alex Parkerd7cb3b12010-07-31 12:47:12 +0000222 \end{itemize}
223
224 The entire viewport will be used, so don't expect other tags in the same
225 viewport to work well. Supported tags are \%pp, all tags starting with \%i,
226 most tags starting with \%f, \%pt and \%s.\\
227
228 Example: \config{\%Vp(1,\%pp - \%it,\%pp - \%fn)} -- Display the playlist
229 position, then either the track title (from the tags) or
230 the filename. The viewer will display as many tracks as will fit in the
231 viewport.
Martin Arver94c12892006-03-23 14:11:52 +0000232
Dominik Riebeling36a31332006-04-09 21:22:42 +0000233\section{Runtime Database}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000234 \begin{tagmap}
Martin Arverf21f9142006-05-08 21:32:44 +0000235 \config{\%rp} & Song playcount\\
Alexander Levin0a241402009-03-23 21:46:49 +0000236 \config{\%rr} & Song rating (0-10). This tag can also be used in a conditional tag: %
Alexander Levin15d0ac02010-07-02 19:55:47 +0000237 \config{\%?rr<0|1|2|3|4|5|6|7|8|9|10>}\\
Tomer Shalev13ef6772010-01-08 14:03:43 +0000238 \config{\%ra} & Autoscore for the song\\
Dominik Riebeling36a31332006-04-09 21:22:42 +0000239 \end{tagmap}
Martin Arver94c12892006-03-23 14:11:52 +0000240
Nils Wallménius12eb0582008-03-23 22:07:09 +0000241\opt{swcodec}{
Dominik Riebeling9eaa5682006-04-10 17:35:49 +0000242\section{Sound (DSP) settings}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000243 \begin{tagmap}
Alexander Levin0a241402009-03-23 21:46:49 +0000244 \config{\%Sp} & Current playback pitch \\
Nils Wallménius12eb0582008-03-23 22:07:09 +0000245 \opt{swcodec}{
Jeffrey Goode0212de42009-11-11 17:38:00 +0000246 \config{\%xf} & Crossfade setting, in the order: Off, Auto Skip, Man Skip,
247 Shuffle, Shuffle and Man Skip, Always\\
Andree Buschmann1248e9c2010-04-14 20:38:21 +0000248 \config{\%rg} & ReplayGain value in use (x.y~dB). If used as a conditional,
Alexander Levin15d0ac02010-07-02 19:55:47 +0000249 Replaygain type in use: \config{\%?rg<Off|Track%
250 |Album|TrackShuffle|AlbumShuffle%
251 |No tag>}\\
Dominik Riebelingda1e28c2006-08-03 18:32:41 +0000252 }
Dominik Riebeling9eaa5682006-04-10 17:35:49 +0000253 \end{tagmap}
254}
Nils Wallméniusaf689872009-08-24 15:19:14 +0000255
Marianne Arnoldb013fb72010-07-01 21:02:12 +0000256\section{Hold}
257 \begin{tagmap}
258 \config{\%mh} & ``h'' if the main unit keys are locked\\
259 \opt{remote_button_hold}{%
260 \config{\%mr} & ``r'' if the remote keys are locked\\
261 }
262 \end{tagmap}
Martin Arver94c12892006-03-23 14:11:52 +0000263
Dominik Riebeling36a31332006-04-09 21:22:42 +0000264\section{Virtual LED}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000265 \begin{tagmap}
Marianne Arnolda352c622007-05-19 19:03:39 +0000266 \config{\%lh} & ``h'' if the \disk\ is accessed\\
Dominik Riebeling36a31332006-04-09 21:22:42 +0000267 \end{tagmap}
Martin Arver94c12892006-03-23 14:11:52 +0000268
Dominik Riebeling36a31332006-04-09 21:22:42 +0000269\section{Repeat Mode}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000270 \begin{tagmap}
Marianne Arnoldc9532a22010-04-04 13:58:52 +0000271 \config{\%mm} & Repeat mode, 0-4, in the order: Off, All, One, Shuffle, A-B\\
Dominik Riebeling36a31332006-04-09 21:22:42 +0000272 \end{tagmap}
Alex Parkerd7cb3b12010-07-31 12:47:12 +0000273Example: \config{\%?mm<Off|All|One|Shuffle|A-B>}
Martin Arver94c12892006-03-23 14:11:52 +0000274
Alexander Levin0bfef1c2010-02-26 19:57:51 +0000275\section{Playback Mode}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000276 \begin{tagmap}
Martin Arverf21f9142006-05-08 21:32:44 +0000277 \config{\%mp} & Play status, 0-4, in the order: Stop, Play, Pause,
Frank Gevaerts629bf3e2010-04-11 11:44:18 +0000278 Fast Forward, Rewind, Recording, Recording paused, FM Radio playing,
279 FM Radio muted\\
Dominik Riebeling36a31332006-04-09 21:22:42 +0000280 \end{tagmap}
Alex Parkerd7cb3b12010-07-31 12:47:12 +0000281Example: \config{\%?mp<Stop|Play|Pause|Ffwd|Rew|Rec|Rec pause|FM|FM pause>}
Martin Arver94c12892006-03-23 14:11:52 +0000282
Alexander Levin5ff8a5a2010-02-26 19:53:06 +0000283\section{Current Screen}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000284 \begin{tagmap}
Osborne Jacobs67b4b2a2012-03-13 02:28:12 -0400285 \config{\%cs} & The current screen, 1-20, in the order shown below\\
Alexander Levin5ff8a5a2010-02-26 19:53:06 +0000286 \end{tagmap}
Alexander Levin5ff8a5a2010-02-26 19:53:06 +0000287
Alex Parker60136142011-08-09 13:53:26 +0000288\begin{table}
289 \begin{rbtabular}{.75\textwidth}{lX}%
290 {\textbf{Number} & \textbf{Screen}}{}{}
291 1 & Menus \\
292 2 & WPS \\
293 3 & Recording screen \\
294 4 & FM Radio screen \\
295 5 & Current Playlist screen \\
296 6 & Settings menus \\
297 7 & File browser \\
298 8 & Database browser \\
299 9 & Plugin browser \\
300 10 & Quickscreen \\
301 11 & Pitchscreen \\
302 12 & Setting chooser \\
303 13 & Playlist Catalogue Viewer \\
304 14 & Plugin \\
305 15 & Context menu \\
306 16 & System Info screen \\
307 17 & Time and Date Screen \\
308 18 & Bookmark browser \\
Jonathan Gordon0402a5c2011-12-19 08:54:01 +0000309 19 & Shortcuts menu \\
Osborne Jacobs67b4b2a2012-03-13 02:28:12 -0400310 20 & Track Info screen \\
Alex Parker60136142011-08-09 13:53:26 +0000311 \end{rbtabular}
312\end{table}
313
314The tag can also be used as the switch in a conditional tag. For players without
315certain capabilities (e.g. no FM radio) some values will never be returned.
316
317Examples:
318
319\config{You are in the \%?cs<Main menu|WPS|Recording screen|FM Radio screen>}
320
321\config{\%?if(\%cs, =, 2)<This is the WPS>}
Alexander Levin5ff8a5a2010-02-26 19:53:06 +0000322
Alex Parker165709b2010-03-21 10:20:24 +0000323\section{List Title (\fname{.sbs} only)}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000324 \begin{tagmap}
Alex Parker165709b2010-03-21 10:20:24 +0000325 \config{\%Lt} & Title text. Should be used in a conditional so that non-list
326 screens don't show a title when they shouldn't\\
327 \config{\%Li} & Title icon. This uses the same order as custom icons (see
328 \wikilink{CustomIcons} in the wiki) except that here \config{0} is ``no
329 icon''\\
330 \end{tagmap}
331
332 This tag can be used to give custom formatting to list titles.
333 Define a viewport with the font and formatting desired, and then use
Alexander Levin15d0ac02010-07-02 19:55:47 +0000334 \config{\%?Lt<\%Lt>} to display the title within the
Alex Parker165709b2010-03-21 10:20:24 +0000335 viewport. If \config{\%Lt} is present anywhere in the \fname{.sbs}, then the
336 \config{\%Vi} viewport will not show the title.
337
Dominik Riebeling71c1e2a2008-10-12 10:48:06 +0000338\section{Changing Volume}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000339 \begin{tagmap}
Alex Parker64d4ddf2010-06-20 12:58:41 +0000340 \config{\%mv(t)} & ``v'' if the volume is being changed\\
Dominik Riebeling71c1e2a2008-10-12 10:48:06 +0000341 \end{tagmap}
Dominik Riebeling71c1e2a2008-10-12 10:48:06 +0000342
343The tag produces the letter ``v'' while the volume is being changed and some
344amount of time after that, i.e. after the volume button has been released. The
Alexander Levin0a241402009-03-23 21:46:49 +0000345optional parameter \config{t} specifies that amount of time, in seconds. If it
346is not specified, 1 second is assumed.
Dominik Riebeling71c1e2a2008-10-12 10:48:06 +0000347
348The tag can be used as the switch in a conditional tag to display different things
349depending on whether the volume is being changed. It can produce neat effects
350when used with conditional viewports.
351
Alexander Levin15d0ac02010-07-02 19:55:47 +0000352Example: \config{\%?mv(2.5)<Volume changing|\%pv>}
Dominik Riebeling71c1e2a2008-10-12 10:48:06 +0000353
354The example above will display the text ``Volume changing'' if the volume is
Andree Buschmann1248e9c2010-04-14 20:38:21 +0000355being changed and 2.5 seconds after the volume button has been released. After
Dominik Riebeling71c1e2a2008-10-12 10:48:06 +0000356that, it will display the volume value.
357
Antoine Cellerier8289b962008-12-07 16:20:35 +0000358\section{Settings}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000359 \begin{tagmap}
Alexander Levin67f25a42010-07-02 18:54:09 +0000360 \config{\%St(<setting\tabnlindent{}name>)} & The value of the Rockbox
Alexander Levin0a241402009-03-23 21:46:49 +0000361 setting with the specified name. See \reference{ref:config_file_options}
362 for the list of the available settings.\\
Jonathan Gordon65f9df32012-07-05 22:44:13 +1000363 \config{\%St(...)} & Draw a bar using from the setting.
364 See \reference{ref:bar_tags} for details.\\
Antoine Cellerier8289b962008-12-07 16:20:35 +0000365 \end{tagmap}
Alexander Levin0a241402009-03-23 21:46:49 +0000366
367Examples:
368\begin{enumerate}
Alex Parker64d4ddf2010-06-20 12:58:41 +0000369\item As a simple tag: \config{\%St(skip length)}
Alexander Levin15d0ac02010-07-02 19:55:47 +0000370\item As a conditional: \config{\%?St(eq enabled)<Eq is enabled|Eq is disabled>}
Alexander Levin0a241402009-03-23 21:46:49 +0000371\end{enumerate}
372
Antoine Cellerier8289b962008-12-07 16:20:35 +0000373
Jonas Häggqvist410cbd12009-02-20 18:37:57 +0000374\opt{lcd_bitmap}{
Alex Parkerab563da2009-09-20 16:48:45 +0000375\section{\label{ref:wps_images}Images}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000376 \begin{tagmap}
Nils Wallméniusda555882006-11-13 15:14:28 +0000377 \nopt{archos}{%
Alex Parker64d4ddf2010-06-20 12:58:41 +0000378 \config{\%X(filename.bmp)}
Dominik Riebeling2ce440d2008-03-26 19:35:39 +0000379 & Load and set a backdrop image for the WPS.
Dominik Riebeling36a31332006-04-09 21:22:42 +0000380 This image must be exactly the same size as your LCD.\\
Nils Wallméniusda555882006-11-13 15:14:28 +0000381 }%
Jonathan Gordon1c1e1c02012-02-29 00:07:16 +1100382 \config{\%x(n,filename[,x,y])}
Alexander Levin12427102010-07-02 19:32:48 +0000383 & Load and display an image\newline
Jonathan Gordon406a3632012-12-09 17:15:17 +1100384 \config{n}: image ID for later referencing in \config{\%xd}\newline
Alexander Levin12427102010-07-02 19:32:48 +0000385 \config{filename}: file name relative to \fname{/.rockbox/} and including ``.bmp''\newline
Jonathan Gordon1c1e1c02012-02-29 00:07:16 +1100386 \config{x}: x coordinate (defaults to 0 if both x and y are not specified)\newline
387 \config{y}: y coordinate. (defaults to 0 if both x and y are not specified)\\
388 \config{\%xl(n,filename,[x,y],\tabnlindent[nimages])}
Alexander Levin12427102010-07-02 19:32:48 +0000389 & Preload an image for later display (useful for when your images are displayed conditionally).\newline
Jonathan Gordon406a3632012-12-09 17:15:17 +1100390 \config{n}: image ID for later referencing in \config{\%xd}\newline
Alexander Levin12427102010-07-02 19:32:48 +0000391 \config{filename}: file name relative to \fname{/.rockbox/} and including ``.bmp''\newline
Marianne Arnoldf67dfd92010-08-13 21:36:44 +0000392 If the filename is ``\_\_list\_icons\_\_'' the list icon bitmap will be used instead\newline
Jonathan Gordon1c1e1c02012-02-29 00:07:16 +1100393 \config{x}: x coordinate (defaults to 0 if both x and y are not specified)\newline
pixelma4601a8b2012-03-02 21:46:53 +0100394 \config{y}: y coordinate. (defaults to 0 if both x and y are not specified)\newline
Alexander Levin12427102010-07-02 19:32:48 +0000395 \config{nimages}: (optional) number of sub-images (tiled vertically, of the same height)
Dominik Riebeling2ce440d2008-03-26 19:35:39 +0000396 contained in the bitmap. Default is 1.\\
Jonathan Gordon3f8e7fc2010-08-05 11:28:48 +0000397 \config{\%xd(n[i] [,tag] [,offset])} & Display a preloaded image.
Jonathan Gordon406a3632012-12-09 17:15:17 +1100398 \config{n}: image ID as it was specified in \config{\%x} or \config{\%xl}\newline
Jonathan Gordon3f8e7fc2010-08-05 11:28:48 +0000399 \config{i}: (optional) number of the sub-image to display (a-z for 1-26 and A-Z for 27-52).
Jonathan Gordon406a3632012-12-09 17:15:17 +1100400 (ignored when \config{tag} is used). Only useable if the ID is a single letter.
Jonathan Gordon3f8e7fc2010-08-05 11:28:48 +0000401 By default the first (i.e. top most) sub-image will be used.\newline
402 \config{tag}: (optional) Another tag to calculate the subimage from e.g \config{\%xd(A, \%mh)} would
403 use the first subimage when \config{\%mh} is on and the second when it is off\newline
Marianne Arnolde6cb22e2010-08-07 08:27:24 +0000404 \config{offset}: (optional) Add this number to the value from the \config{tag} when
Jonathan Gordon3f8e7fc2010-08-05 11:28:48 +0000405 chosing the subimage (may be negative)\\
Jonathan Gordon685cf592012-12-03 20:43:58 +1100406 \config{\%x9(n)}
407 & Display an image as a 9-patch bitmap covering the entire viewport.\newline
408 9-patch images are bitmaps split into 9 segments where the four corners
409 are unscaled, the four middle sections are scaled along one axis and the middle
410 section is scaled on both axis.\newline
411 \config{n}: image ID\\
412
Dominik Riebeling36a31332006-04-09 21:22:42 +0000413 \end{tagmap}
Martin Arver94c12892006-03-23 14:11:52 +0000414
Dominik Riebeling8f44dd22008-03-28 21:49:41 +0000415Examples:
416\begin{enumerate}
417\item Load and display the image \fname{/.rockbox/bg.bmp} with ID ``a'' at 37, 109:\\
Alex Parker64d4ddf2010-06-20 12:58:41 +0000418\config{\%x(a,bg.bmp,37,109)}
Dominik Riebeling8f44dd22008-03-28 21:49:41 +0000419\item Load a bitmap strip containing 5 volume icon images (all the same size)
420with image ID ``M'', and then reference the individual sub-images in a conditional:\\
Alex Parker64d4ddf2010-06-20 12:58:41 +0000421\config{\%xl(M,volume.bmp,134,153,5)}\\
Alexander Levin15d0ac02010-07-02 19:55:47 +0000422\config{\%?pv<\%xd(Ma)|\%xd(Mb)|\%xd(Mc)|%
423\%xd(Md)|\%xd(Me)>}
Dominik Riebeling8f44dd22008-03-28 21:49:41 +0000424\end{enumerate}
Dominik Riebeling2ce440d2008-03-26 19:35:39 +0000425
426
Dominik Riebeling18f319c2006-04-01 17:00:04 +0000427\note{
428 \begin{itemize}
Alexander Levin3adb8212009-03-24 21:39:48 +0000429 \item The images must be in BMP format
Dominik Riebeling18f319c2006-04-01 17:00:04 +0000430 \item The image tag must be on its own line
Jonathan Gordon406a3632012-12-09 17:15:17 +1100431 \item The ID is case sensitive
Marianne Arnoldc4bdf202010-08-14 10:30:42 +0000432 \item The size of the LCD screen for each \dap{} varies. See table below
Dominik Riebeling18f319c2006-04-01 17:00:04 +0000433 for appropriate sizes of each device. The x and y coordinates must
Marianne Arnoldc4bdf202010-08-14 10:30:42 +0000434 respect each of the \daps{} limits.
Dominik Riebeling18f319c2006-04-01 17:00:04 +0000435 \end{itemize}
436}
Jonas Häggqvist410cbd12009-02-20 18:37:57 +0000437}
438
439\opt{albumart}{
Alex Parker018133e2010-05-29 19:02:25 +0000440\subsection{How to display the album art}
441
442Once the album art files are present on your \dap, they can be displayed as
443follows.
444
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000445 \begin{tagmap}
Alexander Levin67f25a42010-07-02 18:54:09 +0000446 \config{\%Cl(x,y,[maxwidth],\tabnlindent[maxheight],\tabnlindent{}hor\_align,\tabnlindent{}vert\_align)}
Alexander Levin12427102010-07-02 19:32:48 +0000447 & Define the settings for album art\newline
448 \config{x}: x coordinate\newline
449 \config{y}: y coordinate\newline
450 \config{maxwidth}: Maximum height\newline
451 \config{maxheight}: Maximum width\newline
452 \config{hor\_align}: Horizontal alignment, enter as `l', `c' or `r' for
453 left, centre or right. Centre is default\newline
454 \config{vert\_align}: Vertical alignment, enter as `t', `c' or `b' for
Alex Parker64d4ddf2010-06-20 12:58:41 +0000455 top, centre or bottom. Centre is default\\
Jonathan Gordon50356d82010-06-08 15:09:32 +0000456 \config{\%Cd} & Display the album art as configured. \\
Alex Parker64d4ddf2010-06-20 12:58:41 +0000457 \config{\%C} & Use in a conditional to determine if an image is available. \\
Jonas Häggqvist410cbd12009-02-20 18:37:57 +0000458 \end{tagmap}
Jonas Häggqvist410cbd12009-02-20 18:37:57 +0000459
460The picture will be rescaled, preserving aspect ratio to fit the given
461\config{maxwidth} and \config{maxheight}. If the aspect ratio doesn't match the
Alex Parker64d4ddf2010-06-20 12:58:41 +0000462configured values, the picture will be placed according to the alignment flags.
Jonas Häggqvist00215342009-02-20 19:08:18 +0000463
464Examples:
465\begin{enumerate}
466 \item Load albumart at position 20,40 and display it without resizing:\\
Alex Parker64d4ddf2010-06-20 12:58:41 +0000467 \config{\%Cl(20,40,,)}
Alexander Levin87b2ad142010-05-20 16:20:58 +0000468 \item Load albumart at position 0,20 and resize it to be at most 100$\times$100
Jonas Häggqvist00215342009-02-20 19:08:18 +0000469 pixels. If the image isn't square, align it to the bottom-right
470 corner:\\
Alex Parker64d4ddf2010-06-20 12:58:41 +0000471 \config{\%Cl(0,20,100,100,r,b)}
Jonas Häggqvist00215342009-02-20 19:08:18 +0000472\end{enumerate}
Marianne Arnoldcf909582012-05-19 17:41:11 +0200473
474For general information where to put album art see \reference{ref:album_art}.
Jonas Häggqvist410cbd12009-02-20 18:37:57 +0000475}
Martin Arver94c12892006-03-23 14:11:52 +0000476
Alex Parkercaa68b52010-05-29 19:02:19 +0000477\opt{radio}{
Alex Parker0926e3e2010-05-13 08:13:42 +0000478\section{FM Radio}
479 \begin{tagmap}
Alex Parker0926e3e2010-05-13 08:13:42 +0000480 \config{\%tt} & Is the tuner tuned?\\
Alexander Levin1940a0b2010-05-13 08:45:22 +0000481 \config{\%tm} & Scan or preset mode? Scan is ``true'', preset is ``false''.\\
Alex Parker0926e3e2010-05-13 08:13:42 +0000482 \config{\%ts} & Is the station in stereo?\\
Alexander Levinedb6bed2010-05-15 21:47:30 +0000483 \config{\%ta} & Minimum frequency (region specific) in MHz.\\
484 \config{\%tb} & Maximum frequency (region specific) in MHz.\\
485 \config{\%tf} & Current frequency in MHz.\\
Alex Parker0926e3e2010-05-13 08:13:42 +0000486 \config{\%Ti} & Current preset id, i.e. 1-based number of the preset
487 within the presets list (usable in playlist viewer).\\
488 \config{\%Tn} & Current preset name (usable in playlist viewer).\\
489 \config{\%Tf} & Current preset frequency (usable in playlist viewer).\\
490 \config{\%Tc} & Preset count, i.e. the number of stations in the current
491 preset list.\\
492 \config{\%tx} & Is RDS available?\\
493 \config{\%ty} & RDS name.\\
494 \config{\%tz} & RDS text.\\
Alex Parkera43fc842010-12-21 10:14:40 +0000495 \config{\%tr} & Signal strength (RSSI). Can be used in a conditional or as
496 a bar.\\
Alex Parker0926e3e2010-05-13 08:13:42 +0000497 \end{tagmap}
498
Alex Parker4b360632010-05-29 19:02:10 +0000499It is also possible to show ``Radio Art'' which can be used to display images
500associated with presets. The tags are exactly the same as for album art,
501described above. Images need to be placed in \fname{/.rockbox/fmpresets/},
502and must have the same name as the preset. They need to be in either
503\fname{.bmp} or \fname{.jpg} format, and the radio must be in preset mode
504and tuned to a preset (and not recording) in order for them to be shown.
Alex Parkercaa68b52010-05-29 19:02:19 +0000505}
Alex Parker4b360632010-05-29 19:02:10 +0000506
Alex Parkerd7cb3b12010-07-31 12:47:12 +0000507\section{Alignment and language direction}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000508 \begin{tagmap}
Alexander Levin0a241402009-03-23 21:46:49 +0000509 \config{\%al} & Align the text left\\
Tomer Shalev13ef6772010-01-08 14:03:43 +0000510 \config{\%aL} & Align the text left, or to the right if RTL language is in use\\
Alex Parkerc4b6c052009-11-22 11:24:49 +0000511 \config{\%ac} & Centre the text\\
Alexander Levin0a241402009-03-23 21:46:49 +0000512 \config{\%ar} & Align the text right\\
Tomer Shalev13ef6772010-01-08 14:03:43 +0000513 \config{\%aR} & Align the text right, or to the left if RTL language is in use\\
Alex Parkerd7cb3b12010-07-31 12:47:12 +0000514 \config{\%ax} & The next tag should follow the set language direction. When
515 prepended to a viewport declaration, the viewport will
516 be horizontally mirrored if the user language is set to
517 a RTL language. Currently the \%Cl, \%V and \%Vl tags
518 support this.\\
519 \config{\%Sr} & Use as a conditional to define options for left to right, or
520 right to left languages. \%?Sr<RTL|LTR>\\
Dominik Riebeling36a31332006-04-09 21:22:42 +0000521 \end{tagmap}
Alex Parkerd7cb3b12010-07-31 12:47:12 +0000522
Dominik Riebeling36a31332006-04-09 21:22:42 +0000523All alignment tags may be present in one line, but they need to be in the
Alex Parkerc4b6c052009-11-22 11:24:49 +0000524order left -- centre -- right. If the aligned texts overlap, they are merged.
Martin Arver94c12892006-03-23 14:11:52 +0000525
Alex Parkerd7cb3b12010-07-31 12:47:12 +0000526Example: \config{\%ax\%V(\dots)}
527
Dominik Riebeling36a31332006-04-09 21:22:42 +0000528\section{Conditional Tags}
Martin Arver94c12892006-03-23 14:11:52 +0000529
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000530\begin{tagmap}
Alexander Levin15d0ac02010-07-02 19:55:47 +0000531\config{\%?xx<true|false>}
Dominik Riebeling36a31332006-04-09 21:22:42 +0000532 & If / Else: Evaluate for true or false case \\
Alexander Levin15d0ac02010-07-02 19:55:47 +0000533\config{\%?xx<alt1|alt2|\tabnlindent{}alt3|\dots|else>}
Dominik Riebeling36a31332006-04-09 21:22:42 +0000534 & Enumerations: Evaluate for first / second / third / \dots / last condition \\
Alex Parker779f1db2010-09-17 19:13:14 +0000535\config{\%if(tag, operator, operand, [option count])}
536 & Allows very simple comparisons with other tags.\newline
537 \config{tag}: the tag to check against.\newline
538 \config{operator}: the comparison to perform - possible options are =, !=,
539 >, >=, <, <=\newline
540 \config{operand}: either a second tag, a number, or text.\newline
541 \config{[option count]}: optional parameter used to select which parameter
542 of a tag to use when the tag has multiple options, e.g. \%?pv<a|b|c|d>\\
Jonathan Gordon40ecdf62012-02-02 22:26:16 +1100543\config{\%and(tag1, tag2, ..., tagN)}\newline
544 & Logical ``and'' operator. Will be evaluate to true if all the tag parameters are true.\\
545\config{\%or(tag1, tag2, ..., tagN)}\newline
546 & Logical ``or'' operator. Will be evaluate to true if any of the tag parameters are true.\\
Dominik Riebeling36a31332006-04-09 21:22:42 +0000547\end{tagmap}
Martin Arver94c12892006-03-23 14:11:52 +0000548
Alex Parker779f1db2010-09-17 19:13:14 +0000549Examples of the \%if tag:\\
550
551\config{\%?if(\%pv, >=, 0)<Clipping possible|Volume OK>} will display ``Clipping
552 possible'' if the volume is higher than or equal to 0 dB, ``Volume OK'' if it
553 is lower.\\
554
555\config{\%?if(\%ia, =, \%Ia)<same artist>} -- this artist and the next artist
556 are the same.\\
557
558\note{When performing a comparison against a string tag such as \%ia, only = and
559 != work, and the comparison is not case sensitive.}
560
Alex Parkere56030a2009-05-15 21:17:21 +0000561\section{Subline Tags}
562
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000563\begin{tagmap}
Alexander Levin67f25a42010-07-02 18:54:09 +0000564\config{\%t(time)}
Alex Parker64d4ddf2010-06-20 12:58:41 +0000565 & Set the subline display cycle time (\%t(5) or \%t(3.4) formats) \\
Alex Parkere56030a2009-05-15 21:17:21 +0000566\config{;}
567 & Split items on a line into separate sublines \\
568\end{tagmap}
Alex Parkere56030a2009-05-15 21:17:21 +0000569
570Allows grouping of several items (sublines) onto one line, with the
571display cycling round the defined sublines. See
572\reference{ref:AlternatingSublines} for details.
573
Marianne Arnoldfa632112010-10-29 17:52:20 +0000574\opt{rtc}{
Marianne Arnolde435e4d2009-05-16 11:22:41 +0000575\section{Time and Date}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000576 \begin{tagmap}
Tomer Shalev13ef6772010-01-08 14:03:43 +0000577 \config{\%cd} & Day of month from 01 to 31\\
578 \config{\%ce} & Zero padded day of month from 1 to 31\\
Alexander Levin12427102010-07-02 19:32:48 +0000579 \config{\%cf} & A conditional for 12/24 hour format.\newline
580 \config{\%?cf<24 hour stuff|12 hour stuff>}\\
Alexander Levin0a241402009-03-23 21:46:49 +0000581 \config{\%cH} & Zero padded hour from 00 to 23 (24 hour format)\\
582 \config{\%ck} & Hour from 0 to 23 (24 hour format)\\
Tomer Shalev13ef6772010-01-08 14:03:43 +0000583 \config{\%cI} & Zero padded hour from 01 to 12 (am/pm format)\\
584 \config{\%cl} & Hour from 1 to 12 (am/pm format)\\
585 \config{\%cm} & Month from 01 to 12\\
Dominik Riebelingf177af42007-04-10 17:38:40 +0000586 \config{\%cM} & Minutes\\
587 \config{\%cS} & Seconds\\
Marianne Arnolde435e4d2009-05-16 11:22:41 +0000588 \config{\%cy} & 2-digit year\\
Dominik Riebelingf177af42007-04-10 17:38:40 +0000589 \config{\%cY} & 4-digit year\\
590 \config{\%cP} & Capital AM/PM\\
591 \config{\%cp} & Lowercase am/pm\\
592 \config{\%ca} & Weekday name\\
593 \config{\%cb} & Month name\\
594 \config{\%cu} & Day of week from 1 to 7, 1 is Monday\\
595 \config{\%cw} & Day of week from 0 to 6, 0 is Sunday\\
596 \end{tagmap}
Marianne Arnoldfa632112010-10-29 17:52:20 +0000597}
Marianne Arnolde435e4d2009-05-16 11:22:41 +0000598
Alex Parker55c8b2b2010-03-21 10:20:14 +0000599\section{Text Translation}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000600 \begin{tagmap}
Alex Parker64d4ddf2010-06-20 12:58:41 +0000601 \config{\%Sx(English)}
Alex Parker55c8b2b2010-03-21 10:20:14 +0000602 & Display the translation of ``English'' in the current language\\
603 \end{tagmap}
604
605 \begin{itemize}
606 \item ``English'' must be a phrase used in the language file.
607 \item It should match the \config{Source:} line in the language file.
608 \end{itemize}
609
610 \note{checkwps cannot verify that the string is correct, so please check on
611 either the simulator or on target.}
612
613
Alex Parkerf7a397b2010-02-28 11:50:11 +0000614\opt{touchscreen}{
Jonathan Gordond7bb5802010-10-28 11:11:01 +0000615 \section{Touchscreen Areas}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000616 \begin{tagmap}
Jonathan Gordon969903b2011-07-28 12:53:22 +0000617 \config{\%T(x,y,width,\tabnlindent{}height, action, [options])}
Alexander Levin4c105b62010-03-07 22:12:16 +0000618 & Invoke the action specified when the user presses in the defined
619 touchscreen area.\\
620 \end{tagmap}
Jonathan Gordon969903b2011-07-28 12:53:22 +0000621
Jonathan Gordon443b1342011-03-27 07:23:38 +0000622 Possible actions are:
Alex Parkerf7a397b2010-02-28 11:50:11 +0000623
624 \begin{description}
Osborne Jacobs67b4b2a2012-03-13 02:28:12 -0400625 \item[none] -- Do nothing.
Alex Parkerf7a397b2010-02-28 11:50:11 +0000626 \item[play] -- Play/pause playback.
627 \item[stop] -- Stop playback and exit the WPS.
Jonathan Gordon98881fd2011-03-22 09:31:45 +0000628 \item[prev] -- Previous track/item.
629 \item[next] -- Next track/item.
Marianne Arnolda0f34622011-05-22 12:54:52 +0000630 \item[wps\_prev] -- Previous track.
631 \item[wps\_next] -- Next track.
Alex Parkerf7a397b2010-02-28 11:50:11 +0000632 \item[ffwd] -- Seek forwards in the track.
633 \item[rwd] -- Seek backwards in the track.
Osborne Jacobs595427c2012-03-03 00:15:31 -0500634 \item[progressbar] -- Seek to the appropriate position in the track based on the touch.
Alex Parkerf7a397b2010-02-28 11:50:11 +0000635 \item[shuffle] -- Toggle shuffle mode.
636 \item[repmode] -- Cycle through the repeat modes.
Alex Parkerf7a397b2010-02-28 11:50:11 +0000637 \item[volume] -- Set the volume to the appropriate level based on the touch.
Alex Parkerf7a397b2010-02-28 11:50:11 +0000638 \item[voldown] -- Decrease the volume by one step.
639 \item[volup] -- Increase the volume by one step.
Jonathan Gordon605e2d02011-01-13 10:56:23 +0000640 \item[mute] -- Un/Mute playback.
Osborne Jacobs595427c2012-03-03 00:15:31 -0500641 \item[createbookmark] -- Create a bookmark in the currently-playing track.
Osborne Jacobs67b4b2a2012-03-13 02:28:12 -0400642 \item[hotkey] -- Performs the action assigned to the hotkey (see Hotkeys section).
Osborne Jacobs595427c2012-03-03 00:15:31 -0500643 \item[menu] -- Go to the main menu.
644 \item[browse] -- Go back to the file browser or database.
Osborne Jacobs67b4b2a2012-03-13 02:28:12 -0400645 \item[resumeplayback] -- Go back to the last music screen (WPS or radio screen).
Osborne Jacobs595427c2012-03-03 00:15:31 -0500646 \item[quickscreen] -- Go to the quickscreen.
647 \item[contextmenu] -- Open the context menu.
648 \item[playlist] -- Go to the playlist viewer.
649 \item[listbookmarks] -- List the bookmarks for the currently-playing directory or playlist.
650 \item[trackinfo] -- Open the track info viewer.
651 \item[pitch] -- Open the pitchscreen.
Alex Parkerb33a2d82011-01-13 18:09:36 +0000652 \item[setting\_inc] -- Increment the subsequently specified setting (e.g
Osborne Jacobs67b4b2a2012-03-13 02:28:12 -0400653 \config{\%T(0,0,32,32, setting\_inc, volume)} increases the volume by one step).
Alex Parkerb33a2d82011-01-13 18:09:36 +0000654 \item[setting\_dec] -- Decrement the subsequently specified setting (e.g
Osborne Jacobs67b4b2a2012-03-13 02:28:12 -0400655 \config{\%T(0,0,32,32, setting\_dec, volume)} decreases the volume by one step).
656 \item[setting\_set] -- Set the subsequently specified setting to a specific value (e.g
657 \config{\%T(0,0,32,32, setting\_set, volume, 0)} sets the volume to 0).
658 \item[lock] -- Soft locks the touchscreen. All touch areas are disabled except for
Marianne Arnolda5c5da42012-05-19 12:50:24 +0200659 areas with the lock action or ones that have the allow\_while\_locked option (see below).
Alex Parkerf7a397b2010-02-28 11:50:11 +0000660 \end{description}
Jonathan Gordon969903b2011-07-28 12:53:22 +0000661 Any (or muliple) of the following options can be used after the action is specified
662 \subsection{Options}
663 \begin{description}
Osborne Jacobs67b4b2a2012-03-13 02:28:12 -0400664 \item[repeat\_press] -- This area will trigger mulitple times when held (i.e for seeking)
665 \item[long\_press] -- This area will trigger once after it is held for a long press
666 \item[reverse\_bar] -- Reverse the bars touch direction (i.e seek right to left)
667 \item[allow\_while\_locked] -- Allows the area to be pressable when the
Jonathan Gordon969903b2011-07-28 12:53:22 +0000668 skin is locked by the lock touch action
669 \end{description}
Alex Parkerf7a397b2010-02-28 11:50:11 +0000670
Jonathan Gordond7bb5802010-10-28 11:11:01 +0000671 \section{Last Touchscreen Press}
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000672 \begin{tagmap}
Alexander Levin4c105b62010-03-07 22:12:16 +0000673 \config{\%Tl} & Indicates that the touchscreen is pressed.\\
674 \end{tagmap}
Alex Parkerf7a397b2010-02-28 11:50:11 +0000675 This tag can be used to display text or images or a viewport when the
676 touchscreen is pressed (like an On Screen Display). If you put a number
677 straight after \%Tl it will be used as a timeout in seconds
Alex Parker64d4ddf2010-06-20 12:58:41 +0000678 (e.g \%Tl(2.5) will give a 2.5 second timeout) between the touchscreen press
Alex Parkerf7a397b2010-02-28 11:50:11 +0000679 being released and the tag going false. If no number is specified it will
680 use a 1 second timeout. It can also be used as a conditional, and can be
681 used with conditional viewports.
682}
Dominik Riebelingf177af42007-04-10 17:38:40 +0000683
Alex Parker15258e02010-09-17 19:13:20 +0000684\section{\label{ref:bar_tags}Bar Tags}
685 Some tags can be used to display a bar which draws according to the value of
686 the tag. To use these tags like a bar you need to use the following parameters
687 (\%XX should be replaced with the actual tag).
Jonathan Gordond336eb32012-06-24 21:52:18 +1000688
689\opt{touchscreen}{
690 Volume and progress bars automatically create touch regions the same size
691 as the bar (slightly larger actually). This can be disabled with the
692 \config{notouch} option.
693}
Alex Parker15258e02010-09-17 19:13:20 +0000694
695\begin{tagmap}
Jonathan Gordon9acd2422010-10-12 12:46:57 +0000696 \config{\%XX(x, y, width, height, [options])}
Alex Parker15258e02010-09-17 19:13:20 +0000697 & Draw the specified tag as a bar\newline
698 \config{x}: x co-ordinate at which to start drawing the bar.\newline
699 \config{y}: y co-ordinate at which to start drawing the bar.\newline
700 \config{width}: width of the bar (- for the full viewport width).\newline
701 \config{height}: height of the bar (- to set to the font height for
702 horizontal bars and to the viewport height for vertical bars).\newline
703 \config{options}: any of the options set out below.\\
704\end{tagmap}
705
706\subsection{Options}
707\begin{description}
Jonathan Gordon9acd2422010-10-12 12:46:57 +0000708 \item[image] -- the next option is either the filename or image label to
709 use for the fill image.
Alex Parker15258e02010-09-17 19:13:20 +0000710 \item[horizontal] -- force the bar to be drawn horizontally.
711 \item[vertical] -- force the bar to be drawn vertically.
712 \item[invert] -- invert the draw direction (i.e. right to left, or top to
713 bottom).
Jonathan Gordonf06f6852011-01-24 09:04:28 +0000714 \item[slider] -- draw a preloaded image over the top of the bar so that
Alex Parkerf70ec762010-10-12 19:34:47 +0000715 the centre of the image matches the current position. This must be
Alex Parker15258e02010-09-17 19:13:20 +0000716 followed by the label of the desired image.
Jonathan Gordonf06f6852011-01-24 09:04:28 +0000717 \item[backdrop] -- draw a preloaded image under the bar. The full
718 image will be displayed and must be the same size as the bar.
719 This must be followed by the label of the desired image.
Alex Parkerf70ec762010-10-12 19:34:47 +0000720 \item[nofill] -- don't draw the bar, only its frame (for use with the
721 ``slider'' option).
722 \item[nobar] -- don't draw the bar or its frame (for use with the
723 ``slider'' option).
Jonathan Gordond336eb32012-06-24 21:52:18 +1000724 \opt{touchscreen}{
725 \item[notouch] -- don't create the touchregion for progress/volume bars.
726 }
Jonathan Gordon65f9df32012-07-05 22:44:13 +1000727 \item[setting] -- Specify the setting name to draw the bar from (bar must be
728 \%St type), the next param is the settings config name.
Alex Parker15258e02010-09-17 19:13:20 +0000729\end{description}
730
731Example: \config{\%pb(0,0,-,-,-,nofill, slider, slider\_image, invert)} -- draw
732a horizontal progressbar which doesn't fill and draws the image
733``slider\_image'' which moves right to left.
734
Alex Parkerf70ec762010-10-12 19:34:47 +0000735\note{If the slider option is used, the bar will be shrunk so that the slider
Jonathan Gordona3ec8482012-07-03 13:14:13 +1000736 fits inside the specified width and height. Example: A 100px bar image with a
737 16px slider image needs the bar to be 116px wide, and should be offset 8px
738 left of the backdrop image to align correctly.}
Teruaki Kawashima3eb58262010-10-12 12:17:39 +0000739
Dominik Riebeling36a31332006-04-09 21:22:42 +0000740\section{Other Tags}
Jonathan Gordon31a05952012-02-26 00:42:53 +1100741
742\begin{tagmap}
743 \config{\%ss(start, length, tag [,number]} & Get a substring from another tag.\\
744\end{tagmap}
745 Use this tag to get a substring from another tag.
746\begin{description}
Jonathan Gordonb2202a32012-03-27 23:42:00 +1100747 \item[start] -- first character to take (0 being the start of the string, negative means from the end of the string)
Jonathan Gordon31a05952012-02-26 00:42:53 +1100748 \item[length] -- length of the substring to return (- for the rest of the string)
749 \item[tag] -- tag to get
750 \item[number] -- OPTIONAL. if this is present it will assume the
751 substring is a number so it can be used with conditionals. (i.e \config{\%cM}).
752 0 is the first conditional option
753\end{description}
754
Michael Chicoine65dc4f22010-03-23 12:02:20 +0000755\begin{tagmap}
Alex Parker64d4ddf2010-06-20 12:58:41 +0000756 \config{\%(} & The character `('\\
757 \config{\%)} & The character `)'\\
758 \config{\%,} & The character `,'\\
Alexander Levin0a241402009-03-23 21:46:49 +0000759 \config{\%\%} & The character `\%'\\
Alexander Levin15d0ac02010-07-02 19:55:47 +0000760 \config{\%<} & The character `<'\\
761 \config{\%|} & The character `|'\\
762 \config{\%>} & The character `>'\\
Alexander Levin0a241402009-03-23 21:46:49 +0000763 \config{\%;} & The character `;'\\
Marianne Arnold498f66f2010-10-12 19:13:24 +0000764 \config{\%\#} & The character `\#'\\
Martin Arverf21f9142006-05-08 21:32:44 +0000765 \config{\%s} & Indicate that the line should scroll. Can occur
766 anywhere in a line (given that the text is
767 displayed; see conditionals above). You can specify
Alexander Levin0a241402009-03-23 21:46:49 +0000768 up to ten scrolling lines. Scrolling lines can not
Martin Arverf21f9142006-05-08 21:32:44 +0000769 contain dynamic content such as timers, peak meters
770 or progress bars.\\
Dominik Riebeling36a31332006-04-09 21:22:42 +0000771\end{tagmap}
Alexander Levin4c105b62010-03-07 22:12:16 +0000772