Nils Wallménius | cb527ca | 2006-09-10 10:17:47 +0000 | [diff] [blame] | 1 | % $Id$ % |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 2 | \chapter{Advanced Topics} |
Martin Arver | 35dcf90 | 2006-03-08 17:58:11 +0000 | [diff] [blame] | 3 | |
Marc Guay | 85eec85 | 2008-06-24 05:16:23 +0000 | [diff] [blame] | 4 | \section{\label{ref:CustomisingUI}Customising the User Interface} |
Nils Wallménius | 12eb058 | 2008-03-23 22:07:09 +0000 | [diff] [blame] | 5 | \opt{lcd_bitmap}{ |
Marianne Arnold | af78b5f | 2008-07-06 16:10:28 +0000 | [diff] [blame] | 6 | \subsection{\label{ref:GettingExtras}Getting Extras} |
| 7 | |
Martin Arver | 7bdd03a | 2006-08-27 15:00:50 +0000 | [diff] [blame] | 8 | Rockbox supports custom fonts. A collection of fonts is available for download |
Marianne Arnold | af78b5f | 2008-07-06 16:10:28 +0000 | [diff] [blame] | 9 | in the font package at \url{http://www.rockbox.org/daily.shtml}.} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 10 | |
Nils Wallménius | 12eb058 | 2008-03-23 22:07:09 +0000 | [diff] [blame] | 11 | \opt{lcd_bitmap}{ |
Dominik Riebeling | 85deab1 | 2006-11-20 19:56:55 +0000 | [diff] [blame] | 12 | \subsection{\label{ref:Loadingfonts}Loading Fonts}\index{Fonts} |
Nils Wallménius | cb527ca | 2006-09-10 10:17:47 +0000 | [diff] [blame] | 13 | Rockbox can load fonts dynamically. Simply copy the \fname{.fnt} file to the |
| 14 | \dap{} and ``play'' it in the \setting{File Browser}. If you want a font to |
| 15 | be loaded automatically every time you start up, it must be located in the |
Marianne Arnold | b2f7c61 | 2007-12-14 02:03:58 +0000 | [diff] [blame] | 16 | \fname{/.rockbox/fonts} directory and the filename must be at most 24 characters |
Nils Wallménius | cb527ca | 2006-09-10 10:17:47 +0000 | [diff] [blame] | 17 | long. You can browse the fonts in \fname{/.rockbox/fonts} under |
Jonas Häggqvist | 4b83175 | 2009-06-22 17:37:36 +0000 | [diff] [blame] | 18 | \setting{Settings $\rightarrow$ Theme Settings $\rightarrow$ Font} |
Alex Parker | 5174341 | 2009-08-25 21:51:55 +0000 | [diff] [blame] | 19 | in the \setting{Main Menu}.\\ |
| 20 | |
Alexander Levin | d930641 | 2010-05-18 20:45:32 +0000 | [diff] [blame] | 21 | \note{Advanced Users Only: Any BDF font should |
Nils Wallménius | cb527ca | 2006-09-10 10:17:47 +0000 | [diff] [blame] | 22 | be usable with Rockbox. To convert from \fname{.bdf} to \fname{.fnt}, use |
| 23 | the \fname{convbdf} tool. This tool can be found in the \fname{tools} |
Alexander Levin | d930641 | 2010-05-18 20:45:32 +0000 | [diff] [blame] | 24 | directory of the Rockbox source code. See \wikilink{CreateFonts\#ConvBdf} |
Alexander Levin | 3fa48ee | 2010-05-19 16:34:20 +0000 | [diff] [blame] | 25 | for more details. Or just run \fname{convbdf} without any parameters to |
| 26 | see the possible options.} |
Dominik Riebeling | ebb8a22 | 2006-04-04 17:48:10 +0000 | [diff] [blame] | 27 | } |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 28 | |
| 29 | \subsection{\label{ref:Loadinglanguages}Loading Languages} |
Dominik Riebeling | 85deab1 | 2006-11-20 19:56:55 +0000 | [diff] [blame] | 30 | \index{Language files}% |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 31 | Rockbox can load language files at runtime. Simply copy the \fname{.lng} file |
Dominik Riebeling | b7eef89 | 2006-04-10 21:47:09 +0000 | [diff] [blame] | 32 | \emph{(do not use the .lang file)} to the \dap\ and ``play'' it in the |
Nils Wallménius | 15c5d26 | 2007-03-15 02:09:15 +0000 | [diff] [blame] | 33 | Rockbox directory browser or select \setting{Settings $\rightarrow$ |
Alex Parker | 5174341 | 2009-08-25 21:51:55 +0000 | [diff] [blame] | 34 | General Settings $\rightarrow$ Language }from the \setting{Main Menu}.\\ |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 35 | |
Dominik Riebeling | b7eef89 | 2006-04-10 21:47:09 +0000 | [diff] [blame] | 36 | \note{If you want a language to be loaded automatically every time you start |
Marianne Arnold | b2f7c61 | 2007-12-14 02:03:58 +0000 | [diff] [blame] | 37 | up, it must be located in the \fname{/.rockbox/langs} directory and the filename |
Alex Parker | 5174341 | 2009-08-25 21:51:55 +0000 | [diff] [blame] | 38 | must be a maximum of 24 characters long.\\} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 39 | |
Dominik Riebeling | ebb8a22 | 2006-04-04 17:48:10 +0000 | [diff] [blame] | 40 | If your language is not yet supported and you want to write your own language |
| 41 | file find the instructions on the Rockbox website: |
Dominik Riebeling | b394e18 | 2006-12-29 19:22:56 +0000 | [diff] [blame] | 42 | \wikilink{LangFiles} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 43 | |
Nils Wallménius | 12eb058 | 2008-03-23 22:07:09 +0000 | [diff] [blame] | 44 | \opt{lcd_color}{ |
Alexander Levin | 71812ca | 2009-03-20 19:33:20 +0000 | [diff] [blame] | 45 | \subsection{\label{ref:ChangingFiletypeColours}Changing Filetype Colours} |
Alex Parker | 6c4661c | 2009-03-18 14:24:28 +0000 | [diff] [blame] | 46 | Rockbox has the capability to modify the \setting{File Browser} to show |
Alexander Levin | 71812ca | 2009-03-20 19:33:20 +0000 | [diff] [blame] | 47 | files of different types in different colours, depending on the file extension. |
Alex Parker | 6c4661c | 2009-03-18 14:24:28 +0000 | [diff] [blame] | 48 | |
Alexander Levin | 71812ca | 2009-03-20 19:33:20 +0000 | [diff] [blame] | 49 | \subsubsection{Set-up} |
Alexander Levin | 277ce9a | 2009-03-21 09:25:49 +0000 | [diff] [blame] | 50 | There are two steps to changing the filetype colours -- creating |
Alexander Levin | 71812ca | 2009-03-20 19:33:20 +0000 | [diff] [blame] | 51 | a file with the extension \fname{.colours} and then activating it using |
| 52 | a config file. The \fname{.colours} files \emph{must} be stored in |
| 53 | the \fname{/.rockbox/themes/} directory. |
| 54 | The \fname{.colours} file is just a text file, and can be edited with |
| 55 | your text editor of choice. |
Alex Parker | 6c4661c | 2009-03-18 14:24:28 +0000 | [diff] [blame] | 56 | |
Alexander Levin | 71812ca | 2009-03-20 19:33:20 +0000 | [diff] [blame] | 57 | \subsubsection{Creating the .colours file} |
| 58 | The \fname{.colours} file consists of the file extension |
| 59 | (or \fname{folder}) followed by a colon and then the colour desired |
| 60 | as an RGB value in hexadecimal, as in the following example:\\* |
| 61 | \\ |
| 62 | \config{folder:808080}\\ |
| 63 | \config{mp3:00FF00}\\ |
| 64 | \config{ogg:00FF00}\\ |
| 65 | \config{txt:FF0000}\\ |
| 66 | \config{???:FFFFFF}\\* |
Alex Parker | 6c4661c | 2009-03-18 14:24:28 +0000 | [diff] [blame] | 67 | |
Alexander Levin | 71812ca | 2009-03-20 19:33:20 +0000 | [diff] [blame] | 68 | The permissible extensions are as follows:\\* |
| 69 | \\ |
| 70 | \config{folder, m3u, m3u8, cfg, wps, lng, rock, bmark, cue, colours, mpa, |
| 71 | \firmwareextension{}, % |
| 72 | \opt{swcodec}{mp1, }mp2, mp3% |
| 73 | \opt{swcodec}{, ogg, oga, wma, wmv, asf, wav, flac, ac3, a52, mpc, |
| 74 | wv, m4a, m4b, mp4, mod, shn, aif, aiff, spx, sid, adx, nsf, nsfe, |
| 75 | spc, ape, mac, sap}% |
| 76 | \opt{lcd_bitmap}{\opt{swcodec}{, mpg, mpeg}}% |
| 77 | \opt{HAVE_REMOTE_LCD}{, rwps}% |
| 78 | \opt{lcd_non-mono}{, bmp}% |
| 79 | \opt{radio}{, fmr}% |
| 80 | \opt{lcd_bitmap}{, fnt, kbd}}\\* |
| 81 | %It'd be ideal to get these from filetypes.c |
Alex Parker | 6c4661c | 2009-03-18 14:24:28 +0000 | [diff] [blame] | 82 | |
Alexander Levin | 71812ca | 2009-03-20 19:33:20 +0000 | [diff] [blame] | 83 | All file extensions that are not either specifically listed in the |
| 84 | \fname{.colours} files or are not in the list above will be |
| 85 | set to the colour given by \config{???}. Extensions that |
| 86 | are in the above list but not in the \fname{.colours} |
| 87 | file will be set to the foreground colour as normal. |
Alex Parker | 6c4661c | 2009-03-18 14:24:28 +0000 | [diff] [blame] | 88 | |
Alexander Levin | 71812ca | 2009-03-20 19:33:20 +0000 | [diff] [blame] | 89 | \subsubsection{Activating} |
| 90 | To activate the filetype colours, the \fname{.colours} file needs to be |
| 91 | invoked from a \fname{.cfg} configuration file. The easiest way to do |
| 92 | this is to create a new text file containing the following single |
| 93 | line:\\* |
| 94 | \\ |
| 95 | \config{filetype colours: /.rockbox/themes/filename.colours}\\* |
Alex Parker | 6c4661c | 2009-03-18 14:24:28 +0000 | [diff] [blame] | 96 | |
Alexander Levin | 71812ca | 2009-03-20 19:33:20 +0000 | [diff] [blame] | 97 | where filename is replaced by the filename you used when creating the |
| 98 | \fname{.colours} file. Save this file as e.g. \fname{colours.cfg} in the |
| 99 | \fname{/.rockbox/themes} directory and then activate the config file |
| 100 | from the menu as normal |
| 101 | (\setting{Settings} $\rightarrow$ \setting{Theme Settings}% |
Jonas Häggqvist | 4b83175 | 2009-06-22 17:37:36 +0000 | [diff] [blame] | 102 | $\rightarrow$ \setting{Browse Theme Files}). |
Alex Parker | 6c4661c | 2009-03-18 14:24:28 +0000 | [diff] [blame] | 103 | |
Alexander Levin | 71812ca | 2009-03-20 19:33:20 +0000 | [diff] [blame] | 104 | \subsubsection{Editing} |
| 105 | The built-in \setting{Text Editor} (see \reference{sec:text_editor}) |
| 106 | automatically understands the |
| 107 | \fname{.colours} file format, but an external text editor can |
| 108 | also be used. To edit the \fname{.colours} file using Rockbox, |
| 109 | ``play'' it in the \setting{File Browser}. The file will open in |
| 110 | the \setting{Text Editor}. Upon selecting a line, the following choices |
| 111 | will appear:\\* |
| 112 | \\ |
| 113 | \config{Extension}\\ |
| 114 | \config{Colour}\\* |
| 115 | |
| 116 | If \config{Extension} is selected, the \setting{virtual keyboard} |
| 117 | (see \reference{sec:virtual_keyboard}) appears, |
| 118 | allowing the file extension to be modified. If \config{Colour} |
| 119 | is selected, the colour selector screen appears. Choose the desired |
| 120 | colour, then save the \fname{.colours} file using the standard |
| 121 | \setting{Text Editor} controls. |
Nils Wallménius | 15c5d26 | 2007-03-15 02:09:15 +0000 | [diff] [blame] | 122 | } |
| 123 | |
Marianne Arnold | 8189246 | 2008-07-15 20:57:05 +0000 | [diff] [blame] | 124 | \opt{lcd_non-mono}{% |
Nils Wallménius | da55588 | 2006-11-13 15:14:28 +0000 | [diff] [blame] | 125 | \subsection{\label{ref:LoadingBackdrops}Loading Backdrops} |
| 126 | Rockbox supports showing an image as a backdrop in the \setting{File Browser} |
| 127 | and the menus. The backdrop image must be a \fname{.bmp} file of the exact |
Alexander Levin | 87b2ad14 | 2010-05-20 16:20:58 +0000 | [diff] [blame] | 128 | same dimensions as the display in your \dap{} (\dapdisplaysize{} with the last |
Nils Wallménius | da55588 | 2006-11-13 15:14:28 +0000 | [diff] [blame] | 129 | number giving the colour depth in bits). To use an image as a backdrop browse |
Marianne Arnold | 90bcefa | 2008-03-03 23:01:44 +0000 | [diff] [blame] | 130 | to it in the \setting{File Browser} and open the \setting{Context Menu} |
| 131 | (see \reference{ref:Contextmenu}) on it and select the option |
Nils Wallménius | da55588 | 2006-11-13 15:14:28 +0000 | [diff] [blame] | 132 | \setting{Set As Backdrop}. If you want rockbox to remember your |
| 133 | backdrop the next time you start your \dap{} the backdrop must be placed in |
Marianne Arnold | b2f7c61 | 2007-12-14 02:03:58 +0000 | [diff] [blame] | 134 | the \fname{/.rockbox/backdrops} directory. |
Nils Wallménius | da55588 | 2006-11-13 15:14:28 +0000 | [diff] [blame] | 135 | }% |
| 136 | |
Alex Parker | ab563da | 2009-09-20 16:48:45 +0000 | [diff] [blame] | 137 | \nopt{lcd_charcell}{ |
| 138 | \subsection{UI Viewport} |
| 139 | By default, the UI is drawn on the whole screen. This can be changed so that |
| 140 | the UI is confined to a specific area of the screen, by use of a UI |
| 141 | viewport. This is done by adding the following line to the |
| 142 | \fname{.cfg} file for a theme:\\* |
| 143 | |
| 144 | \nopt{lcd_non-mono}{\config{ui viewport: X,Y,[width],[height],[font]}} |
| 145 | \nopt{lcd_color}{\opt{lcd_non-mono}{ |
| 146 | \config{ui viewport: X,Y,[width],[height],[font],[fgshade],[bgshade]}}} |
| 147 | \opt{lcd_color}{ |
| 148 | \config{ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]}} |
| 149 | \\* |
| 150 | |
| 151 | \opt{HAVE_REMOTE_LCD}{ |
| 152 | The dimensions of the menu that is displayed on the remote control of your |
| 153 | \dap\ can be set in the same way. The line to be added to the theme |
| 154 | \fname{.cfg} is the following:\\* |
| 155 | |
| 156 | \nopt{lcd_non-mono}{\config{remote ui viewport: X,Y,[width],[height],[font]}} |
| 157 | \nopt{lcd_color}{\opt{lcd_non-mono}{ |
| 158 | \config{remote ui viewport: X,Y,[width],[height],[font],[fgshade],[bgshade]}}} |
| 159 | \opt{lcd_color}{ |
| 160 | \config{remote ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]}} |
| 161 | \\* |
| 162 | } |
| 163 | |
| 164 | Only the first two parameters \emph{have} to be specified, the others can |
Alexander Levin | b57fe48 | 2009-12-23 20:05:29 +0000 | [diff] [blame] | 165 | be omitted using `-' as a placeholder. The syntax is very similar to WPS |
Alex Parker | ab563da | 2009-09-20 16:48:45 +0000 | [diff] [blame] | 166 | viewports (see \reference{ref:Viewports}). Briefly: |
| 167 | |
| 168 | \nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-uivp-syntax.tex}} |
| 169 | \nopt{lcd_color}{\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-uivp-syntax.tex}}} |
| 170 | \opt{lcd_color}{\input{advanced_topics/viewports/colour-uivp-syntax.tex}} |
| 171 | } |
| 172 | |
Alex Parker | 40782d5 | 2010-05-13 08:13:31 +0000 | [diff] [blame] | 173 | \section{\label{ref:ConfiguringtheWPS}Configuring the Theme} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 174 | |
Alex Parker | 40782d5 | 2010-05-13 08:13:31 +0000 | [diff] [blame] | 175 | \subsection{Themeing -- General Info} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 176 | |
Alex Parker | 40782d5 | 2010-05-13 08:13:31 +0000 | [diff] [blame] | 177 | There are various different aspects of the Rockbox interface |
| 178 | that can be themed -- the WPS or \setting{While Playing Screen}, the FMS or |
| 179 | \setting{FM Screen} (if the \dap{} has a tuner), and the SBS or |
Jonathan Gordon | 3238293 | 2010-05-16 11:20:42 +0000 | [diff] [blame] | 180 | \setting{Base Skin}. The WPS is the name used to |
Alex Parker | 40782d5 | 2010-05-13 08:13:31 +0000 | [diff] [blame] | 181 | describe the information displayed on the \daps{} screen whilst an audio |
| 182 | track is being played, the FMS is the screen shown while listening to the |
Jonathan Gordon | 3238293 | 2010-05-16 11:20:42 +0000 | [diff] [blame] | 183 | radio, and the SBS lets you specify a base skin that is shown in the |
Alex Parker | 40782d5 | 2010-05-13 08:13:31 +0000 | [diff] [blame] | 184 | menus and browsers, as well as the WPS and FMS. The SBS also allows you to |
| 185 | control certain aspects of the appearance of the menus/browsers. |
| 186 | There are a number of themes included in Rockbox, and |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 187 | you can load one of these at any time by selecting it in |
Alex Parker | 40782d5 | 2010-05-13 08:13:31 +0000 | [diff] [blame] | 188 | \setting{Settings $\rightarrow$ Theme Settings $\rightarrow$ Browse Theme Files}. |
| 189 | It is also possible to set individual items of a theme from within the |
| 190 | \setting{Settings $\rightarrow$ Theme Settings} menu. |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 191 | |
Dominik Riebeling | b7eef89 | 2006-04-10 21:47:09 +0000 | [diff] [blame] | 192 | |
Alex Parker | 40782d5 | 2010-05-13 08:13:31 +0000 | [diff] [blame] | 193 | \subsection{\label{ref:CreateYourOwnWPS}Themes -- Create Your Own} |
| 194 | The theme files are simple text files, and can be created (or edited) in your |
| 195 | favourite text editor. To make sure non-English characters |
Alex Parker | 1b0c77f | 2010-06-20 12:58:09 +0000 | [diff] [blame] | 196 | display correctly in your theme you must save the theme files with UTF-8 |
| 197 | character encoding. This can be done in most editors, for example Notepad in |
| 198 | Windows 2000 or XP (but not in 9x/ME) can do this. |
Alex Parker | 40782d5 | 2010-05-13 08:13:31 +0000 | [diff] [blame] | 199 | |
| 200 | \begin{description} |
| 201 | \item [Files Locations: ] Each different ``themeable'' aspect requires its own file -- |
| 202 | WPS files have the extension \fname{.wps}, FM screen files have the extension |
| 203 | \fname{.fms}, and SBS files have the extension \fname{.sbs}. The main theme |
| 204 | file has the extension \fname{.cfg}. All files should have the same name. |
| 205 | |
| 206 | The theme \fname{.cfg} file should be placed in the \fname{/.rockbox/themes} |
| 207 | directory, while the \fname{.wps}, \fname{.fms} and \fname{.sbs} files should |
| 208 | be placed in the \fname{/.rockbox/wps} directory. Any images used by the |
| 209 | theme should be placed in a subdirectory of \fname{/.rockbox/wps} with the |
| 210 | same name as the theme, e.g. if the theme files are named |
| 211 | \fname{mytheme.wps, mytheme.sbs} etc., then the images should be placed in |
| 212 | \fname{/.rockbox/wps/mytheme}. |
| 213 | \end{description} |
| 214 | |
| 215 | All full list of the available tags are given in appendix |
| 216 | \reference{ref:wps_tags}; some of the more powerful concepts in theme designe |
| 217 | are discussed below. |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 218 | |
Dominik Riebeling | f949c8e | 2006-06-07 17:09:06 +0000 | [diff] [blame] | 219 | \begin{itemize} |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 220 | \item All characters not preceded by \% are displayed as typed. |
| 221 | \item Lines beginning with \# are comments and will be ignored. |
Dominik Riebeling | f949c8e | 2006-06-07 17:09:06 +0000 | [diff] [blame] | 222 | \end{itemize} |
Dominik Riebeling | b7eef89 | 2006-04-10 21:47:09 +0000 | [diff] [blame] | 223 | |
Alexander Levin | 87b2ad14 | 2010-05-20 16:20:58 +0000 | [diff] [blame] | 224 | \note{Keep in mind that your \dap{} resolution is \dapdisplaysize{} (with |
Dominik Riebeling | 5ec3805 | 2006-08-28 18:09:17 +0000 | [diff] [blame] | 225 | the last number giving the colour depth in bits) when |
| 226 | designing your own WPS, or if you use a WPS designed for another target. |
| 227 | \opt{HAVE_REMOTE_LCD}{The resolution of the remote is |
Alexander Levin | 87b2ad14 | 2010-05-20 16:20:58 +0000 | [diff] [blame] | 228 | \opt{h100,h300}{128$\times$64$\times$1}\opt{x5,m5}{128$\times$96$\times$2} pixels.}} |
Martin Arver | 6fc30d6 | 2006-08-28 17:44:49 +0000 | [diff] [blame] | 229 | |
Alex Parker | ab563da | 2009-09-20 16:48:45 +0000 | [diff] [blame] | 230 | \nopt{lcd_charcell}{ |
| 231 | \subsubsection{\label{ref:Viewports}Viewports} |
| 232 | |
| 233 | By default, a viewport filling the whole screen contains all the elements |
Alex Parker | 64d4ddf | 2010-06-20 12:58:41 +0000 | [diff] [blame] | 234 | defined in each theme file. The |
Alex Parker | ab563da | 2009-09-20 16:48:45 +0000 | [diff] [blame] | 235 | \opt{lcd_non-mono}{elements in this viewport are displayed |
Alexander Levin | 64bb9a0 | 2010-05-18 20:23:22 +0000 | [diff] [blame] | 236 | with the same background/\linebreak{}foreground |
Alex Parker | ab563da | 2009-09-20 16:48:45 +0000 | [diff] [blame] | 237 | \opt{lcd_color}{colours}\nopt{lcd_color}{shades} and the} |
| 238 | text is rendered in the |
| 239 | same font as in the main menu. To change this behaviour a custom viewport can |
| 240 | be defined. A viewport is a rectangular window on the screen% |
| 241 | \opt{lcd_non-mono}{ with its own foreground/background |
| 242 | \opt{lcd_color}{colours}\nopt{lcd_color}{shades}}. |
| 243 | This window also has variable dimensions. To |
Alex Parker | 64d4ddf | 2010-06-20 12:58:41 +0000 | [diff] [blame] | 244 | define a viewport a line starting \config{{\%V(\dots}} has to be |
| 245 | present in the theme file. The full syntax will be explained later in |
Alex Parker | ab563da | 2009-09-20 16:48:45 +0000 | [diff] [blame] | 246 | this section. All elements placed before the |
| 247 | line defining a viewport are displayed in the default viewport. Elements |
| 248 | defined after a viewport declaration are drawn within that viewport. |
| 249 | \opt{lcd_bitmap}{Loading images (see Appendix \reference{ref:wps_images}) |
| 250 | should be done within the default viewport.} |
| 251 | A viewport ends either with the end of the file, or with the next viewport |
| 252 | declaration line. Viewports sharing the same |
| 253 | coordinates and dimensions cannot be displayed at the same time. Viewports |
| 254 | cannot be layered \emph{transparently} over one another. Subsequent viewports |
| 255 | will be drawn over any other viewports already drawn onto that |
| 256 | area of the screen. |
| 257 | |
| 258 | \nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-vp-syntax.tex}} |
| 259 | \nopt{lcd_color}{\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-vp-syntax.tex}}} |
| 260 | \opt{lcd_color}{\input{advanced_topics/viewports/colour-vp-syntax.tex}} |
| 261 | |
| 262 | |
| 263 | \subsubsection{Conditional Viewports} |
| 264 | |
| 265 | Any viewport can be displayed either permanently or conditionally. |
Alex Parker | 64d4ddf | 2010-06-20 12:58:41 +0000 | [diff] [blame] | 266 | Defining a viewport as \config{{\%V(\dots}} |
Alex Parker | ab563da | 2009-09-20 16:48:45 +0000 | [diff] [blame] | 267 | will display it permanently. |
| 268 | |
| 269 | \begin{itemize} |
Alexander Levin | e39f409 | 2010-06-23 18:21:35 +0000 | [diff] [blame] | 270 | \item {\config{\%Vl('identifier',\dots)}} |
Alexander Levin | e0bb2218 | 2010-05-12 22:07:49 +0000 | [diff] [blame] | 271 | This tag preloads a viewport for later display. `identifier' is a single |
Alexander Levin | 5a379bc | 2010-05-20 16:35:45 +0000 | [diff] [blame] | 272 | lowercase letter (a-z) and the `\dots' parameters use the same logic as |
Alex Parker | ab563da | 2009-09-20 16:48:45 +0000 | [diff] [blame] | 273 | the \config{\%V} tag explained above. |
Alexander Levin | e39f409 | 2010-06-23 18:21:35 +0000 | [diff] [blame] | 274 | \item {\config{\%Vd('identifier')}} Display the `identifier' viewport. |
Alex Parker | ab563da | 2009-09-20 16:48:45 +0000 | [diff] [blame] | 275 | \end{itemize} |
| 276 | |
| 277 | Viewports can share identifiers so that you can display multiple viewports |
| 278 | with one \%Vd line. |
| 279 | |
| 280 | \nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-conditional.tex}} |
| 281 | \nopt{lcd_color}{% |
| 282 | \opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-conditional.tex}}} |
| 283 | \opt{lcd_color}{\input{advanced_topics/viewports/colour-conditional.tex}} |
| 284 | \\* |
| 285 | |
| 286 | \note{The tag to display conditional viewports must come before the tag to |
| 287 | preload the viewport in the \fname{.wps} file.} |
Alex Parker | 6d549df | 2010-05-13 08:13:37 +0000 | [diff] [blame] | 288 | |
| 289 | \subsection{Info Viewport (SBS only)} |
| 290 | As mentioned above, it is possible to set a UI viewport via the theme |
| 291 | \fname{.cfg} file. It is also possible to set the UI viewport through the SBS |
| 292 | file, and to conditionally select different UI viewports. |
| 293 | |
| 294 | \begin{itemize} |
Alexander Levin | e39f409 | 2010-06-23 18:21:35 +0000 | [diff] [blame] | 295 | \item {\config{\%Vi('label',\dots)}} |
Alex Parker | 6d549df | 2010-05-13 08:13:37 +0000 | [diff] [blame] | 296 | This viewport is used as Custom UI Viewport in the case that the theme |
| 297 | doesn't have a ui viewport set in the theme \fname{.cfg} file. Having this |
| 298 | is strongly recommended since it makes you able to use the SBS |
| 299 | with other themes. If label is set this viewport can be selectivly used as the |
Alexander Levin | 5a379bc | 2010-05-20 16:35:45 +0000 | [diff] [blame] | 300 | Info Viewport using the \%VI tag. The `\dots' parameters use the same logic as |
Alex Parker | 6d549df | 2010-05-13 08:13:37 +0000 | [diff] [blame] | 301 | the \config{\%V} tag explained above. |
| 302 | |
Alexander Levin | e39f409 | 2010-06-23 18:21:35 +0000 | [diff] [blame] | 303 | \item {\config{\%VI('label')}} Set the Info Viewport to use the viewport called |
Alex Parker | 6d549df | 2010-05-13 08:13:37 +0000 | [diff] [blame] | 304 | label, as declared with the previous tag. |
| 305 | \end{itemize} |
Alex Parker | 1b0c77f | 2010-06-20 12:58:09 +0000 | [diff] [blame] | 306 | |
| 307 | \subsection{\label{ref:multifont}Additional Fonts} |
| 308 | Additional fonts can be loaded within each screen file to be used in that |
| 309 | screen. In this way not only can you have different fonts between e.g. the menu |
| 310 | and the WPS, but you can use multiple fonts in each of the individual screens.\\ |
| 311 | |
Alexander Levin | e39f409 | 2010-06-23 18:21:35 +0000 | [diff] [blame] | 312 | \config{\%Fl('id',filename)} |
Alex Parker | 1b0c77f | 2010-06-20 12:58:09 +0000 | [diff] [blame] | 313 | |
| 314 | \begin{itemize} |
Alex Parker | 994d955 | 2010-06-20 16:23:47 +0000 | [diff] [blame] | 315 | \item `id' is the number you want to use in viewport declarations, 0 and 1 |
Alex Parker | 1b0c77f | 2010-06-20 12:58:09 +0000 | [diff] [blame] | 316 | are reserved and so can't be used. |
| 317 | \item `filename' is the font filename to load. Fonts should be stored in |
| 318 | \fname{/.rockbox/fonts/} |
| 319 | \end{itemize} |
| 320 | |
Alex Parker | 64d4ddf | 2010-06-20 12:58:41 +0000 | [diff] [blame] | 321 | An example would be: \config{\%Fl(2,12-Nimbus.fnt)} |
Alex Parker | 1b0c77f | 2010-06-20 12:58:09 +0000 | [diff] [blame] | 322 | |
Alex Parker | ab563da | 2009-09-20 16:48:45 +0000 | [diff] [blame] | 323 | } |
| 324 | |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 325 | \subsubsection{Conditional Tags} |
Martin Arver | d3d3e34 | 2006-03-15 10:56:14 +0000 | [diff] [blame] | 326 | |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 327 | \begin{description} |
| 328 | \item[If/else: ] |
Dominik Riebeling | f949c8e | 2006-06-07 17:09:06 +0000 | [diff] [blame] | 329 | Syntax: \config{\%?xx{\textless}true{\textbar}false{\textgreater}} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 330 | |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 331 | If the tag specified by ``\config{xx}'' has a value, the text between the |
| 332 | ``\config{{\textless}}'' and the ``\config{{\textbar}}'' is displayed (the true |
| 333 | part), else the text between the ``\config{{\textbar}}'' and the |
| 334 | ``\config{{\textgreater}}'' is displayed (the false part). |
| 335 | The else part is optional, so the ``\config{{\textbar}}'' does not have to be |
| 336 | specified if no else part is desired. The conditionals nest, so the text in the |
| 337 | if and else part can contain all \config{\%} commands, including conditionals. |
Martin Arver | d3d3e34 | 2006-03-15 10:56:14 +0000 | [diff] [blame] | 338 | |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 339 | \item[Enumerations: ] |
Dominik Riebeling | f949c8e | 2006-06-07 17:09:06 +0000 | [diff] [blame] | 340 | Syntax: \config{\%?xx{\textless}alt1{\textbar}alt2{\textbar}alt3{\textbar}\dots{\textbar}else{\textgreater}} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 341 | |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 342 | For tags with multiple values, like Play status, the conditional can hold a |
| 343 | list of alternatives, one for each value the tag can have. |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 344 | Example enumeration: |
| 345 | \begin{example} |
Martin Arver | 0642451 | 2006-10-25 22:12:25 +0000 | [diff] [blame] | 346 | \%?mp{\textless}Stop{\textbar}\%Play{\textbar}Pause{\textbar}Ffwd{\textbar}Rew{\textgreater} |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 347 | \end{example} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 348 | |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 349 | The last else part is optional, and will be displayed if the tag has no value. |
| 350 | The WPS parser will always display the last part if the tag has no value, or if |
| 351 | the list of alternatives is too short. |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 352 | \end{description} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 353 | |
Marc Guay | 85eec85 | 2008-06-24 05:16:23 +0000 | [diff] [blame] | 354 | \subsubsection{Next Song Info} |
Dominik Riebeling | b7eef89 | 2006-04-10 21:47:09 +0000 | [diff] [blame] | 355 | You can display information about the next song -- the song that is |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 356 | about to play after the one currently playing (unless you change the |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 357 | plan). |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 358 | |
Dominik Riebeling | f949c8e | 2006-06-07 17:09:06 +0000 | [diff] [blame] | 359 | If you use the upper-case versions of the |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 360 | three tags: \config{F}, \config{I} and \config{D}, they will instead refer to |
| 361 | the next song instead of the current one. Example: \config{\%Ig} is the genre |
Alex Parker | 5174341 | 2009-08-25 21:51:55 +0000 | [diff] [blame] | 362 | name used in the next song and \config{\%Ff} is the mp3 frequency.\\ |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 363 | |
Dominik Riebeling | f949c8e | 2006-06-07 17:09:06 +0000 | [diff] [blame] | 364 | \note{The next song information \emph{will not} be available at all |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 365 | times, but will most likely be available at the end of a song. We |
| 366 | suggest you use the conditional display tag a lot when displaying |
| 367 | information about the next song!} |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 368 | |
Alex Parker | e56030a | 2009-05-15 21:17:21 +0000 | [diff] [blame] | 369 | \subsubsection{\label{ref:AlternatingSublines}Alternating Sublines} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 370 | |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 371 | It is possible to group items on each line into 2 or more groups or |
| 372 | ``sublines''. Each subline will be displayed in succession on the line for a |
| 373 | specified time, alternating continuously through each defined subline. |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 374 | |
| 375 | Items on a line are broken into sublines with the semicolon |
Alexander Levin | 5a379bc | 2010-05-20 16:35:45 +0000 | [diff] [blame] | 376 | `\config{;}' character. The display time for |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 377 | each subline defaults to 2 seconds unless modified by using the |
Alexander Levin | 5a379bc | 2010-05-20 16:35:45 +0000 | [diff] [blame] | 378 | `\config{\%t}' tag to specify an alternate |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 379 | time (in seconds and optional tenths of a second) for the subline to be |
| 380 | displayed. |
| 381 | |
| 382 | Subline related special characters and tags: |
Dominik Riebeling | f949c8e | 2006-06-07 17:09:06 +0000 | [diff] [blame] | 383 | \begin{description} |
| 384 | \item[;] Split items on a line into separate sublines |
| 385 | \item[\%t] Set the subline display time. The |
Alex Parker | 64d4ddf | 2010-06-20 12:58:41 +0000 | [diff] [blame] | 386 | `\config{\%t}' is followed by either integer seconds (\config{\%t5}), or seconds |
| 387 | and tenths of a second within () e.g. (\config{\%t(3.5)}). |
Dominik Riebeling | f949c8e | 2006-06-07 17:09:06 +0000 | [diff] [blame] | 388 | \end{description} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 389 | |
| 390 | Each alternating subline can still be optionally scrolled while it is |
| 391 | being displayed, and scrollable formats can be displayed on the same |
| 392 | line with non{}-scrollable formats (such as track elapsed time) as long |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 393 | as they are separated into different sublines. |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 394 | Example subline definition: |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 395 | \begin{example} |
Alex Parker | 64d4ddf | 2010-06-20 12:58:41 +0000 | [diff] [blame] | 396 | %s%t(4)%ia;%s%it;%t(3)%pc %pr : Display id3 artist for 4 seconds, |
Martin Arver | 49cdd5e | 2006-06-07 13:29:52 +0000 | [diff] [blame] | 397 | Display id3 title for 2 seconds, |
| 398 | Display current and remaining track time |
| 399 | for 3 seconds, |
| 400 | repeat... |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 401 | \end{example} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 402 | |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 403 | Conditionals can be used with sublines to display a different set and/or number |
| 404 | of sublines on the line depending on the evaluation of the conditional. |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 405 | Example subline with conditionals: |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 406 | \begin{example} |
Alex Parker | 64d4ddf | 2010-06-20 12:58:41 +0000 | [diff] [blame] | 407 | %?it{\textless}%t(8)%s%it{\textbar}%s%fn{\textgreater};%?ia{\textless}%t(3)%s%ia{\textbar}%t(0){\textgreater}\\ |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 408 | \end{example} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 409 | |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 410 | The format above will do two different things depending if ID3 tags are |
| 411 | present. If the ID3 artist and title are present: |
Dominik Riebeling | f949c8e | 2006-06-07 17:09:06 +0000 | [diff] [blame] | 412 | \begin{itemize} |
| 413 | \item Display id3 title for 8 seconds, |
| 414 | \item Display id3 artist for 3 seconds, |
| 415 | \item repeat\dots |
| 416 | \end{itemize} |
| 417 | If the ID3 artist and title are not present: |
| 418 | \begin{itemize} |
| 419 | \item Display the filename continuously. |
| 420 | \end{itemize} |
Dominik Riebeling | ebb8a22 | 2006-04-04 17:48:10 +0000 | [diff] [blame] | 421 | Note that by using a subline display time of 0 in one branch of a conditional, |
| 422 | a subline can be skipped (not displayed) when that condition is met. |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 423 | |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 424 | \subsubsection{Using Images} |
Dominik Riebeling | b7eef89 | 2006-04-10 21:47:09 +0000 | [diff] [blame] | 425 | You can have as many as 52 images in your WPS. There are various ways of |
Dominik Riebeling | ebb8a22 | 2006-04-04 17:48:10 +0000 | [diff] [blame] | 426 | displaying images: |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 427 | \begin{enumerate} |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 428 | \item Load and always show the image, using the \config{\%x} tag |
| 429 | \item Preload the image with \config{\%xl} and show it with \config{\%xd}. |
| 430 | This way you can have your images displayed conditionally. |
Nils Wallménius | da55588 | 2006-11-13 15:14:28 +0000 | [diff] [blame] | 431 | \nopt{archos}{% |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 432 | \item Load an image and show as backdrop using the \config{\%X} tag. The |
| 433 | image must be of the same exact dimensions as your display. |
Nils Wallménius | da55588 | 2006-11-13 15:14:28 +0000 | [diff] [blame] | 434 | }% |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 435 | \end{enumerate} |
Martin Arver | 959d23e | 2006-06-04 15:03:39 +0000 | [diff] [blame] | 436 | |
Nils Wallménius | 12eb058 | 2008-03-23 22:07:09 +0000 | [diff] [blame] | 437 | \optv{swcodec}{% This doesn't depend on swcodec but we don't have a \noptv |
Nils Wallménius | da55588 | 2006-11-13 15:14:28 +0000 | [diff] [blame] | 438 | % command. |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 439 | Example on background image use: |
| 440 | \begin{example} |
Alex Parker | 64d4ddf | 2010-06-20 12:58:41 +0000 | [diff] [blame] | 441 | %X(background.bmp) |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 442 | \end{example} |
| 443 | The image with filename \fname{background.bmp} is loaded and used in the WPS. |
Nils Wallménius | da55588 | 2006-11-13 15:14:28 +0000 | [diff] [blame] | 444 | }% |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 445 | |
| 446 | Example on bitmap preloading and use: |
| 447 | \begin{example} |
Alex Parker | 64d4ddf | 2010-06-20 12:58:41 +0000 | [diff] [blame] | 448 | %x(a,static_icon.bmp,50,50) |
| 449 | %xl(b,rep\_off.bmp,16,64) |
| 450 | %xl(c,rep\_all.bmp,16,64) |
| 451 | %xl(d,rep\_one.bmp,16,64) |
| 452 | %xl(e,rep\_shuffle.bmp,16,64) |
| 453 | %?mm<%xd(b)|%xd(c)|%xd(d)|%xd(e)> |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 454 | \end{example} |
| 455 | Four images at the same x and y position are preloaded in the example. Which |
Martin Arver | 68e4017 | 2006-06-07 16:37:04 +0000 | [diff] [blame] | 456 | image to display is determined by the \config{\%mm} tag (the repeat mode). |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 457 | |
| 458 | \subsubsection{Example File} |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 459 | \begin{example} |
Dominik Riebeling | f949c8e | 2006-06-07 17:09:06 +0000 | [diff] [blame] | 460 | %s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]> |
| 461 | %pb%pc/%pt |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 462 | \end{example} |
Dominik Riebeling | ebb8a22 | 2006-04-04 17:48:10 +0000 | [diff] [blame] | 463 | That is, ``tracknum -- title [artist, album]'', where most fields are only |
| 464 | displayed if available. Could also be rendered as ``filename'' or ``tracknum -- |
| 465 | title [artist]''. |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 466 | |
Nils Wallménius | 12eb058 | 2008-03-23 22:07:09 +0000 | [diff] [blame] | 467 | %\opt{lcd_bitmap}{ |
Martin Arver | a245e88 | 2006-03-08 15:04:36 +0000 | [diff] [blame] | 468 | % \begin{verbatim} |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 469 | % %s%?it<%?in<%in. |>%it|%fn> |
Alex Parker | 64d4ddf | 2010-06-20 12:58:41 +0000 | [diff] [blame] | 470 | % %s%?ia<%ia|%?d2<%d(2)|(root)>> |
| 471 | % %s%?id<%id|%?d1<%d(1)|(root)>> %?iy<(%iy)|> |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 472 | % |
| 473 | % %al%pc/%pt%ar[%pp:%pe] |
| 474 | % %fbkBit %?fv<avg|> %?iv<(id3v%iv)|(no id3)> |
| 475 | % %pb |
| 476 | % %pm |
| 477 | % % \end{verbatim} |
| 478 | %} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 479 | |
Marc Guay | 85eec85 | 2008-06-24 05:16:23 +0000 | [diff] [blame] | 480 | \section{\label{ref:manage_settings}Managing Rockbox Settings} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 481 | |
Alexander Levin | 15c850c | 2010-01-22 22:54:05 +0000 | [diff] [blame] | 482 | \subsection{Introduction to \fname{.cfg} Files} |
Marianne Arnold | b24f5ce | 2008-01-17 19:45:22 +0000 | [diff] [blame] | 483 | Rockbox allows users to store and load multiple settings through the use of |
| 484 | configuration files. A configuration file is simply a text file with the |
| 485 | extension \fname{.cfg}. |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 486 | |
Marianne Arnold | a352c62 | 2007-05-19 19:03:39 +0000 | [diff] [blame] | 487 | A configuration file may reside anywhere on the disk. Multiple |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 488 | configuration files are permitted. So, for example, you could have |
| 489 | a \fname{car.cfg} file for the settings that you use while playing your |
| 490 | jukebox in your car, and a \fname{headphones.cfg} file to store the |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 491 | settings that you use while listening to your \dap{} through headphones. |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 492 | |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 493 | See \reference{ref:cfg_specs} below for an explanation of the format |
Marianne Arnold | b24f5ce | 2008-01-17 19:45:22 +0000 | [diff] [blame] | 494 | for configuration files. See \reference{ref:manage_settings_menu} for an |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 495 | explanation of how to create, edit and load configuration files. |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 496 | |
Alexander Levin | 15c850c | 2010-01-22 22:54:05 +0000 | [diff] [blame] | 497 | \subsection{\label{ref:cfg_specs}Specifications for \fname{.cfg} Files} |
Michael DiFebbo | 0623841 | 2006-08-12 15:56:33 +0000 | [diff] [blame] | 498 | |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 499 | The Rockbox configuration file is a plain text file, so once you use the |
Nils Wallménius | b659c0c | 2008-03-22 15:26:45 +0000 | [diff] [blame] | 500 | \setting{Save .cfg file} option to create the file, you can edit the file on |
Marianne Arnold | b24f5ce | 2008-01-17 19:45:22 +0000 | [diff] [blame] | 501 | your computer using any text editor program. See |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 502 | Appendix \reference{ref:config_file_options} for available settings. Configuration |
Marianne Arnold | b24f5ce | 2008-01-17 19:45:22 +0000 | [diff] [blame] | 503 | files use the following formatting rules: % |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 504 | |
| 505 | \begin{enumerate} |
| 506 | \item Each setting must be on a separate line. |
| 507 | \item Each line has the format ``setting: value''. |
| 508 | \item Values must be within the ranges specified in this manual for each |
| 509 | setting. |
| 510 | \item Lines starting with \# are ignored. This lets you write comments into |
| 511 | your configuration files. |
| 512 | \end{enumerate} |
| 513 | |
| 514 | Example of a configuration file: |
| 515 | \begin{example} |
Alexander Levin | 005caba | 2009-03-22 12:14:03 +0000 | [diff] [blame] | 516 | volume: 70 |
| 517 | bass: 11 |
| 518 | treble: 12 |
| 519 | balance: 0 |
| 520 | time format: 12hour |
| 521 | volume display: numeric |
| 522 | show files: supported |
| 523 | wps: /.rockbox/car.wps |
| 524 | lang: /.rockbox/afrikaans.lng |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 525 | \end{example} |
| 526 | |
| 527 | \note{As you can see from the example, configuration files do not need to |
| 528 | contain all of the Rockbox options. You can create configuration files |
| 529 | that change only certain settings. So, for example, supppose you |
Martin Arver | 56b339e | 2006-08-27 20:44:23 +0000 | [diff] [blame] | 530 | typically use the \dap{} at one volume in the car, and another when using |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 531 | headphones. Further, suppose you like to use an inverse LCD when you are |
| 532 | in the car, and a regular LCD setting when you are using headphones. You |
| 533 | could create configuration files that control only the volume and LCD |
| 534 | settings. Create a few different files with different settings, give |
| 535 | each file a different name (such as \fname{car.cfg}, |
| 536 | \fname{headphones.cfg}, etc.), and you can then use the \setting{Browse .cfg |
Alex Parker | 5174341 | 2009-08-25 21:51:55 +0000 | [diff] [blame] | 537 | files} option to quickly change settings.\\} |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 538 | |
| 539 | A special case configuration file can be used to force a particular setting |
| 540 | or settings every time Rockbox starts up (e.g. to set the volume to a safe |
| 541 | level). Format a new configuration file as above with the required setting(s) |
| 542 | and save it into the \fname{/.rockbox} directory with the filename |
| 543 | \fname{fixed.cfg}. |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 544 | |
| 545 | \subsection{\label{ref:manage_settings_menu}The \setting{Manage Settings} |
| 546 | menu} The \setting{Manage Settings} menu can be found in the \setting{Main |
Martin Arver | 56b339e | 2006-08-27 20:44:23 +0000 | [diff] [blame] | 547 | Menu}. The \setting{Manage Settings} menu allows you to save and load |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 548 | \fname{.cfg} files. |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 549 | |
| 550 | \begin{description} |
Michael DiFebbo | 0623841 | 2006-08-12 15:56:33 +0000 | [diff] [blame] | 551 | |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 552 | \item [Browse .cfg Files]Opens the \setting{File Browser} in the |
| 553 | \fname{/.rockbox} directory and displays all \fname{.cfg} (configuration) |
| 554 | files. Selecting a \fname{.cfg} file will cause Rockbox to load the settings |
Marianne Arnold | 8c54767 | 2010-07-04 22:33:37 +0000 | [diff] [blame] | 555 | contained in that file. Pressing \ActionStdCancel{} will exit back to the |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 556 | \setting{Manage Settings} menu. See the \setting{Write .cfg files} option on |
| 557 | the \setting{Manage Settings} menu for details of how to save and edit a |
Martin Arver | 56b339e | 2006-08-27 20:44:23 +0000 | [diff] [blame] | 558 | configuration file. |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 559 | |
Marc Guay | 162a8f2 | 2008-06-28 16:10:02 +0000 | [diff] [blame] | 560 | \item [Reset Settings]This wipes the saved settings |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 561 | in the \dap{} and resets all settings to their default values. |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 562 | |
Szymon Dziok | f7253e3 | 2010-05-24 19:24:38 +0000 | [diff] [blame] | 563 | \opt{IRIVER_H100_PAD,IRIVER_H300_PAD,IAUDIO_X5_PAD,SANSA_E200_PAD,SANSA_C200_PAD% |
| 564 | ,PBELL_VIBE500_PAD}{ |
Marianne Arnold | 56b3f92 | 2008-01-20 16:33:12 +0000 | [diff] [blame] | 565 | \note{You can also reset all settings to their default |
Marc Guay | 162a8f2 | 2008-06-28 16:10:02 +0000 | [diff] [blame] | 566 | values by turning off the \dap, turning it back on, and holding the |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 567 | \ButtonRec{} button immediately after the \dap{} turns on.} |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 568 | } |
Marc Guay | 162a8f2 | 2008-06-28 16:10:02 +0000 | [diff] [blame] | 569 | \opt{IRIVER_H10_PAD}{\note{You can also reset all settings to |
Marianne Arnold | 56b3f92 | 2008-01-20 16:33:12 +0000 | [diff] [blame] | 570 | their default values by turning off the \dap, and turning it back on |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 571 | with the \ButtonHold{} button on.} |
Marcoen Hirschberg | 1e51477 | 2007-04-27 19:38:16 +0000 | [diff] [blame] | 572 | } |
Marc Guay | 162a8f2 | 2008-06-28 16:10:02 +0000 | [diff] [blame] | 573 | \opt{IPOD_4G_PAD}{\note{You can also reset all settings to their default |
| 574 | values by turning off the \dap, turning it back on, and activating the |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 575 | \ButtonHold{} button immediately after the backlight comes on.} |
Marc Guay | 162a8f2 | 2008-06-28 16:10:02 +0000 | [diff] [blame] | 576 | } |
Marianne Arnold | 56b3f92 | 2008-01-20 16:33:12 +0000 | [diff] [blame] | 577 | \opt{GIGABEAT_PAD}{\note{You can also reset all settings to their default |
| 578 | values by turning off the \dap, turning it back on and pressing the |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 579 | \ButtonA{} button immediately after the \dap{} turns on.} |
Marianne Arnold | b24f5ce | 2008-01-17 19:45:22 +0000 | [diff] [blame] | 580 | } |
| 581 | |
Marc Guay | 85eec85 | 2008-06-24 05:16:23 +0000 | [diff] [blame] | 582 | \item [Save .cfg File]This option writes a \fname{.cfg} file to |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 583 | your \daps{} disk. The configuration file has the \fname{.cfg} |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 584 | extension and is used to store all of the user settings that are described |
| 585 | throughout this manual. |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 586 | |
Marc Guay | 85eec85 | 2008-06-24 05:16:23 +0000 | [diff] [blame] | 587 | Hint: Use the \setting{Save .cfg File} feature (\setting{Main Menu |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 588 | $\rightarrow$ Manage Settings}) to save the current settings, then |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 589 | use a text editor to customize the settings file. See Appendix |
| 590 | \reference{ref:config_file_options} for the full reference of available |
| 591 | options. |
Dominik Riebeling | d3bf94f | 2008-03-11 18:43:56 +0000 | [diff] [blame] | 592 | |
Marc Guay | 85eec85 | 2008-06-24 05:16:23 +0000 | [diff] [blame] | 593 | \item [Save Sound Settings]This option writes a \fname{.cfg} file to |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 594 | your \daps{} disk. The configuration file has the \fname{.cfg} |
Dominik Riebeling | d3bf94f | 2008-03-11 18:43:56 +0000 | [diff] [blame] | 595 | extension and is used to store all of the sound related settings. |
| 596 | |
Marc Guay | 85eec85 | 2008-06-24 05:16:23 +0000 | [diff] [blame] | 597 | \item [Save Theme Settings]This option writes a \fname{.cfg} file to |
Nils Wallménius | 01bd736 | 2009-02-04 14:22:35 +0000 | [diff] [blame] | 598 | your \daps{} disk. The configuration file has the \fname{.cfg} |
Dominik Riebeling | d3bf94f | 2008-03-11 18:43:56 +0000 | [diff] [blame] | 599 | extension and is used to store all of the theme related settings. |
Michael DiFebbo | 0623841 | 2006-08-12 15:56:33 +0000 | [diff] [blame] | 600 | |
Martin Arver | 09c3961 | 2006-08-18 16:57:56 +0000 | [diff] [blame] | 601 | \end{description} |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 602 | |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 603 | \section{\label{ref:FirmwareLoading}Firmware Loading} |
Martin Arver | 96f898e | 2006-03-25 09:22:43 +0000 | [diff] [blame] | 604 | \opt{player,recorder,recorderv2fm,ondio}{ |
Martin Arver | 7bdd03a | 2006-08-27 15:00:50 +0000 | [diff] [blame] | 605 | When your \dap{} powers on, it loads the Archos firmware in ROM, which |
Marianne Arnold | b2f7c61 | 2007-12-14 02:03:58 +0000 | [diff] [blame] | 606 | automatically checks your \daps{} root directory for a file named |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 607 | \firmwarefilename. Note that Archos firmware can only read the first |
Thom Johansen | c479b99 | 2008-02-13 13:32:44 +0000 | [diff] [blame] | 608 | ten characters of each filename in this process, so do not rename your old |
Martin Arver | 47ea906 | 2006-06-07 12:15:46 +0000 | [diff] [blame] | 609 | firmware files with names like \firmwarefilename.\fname{old} and so on, |
Thom Johansen | 10d0344 | 2007-12-13 22:51:27 +0000 | [diff] [blame] | 610 | because it is possible that the \dap{} will load a file other than the one |
Martin Arver | 7bdd03a | 2006-08-27 15:00:50 +0000 | [diff] [blame] | 611 | you intended. |
Martin Arver | d3d3e34 | 2006-03-15 10:56:14 +0000 | [diff] [blame] | 612 | } |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 613 | |
Marc Guay | 85eec85 | 2008-06-24 05:16:23 +0000 | [diff] [blame] | 614 | \subsection{\label{ref:using_rolo}Using ROLO (Rockbox Loader)} |
Dominik Riebeling | ebb8a22 | 2006-04-04 17:48:10 +0000 | [diff] [blame] | 615 | Rockbox is able to load and start another firmware file without rebooting. |
Dominik Riebeling | 2794888 | 2006-07-24 20:53:27 +0000 | [diff] [blame] | 616 | You just ``play'' a file with the extension % |
| 617 | \opt{recorder,recorderv2fm,ondio}{\fname{.ajz}.} % |
| 618 | \opt{player}{\fname{.mod}.} % |
Dominik Riebeling | f498d53 | 2008-12-07 23:00:15 +0000 | [diff] [blame] | 619 | \opt{h100,h300}{\fname{.iriver}.} % |
Dominik Riebeling | 2794888 | 2006-07-24 20:53:27 +0000 | [diff] [blame] | 620 | \opt{ipod}{\fname{.ipod}.} % |
| 621 | \opt{iaudio}{\fname{.iaudio}.} % |
Szymon Dziok | a09152b | 2010-04-15 18:35:41 +0000 | [diff] [blame] | 622 | \opt{sansa,h10,h10_5gb,vibe500}{\fname{.mi4}.} % |
Rafaël Carré | e3c9d6a | 2009-05-22 10:44:15 +0000 | [diff] [blame] | 623 | \opt{sansaAMS}{\fname{.sansa}.} % |
Alex Parker | 5174341 | 2009-08-25 21:51:55 +0000 | [diff] [blame] | 624 | \opt{gigabeatf,gigabeats}{\fname{.gigabeat}.} % |
Dominik Riebeling | 2794888 | 2006-07-24 20:53:27 +0000 | [diff] [blame] | 625 | This can be used to test new firmware versions without deleting your |
Dominik Riebeling | ebb8a22 | 2006-04-04 17:48:10 +0000 | [diff] [blame] | 626 | current version. |
Martin Arver | 8e8207f | 2006-02-11 00:57:17 +0000 | [diff] [blame] | 627 | |
Martin Arver | 30b0e66 | 2006-06-15 11:56:50 +0000 | [diff] [blame] | 628 | \opt{archos}{\input{advanced_topics/archos-flashing.tex}} |
Alexander Levin | b57fe48 | 2009-12-23 20:05:29 +0000 | [diff] [blame] | 629 | |
Andree Buschmann | 10023ad | 2010-03-29 17:58:17 +0000 | [diff] [blame] | 630 | \section{Optimising battery runtime} |
| 631 | Rockbox offers a lot of settings that have high impact on the battery runtime |
| 632 | of your \dap{}. The largest power savings can be achieved through disabling |
| 633 | unneeded hardware components -- for some of those there are settings |
| 634 | available. |
| 635 | \opt{swcodec}{ |
| 636 | Another area of savings is avoiding or reducing CPU boosting |
| 637 | through disabling computing intense features (e.g. sound processing) or |
| 638 | using effective audio codecs. |
| 639 | } The following provides a short overview of the most relevant settings and |
| 640 | rules of thumb. |
| 641 | |
| 642 | \nopt{ondio}{ |
| 643 | \subsection{Display backlight} |
| 644 | The active backlight consumes a lot of power. Therefore choose a setting that |
| 645 | disables the backlight after timeout (for setting \setting{Backlight} see |
| 646 | \reference{ref:Displayoptions}). Avoid to have the backlight enabled all the |
| 647 | time. |
| 648 | } |
| 649 | |
| 650 | \opt{lcd_sleep}{ |
| 651 | \subsection{Display power-off} |
| 652 | Shutting down the display and the display controller saves a reasonable amount |
| 653 | of power. Choose a setting that will put the display to sleep after timeout |
| 654 | (for setting \setting{Sleep} see \reference{ref:Displayoptions}). Avoid to |
| 655 | have the display enabled all the time -- even, if the display is transflective |
| 656 | and is readable without backlight. Depending on your \dap{} it might be |
| 657 | significantly more efficient to re-enable the display and its backlight for a |
| 658 | glimpse a few times per hour than to keep the display enabled. |
| 659 | } |
| 660 | |
| 661 | \opt{accessory_supply}{ |
| 662 | \subsection{Accessory power supply} |
| 663 | As default your \dap{}'s accessory power supply is always enabled to ensure |
| 664 | proper function of connected accessory devices. Disable this power supply, if |
| 665 | -- or as long as -- you do not use any accessory device with your \dap{} while |
| 666 | running Rockbox (see \reference{ref:AccessoryPowerSupply}). |
| 667 | } |
| 668 | |
| 669 | \opt{lineout_poweroff}{ |
| 670 | \subsection{Line Out} |
| 671 | Rockbox allows to switch off the line-out on your \dap{}. If you do not need |
| 672 | the line-out, switch it off (see \reference{ref:LineoutOnOff}). |
| 673 | } |
| 674 | |
| 675 | \opt{spdif_power}{ |
| 676 | \subsection{Optical Output} |
| 677 | Rockbox allows to switch off the S/PDIF output on your \dap{}. If you do not |
| 678 | need this output, switch it off (see \reference{ref:SPDIF_OnOff}). |
| 679 | } |
| 680 | |
| 681 | \opt{disk_storage}{ |
| 682 | \subsection{Anti-Skip Buffer} |
| 683 | Having a large anti-skip buffer tends to use more power, and may reduce your |
| 684 | battery life. It is recommended to always use the lowest possible setting |
| 685 | that allows correct and continuous playback (see \reference{ref:AntiSkipBuf}). |
| 686 | } |
| 687 | |
Andree Buschmann | 2349cf5 | 2010-04-12 06:40:58 +0000 | [diff] [blame] | 688 | \opt{swcodec}{ |
| 689 | \subsection{Replaygain} |
| 690 | Replaygain is a post processing that equalises the playback volume of audio |
| 691 | files to the same perceived loudness. This post processing applies a factor |
| 692 | to each single PCM sample and is therefore consuming additional CPU time. If |
| 693 | you want to achieve some (minor) savings in runtime, switch this feature off |
| 694 | (see \reference{ref:ReplayGain}). |
| 695 | } |
| 696 | |
Andree Buschmann | 10023ad | 2010-03-29 17:58:17 +0000 | [diff] [blame] | 697 | \opt{swcodec,disk_storage,flash_storage}{ |
| 698 | \subsection{Audio format and bitrate} |
| 699 | \opt{swcodec}{ |
| 700 | In general the fastest decoding audio format will be the best in terms of |
| 701 | battery runtime on your \dap{}. An overview of different codec's performance |
| 702 | on different \dap{}s can be found at \wikilink{CodecPerformanceComparison}. |
| 703 | } |
| 704 | |
| 705 | \opt{flash_storage}{ |
| 706 | Your target uses flash that consumes a certain amount of power during access. |
| 707 | The less often the flash needs to be switched on for buffering and the shorter |
| 708 | the buffering duration is, the lower is the overall power consumption. |
| 709 | Therefore the bitrate of the audio files does have an impact on the battery |
| 710 | runtime as well. Lower bitrate audio files will result in longer battery |
| 711 | runtime. |
| 712 | } |
| 713 | \opt{disk_storage}{ |
| 714 | Your target uses a hard disk which consumes a large amount of power while |
| 715 | spinning -- up to several hundred mA. The less often the hard disk needs to |
| 716 | spin up for buffering and the shorter the buffering duration is, the lower is |
| 717 | the power consumption. Therefore the bitrate of the audio files does have an |
| 718 | impact on the battery runtime as well. Lower bitrate audio files will result |
| 719 | in longer battery runtime. |
| 720 | } |
| 721 | |
| 722 | Please do not re-encode any existing audio files from one lossy format to |
| 723 | another based upon the above mentioned. This will reduce the audio quality. |
| 724 | If you have the choice, select the best suiting codec when encoding the |
| 725 | original source material. |
| 726 | } |
| 727 | |
| 728 | \opt{swcodec}{ |
| 729 | \subsection{Sound settings} |
| 730 | In general all kinds of sound processing will need more CPU time and therefore |
| 731 | consume more power. The less sound processing you use, the better it is for |
| 732 | the battery runtime (for options see \reference{ref:configure_rockbox_sound}). |
| 733 | } |