From e8b3b61d0380c2e600c45be3bc9217a074e42cc3 Mon Sep 17 00:00:00 2001 From: alex Date: Sun, 20 Sep 2009 16:48:45 +0000 Subject: [PATCH] =?utf8?q?Add=20viewports=20to=20the=20manual.=20=20Adapte?= =?utf8?q?d=20from=20FS#9934=20by=20Jonas=20H=C3=A4ggqvist=20and=20FS#1055?= =?utf8?q?3=20by=20David=20Kauffmann?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit git-svn-id: svn://svn.rockbox.org/rockbox/trunk@22756 a1c6a512-1295-4272-9138-f99709370657 --- docs/CREDITS | 1 + manual/advanced_topics/main.tex | 101 ++++++++++++++++++++- .../viewports/colour-conditional.tex | 15 +++ .../viewports/colour-uivp-syntax.tex | 13 +++ .../advanced_topics/viewports/colour-vp-syntax.tex | 26 ++++++ .../viewports/grayscale-conditional.tex | 15 +++ .../viewports/grayscale-uivp-syntax.tex | 14 +++ .../viewports/grayscale-vp-syntax.tex | 27 ++++++ .../advanced_topics/viewports/mono-conditional.tex | 13 +++ .../advanced_topics/viewports/mono-uivp-syntax.tex | 11 +++ .../advanced_topics/viewports/mono-vp-syntax.tex | 24 +++++ manual/appendix/wps_tags.tex | 39 ++++++-- 12 files changed, 286 insertions(+), 13 deletions(-) create mode 100644 manual/advanced_topics/viewports/colour-conditional.tex create mode 100644 manual/advanced_topics/viewports/colour-uivp-syntax.tex create mode 100644 manual/advanced_topics/viewports/colour-vp-syntax.tex create mode 100644 manual/advanced_topics/viewports/grayscale-conditional.tex create mode 100644 manual/advanced_topics/viewports/grayscale-uivp-syntax.tex create mode 100644 manual/advanced_topics/viewports/grayscale-vp-syntax.tex create mode 100644 manual/advanced_topics/viewports/mono-conditional.tex create mode 100644 manual/advanced_topics/viewports/mono-uivp-syntax.tex create mode 100644 manual/advanced_topics/viewports/mono-vp-syntax.tex diff --git a/docs/CREDITS b/docs/CREDITS index 906677824..c8b61f8ed 100644 --- a/docs/CREDITS +++ b/docs/CREDITS @@ -493,6 +493,7 @@ Jason Yu Aaron DeMille Tomasz Kowalczyk Michael Lechner +David Kauffmann The libmad team The wavpack team diff --git a/manual/advanced_topics/main.tex b/manual/advanced_topics/main.tex index f95692267..53bb984f2 100644 --- a/manual/advanced_topics/main.tex +++ b/manual/advanced_topics/main.tex @@ -132,6 +132,42 @@ file find the instructions on the Rockbox website: the \fname{/.rockbox/backdrops} directory. }% +\nopt{lcd_charcell}{ + \subsection{UI Viewport} + By default, the UI is drawn on the whole screen. This can be changed so that + the UI is confined to a specific area of the screen, by use of a UI + viewport. This is done by adding the following line to the + \fname{.cfg} file for a theme:\\* + + \nopt{lcd_non-mono}{\config{ui viewport: X,Y,[width],[height],[font]}} + \nopt{lcd_color}{\opt{lcd_non-mono}{ + \config{ui viewport: X,Y,[width],[height],[font],[fgshade],[bgshade]}}} + \opt{lcd_color}{ + \config{ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]}} + \\* + + \opt{HAVE_REMOTE_LCD}{ + The dimensions of the menu that is displayed on the remote control of your + \dap\ can be set in the same way. The line to be added to the theme + \fname{.cfg} is the following:\\* + + \nopt{lcd_non-mono}{\config{remote ui viewport: X,Y,[width],[height],[font]}} + \nopt{lcd_color}{\opt{lcd_non-mono}{ + \config{remote ui viewport: X,Y,[width],[height],[font],[fgshade],[bgshade]}}} + \opt{lcd_color}{ + \config{remote ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]}} + \\* + } + + Only the first two parameters \emph{have} to be specified, the others can + be omitted using '-' as a placeholder. The syntax is very similar to WPS + viewports (see \reference{ref:Viewports}). Briefly: + + \nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-uivp-syntax.tex}} + \nopt{lcd_color}{\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-uivp-syntax.tex}}} + \opt{lcd_color}{\input{advanced_topics/viewports/colour-uivp-syntax.tex}} +} + \section{\label{ref:ConfiguringtheWPS}Configuring the WPS} \subsection{WPS -- General Info} @@ -171,11 +207,6 @@ all the tags that are available. \begin{itemize} \item All characters not preceded by \% are displayed as typed. \item Lines beginning with \# are comments and will be ignored. -\item Maximum file size used is - \opt{lcd_bitmap}{1600} - \opt{player}{400} bytes. - If you have a bigger WPS file, only the first part of it will be - loaded and used. \end{itemize} \note{Keep in mind that your \dap{} resolution is \genericimg{} (with @@ -184,6 +215,66 @@ all the tags that are available. \opt{HAVE_REMOTE_LCD}{The resolution of the remote is \opt{h100,h300}{128x64x1}\opt{x5,m5}{128x96x2} pixels.}} +\nopt{lcd_charcell}{ +\subsubsection{\label{ref:Viewports}Viewports} + +By default, a viewport filling the whole screen contains all the elements +defined in the \fname(.wps) file. The +\opt{lcd_non-mono}{elements in this viewport are displayed + with the same background/foreground + \opt{lcd_color}{colours}\nopt{lcd_color}{shades} and the} +text is rendered in the +same font as in the main menu. To change this behaviour a custom viewport can +be defined. A viewport is a rectangular window on the screen% +\opt{lcd_non-mono}{ with its own foreground/background +\opt{lcd_color}{colours}\nopt{lcd_color}{shades}}. +This window also has variable dimensions. To +define a viewport a line starting \config{{\%V{\textbar}\dots}} has to be +present in the \fname{.wps} file. The full syntax will be explained later in +this section. All elements placed before the +line defining a viewport are displayed in the default viewport. Elements +defined after a viewport declaration are drawn within that viewport. +\opt{lcd_bitmap}{Loading images (see Appendix \reference{ref:wps_images}) + should be done within the default viewport.} +A viewport ends either with the end of the file, or with the next viewport +declaration line. Viewports sharing the same +coordinates and dimensions cannot be displayed at the same time. Viewports +cannot be layered \emph{transparently} over one another. Subsequent viewports +will be drawn over any other viewports already drawn onto that +area of the screen. + +\nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-vp-syntax.tex}} +\nopt{lcd_color}{\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-vp-syntax.tex}}} +\opt{lcd_color}{\input{advanced_topics/viewports/colour-vp-syntax.tex}} + + +\subsubsection{Conditional Viewports} + +Any viewport can be displayed either permanently or conditionally. +Defining a viewport as \config{{\%V{\textbar}\dots}} +will display it permanently. + +\begin{itemize} +\item {\config{\%Vl{\textbar}'identifier'{\textbar}\dots{\textbar}}} +This tag preloads a viewport for later display. 'identifier' is a single +lowercase letter (a-z) and the '\dots' parameters use the same logic as +the \config{\%V} tag explained above. +\item {\config{\%Vd'identifier'}} Display the 'identifier' viewport. +\end{itemize} + +Viewports can share identifiers so that you can display multiple viewports +with one \%Vd line. + +\nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-conditional.tex}} +\nopt{lcd_color}{% + \opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-conditional.tex}}} +\opt{lcd_color}{\input{advanced_topics/viewports/colour-conditional.tex}} +\\* + +\note{The tag to display conditional viewports must come before the tag to +preload the viewport in the \fname{.wps} file.} +} + \subsubsection{Conditional Tags} \begin{description} diff --git a/manual/advanced_topics/viewports/colour-conditional.tex b/manual/advanced_topics/viewports/colour-conditional.tex new file mode 100644 index 000000000..bcef71526 --- /dev/null +++ b/manual/advanced_topics/viewports/colour-conditional.tex @@ -0,0 +1,15 @@ +\begin{example} + %?C<%Vda|%Vdb> + %Vl|a|10|10|50|50|-|-|-| + %Cl|0|0|50|50| + %C + %Vl|a|0|70|70|14|1|-|-| + %s%acThere you have it: Album art. + %Vl|b|20|14|50|14|1|ff0000|ffffff| + %t1%acWarning:;%t.1 + %Vl|b|20|30|50|50|1|000000|ffffff| + %sNo album art found + %scheck your filenames. +\end{example} +This example checks for album art. Album art will be displayed in viewport 'a', if +it is found. Otherwise a red flashing warning will be displayed in viewport 'b'. diff --git a/manual/advanced_topics/viewports/colour-uivp-syntax.tex b/manual/advanced_topics/viewports/colour-uivp-syntax.tex new file mode 100644 index 000000000..e681f45fc --- /dev/null +++ b/manual/advanced_topics/viewports/colour-uivp-syntax.tex @@ -0,0 +1,13 @@ + \begin{itemize} + \item 'fgcolour' and 'bgcolour' are 6-digit RGB888 colours - e.g. FF00FF. + \item 'font' is a number - '0' is the built-in system font, '1' is the + user-selected font. + \end{itemize} + +\begin{example} + \config{ui viewport: 15,20,100,150,-,-,-} +\end{example} +This displays the menu starting at 15px from the left of the screen and 20px +from the top of the screen. It is 100px wide and 150px high. +The font and the foreground/background colours are defined in the theme +\fname{.cfg} file or in the \setting{Theme Settings} menu. diff --git a/manual/advanced_topics/viewports/colour-vp-syntax.tex b/manual/advanced_topics/viewports/colour-vp-syntax.tex new file mode 100644 index 000000000..c88451724 --- /dev/null +++ b/manual/advanced_topics/viewports/colour-vp-syntax.tex @@ -0,0 +1,26 @@ +\subsubsection{Viewport Declaration Syntax} + +{\config{\%V}}{\textbar}x{\textbar}y{\textbar}[width]{\textbar}[height]{\textbar}[font]{\textbar}[fgcolour]{\textbar}[bgcolour]{\textbar}% + + \begin{itemize} + \item 'fgcolour' and 'bgcolour' are 6-digit RGB888 colours - e.g. FF00FF. + \item 'font' is a number - '0' is the built-in system font, '1' is the + user-selected font. + \item Only the coordinates \emph{have} to be specified. Leaving the other + definitions blank will set them to their default values. + \note{The correct number of {\textbar}s with hyphens in blank fields + are still needed in any case.} + \end{itemize} + +\begin{example} + %V|12|20|-|-|1|-|-| + %sThis viewport is displayed permanently. It starts 12px from the left and + %s20px from the top of the screen, and fills the rest of the screen from + %sthat point. The lines will scroll if this text does not fit in the viewport. + %sThe user font is used, as are the default foreground/background colours. +\end{example} +\begin{rbtabular}{.75\textwidth}{XX}{Viewport definition & Default value}{}{} + width/height & remaining part of screen \\ + font & user defined \\ + forground/background colours & defined by theme \\ +\end{rbtabular} \ No newline at end of file diff --git a/manual/advanced_topics/viewports/grayscale-conditional.tex b/manual/advanced_topics/viewports/grayscale-conditional.tex new file mode 100644 index 000000000..390a043f4 --- /dev/null +++ b/manual/advanced_topics/viewports/grayscale-conditional.tex @@ -0,0 +1,15 @@ +\begin{example} + %?C<%Vda|%Vdb> + %Vl|a|10|10|50|50|-|-|-| + %Cl|0|0|50|50| + %C + %Vl|a|0|70|70|14|1|-|-| + %s%acThere you have it: Album art. + %Vl|b|20|14|50|14|1|2|-| + %t1%acWarning:;%t.1 + %Vl|b|20|30|50|50|1|-|-| + %sNo album art found + %scheck your filenames. +\end{example} +This example checks for album art. Album art will be displayed in viewport 'a', if +it is found. Otherwise a flashing warning will be displayed in viewport 'b'. diff --git a/manual/advanced_topics/viewports/grayscale-uivp-syntax.tex b/manual/advanced_topics/viewports/grayscale-uivp-syntax.tex new file mode 100644 index 000000000..3b420ce7d --- /dev/null +++ b/manual/advanced_topics/viewports/grayscale-uivp-syntax.tex @@ -0,0 +1,14 @@ + \begin{itemize} + \item 'fgshade' and bgshade are numbers in the range '0' (= black) to '3' + (= white). + \item 'font' is a number - '0' is the built-in system font, '1' is the + user-selected font. + \end{itemize} + +\begin{example} + \config{ui viewport: 15,20,100,150,-,-,-} +\end{example} +his displays the menu starting at 15px from the left of the screen and 20px +from the top of the screen. It is 100px wide and 150px high. +The font and the foreground/background shades are defined in the theme +\fname{.cfg} file or in the \setting{Theme Settings} menu. diff --git a/manual/advanced_topics/viewports/grayscale-vp-syntax.tex b/manual/advanced_topics/viewports/grayscale-vp-syntax.tex new file mode 100644 index 000000000..9f15b514b --- /dev/null +++ b/manual/advanced_topics/viewports/grayscale-vp-syntax.tex @@ -0,0 +1,27 @@ +\subsubsection{Viewport Declaration Syntax} + +{\config{\%V}}{\textbar}x{\textbar}y{\textbar}[width]{\textbar}[height]{\textbar}[font]{\textbar}[fgshade]{\textbar}[bgshade]{\textbar}% + + \begin{itemize} + \item 'fgshade' and bgshade are numbers in the range '0' (= black) to '3' + (= white). + \item 'font' is a number - '0' is the built-in system font, '1' is the + user-selected font. + \item Only the coordinates \emph{have} to be specified. Leaving the other + definitions blank will set them to their default values. + \note{The correct number of {\textbar}s with hyphens in blank fields + are still needed in any case.} + \end{itemize} + +\begin{example} + %V|12|20|-|-|1|-|-| + %sThis viewport is displayed permanently. It starts 12px from the left and + %s20px from the top of the screen, and fills the rest of the screen from + %sthat point. The lines will scroll if this text does not fit in the viewport. + %sThe user font is used, as are the default foreground/background shades. +\end{example} +\begin{rbtabular}{.75\textwidth}{XX}{Viewport definition & Default value}{}{} + width/height & remaining part of screen \\ + font & user defined \\ + shade & black foreground on white background \\ +\end{rbtabular} diff --git a/manual/advanced_topics/viewports/mono-conditional.tex b/manual/advanced_topics/viewports/mono-conditional.tex new file mode 100644 index 000000000..fef1488ba --- /dev/null +++ b/manual/advanced_topics/viewports/mono-conditional.tex @@ -0,0 +1,13 @@ +\begin{example} + %?mh<%Vda|%Vdb> + %Vl|a|10|10|50|50|-| + %sYou could now show a hold icon using the %%xl and %%xd tags. + %Vl|a|0|70|70|14|1| + %s%acYour DAP is locked. + %Vl|b|20|14|50|14|1| + %t1%acWarning:;%t.1 + %Vl|b|20|30|50|50|0| + %sYou've unlocked your player. +\end{example} +This example checks for hold. Viewport 'a' will be displayed if it is on, +otherwise viewport 'b' will display a flashing warning. diff --git a/manual/advanced_topics/viewports/mono-uivp-syntax.tex b/manual/advanced_topics/viewports/mono-uivp-syntax.tex new file mode 100644 index 000000000..bdf0a28ea --- /dev/null +++ b/manual/advanced_topics/viewports/mono-uivp-syntax.tex @@ -0,0 +1,11 @@ + \begin{itemize} + \item 'font' is a number - '0' is the built-in system font, '1' is the + user-selected font. + \end{itemize} + +\begin{example} + \config{ui viewport: 15,20,100,150,-} +\end{example} +This displays the menu starting at 15px from the left of the screen and 20px +from the top of the screen. It is 100px wide and 150px high. The font is +defined in the theme \fname{.cfg} file or in the \setting{Theme Settings} menu. diff --git a/manual/advanced_topics/viewports/mono-vp-syntax.tex b/manual/advanced_topics/viewports/mono-vp-syntax.tex new file mode 100644 index 000000000..3126d81a1 --- /dev/null +++ b/manual/advanced_topics/viewports/mono-vp-syntax.tex @@ -0,0 +1,24 @@ +\subsubsection{Viewport Declaration Syntax} + +{\config{\%V}}{\textbar}x{\textbar}y{\textbar}[width]{\textbar}[height]{\textbar}[font]{\textbar}% + + \begin{itemize} + \item 'font' is a number - '0' is the built-in system font, '1' is the + user-selected font. + \item Only the coordinates \emph{have} to be specified. Leaving the other + definitions blank will set them to their default values. + \note{The correct number of {\textbar}s with hyphens in blank fields + are still needed in any case.} + \end{itemize} + +\begin{example} + %V|12|20|-|-|1| + %sThis viewport is displayed permanently. It starts 12px from the left and + %s20px from the top of the screen, and fills the rest of the screen from + %sthat point. The lines will scroll if this text does not fit in the viewport. + %sThe user font is used. +\end{example} +\begin{rbtabular}{.75\textwidth}{XX}{Viewport definition & Default value}{}{} + width/height & remaining part of screen \\ + font & user defined \\ +\end{rbtabular} diff --git a/manual/appendix/wps_tags.tex b/manual/appendix/wps_tags.tex index 9be085d01..7c4fd5418 100644 --- a/manual/appendix/wps_tags.tex +++ b/manual/appendix/wps_tags.tex @@ -27,7 +27,33 @@ Remember that this information is not always available, so use the conditionals to show alternate information in preference to assuming. These tags, when written with a capital ``I'' (e.g. \config{\%Ia} or \config{\%Ic}), -produce the information for the next song to be played. +show the information for the next song to be played. + +\nopt{lcd_charcell}{ + \section{Viewports} + \begin{table} + \begin{tagmap}{}{} + \nopt{lcd_non-mono}{~% + \config{\%V{\textbar}x{\textbar}y{\textbar}[width]{\textbar}% + [height]{\textbar}[font]{\textbar}} + & (see section \ref{ref:Viewports})\\} + + \nopt{lcd_color}{\opt{lcd_non-mono}{% + \config{\%V{\textbar}x{\textbar}y{\textbar}[width]{\textbar}% + [height]{\textbar}[font]{\textbar}[fgshade]{\textbar}[bgshade]{\textbar}} + & (see section \ref{ref:Viewports})\\}} + + \opt{lcd_color}{% + \config{\%V{\textbar}x{\textbar}y{\textbar}[width]{\textbar}% + [height]{\textbar}[font]{\textbar}[fgcolour]{\textbar}[bgcolour]{\textbar}} + & (see section \ref{ref:Viewports})\\} + + \config{\%Vd'identifier'} & Display the 'identifier' viewport. E.g. + \config{\%?C{\textless}\%C\%Vda{\textbar}\%Vdb{\textgreater}} + will show viewport 'a' if album art is found, and 'b' if it isn't.\\ + \end{tagmap} + \end{table} +} \section{Power Related Information} \begin{table} @@ -91,9 +117,9 @@ produce the information for the next file to be played. that empties as the time progresses.} \opt{lcd_bitmap}{ & This will replace the entire line with a progress bar. \\ - & You can set the height, position and width of the progressbar % - (in pixels): \config{\%pb{\textbar}height{\textbar}leftpos% - {\textbar}rightpos{\textbar}toppos{\textbar}}} \\ + & You can set the position, width and height of the progressbar % + (in pixels) and load a custom image for it: % + \config{\%pb{\textbar}image.bmp{\textbar}x{\textbar}y{\textbar}width{\textbar}height{\textbar}}} \\ \opt{player}{% \config{\%pf} & Full-line progress bar \& time display\\ }% @@ -231,7 +257,7 @@ Examples: \opt{lcd_bitmap}{ -\section{Images} +\section{\label{ref:wps_images}Images} \begin{table} \begin{tagmap}{}{} \nopt{archos}{% @@ -239,9 +265,6 @@ Examples: & Load and set a backdrop image for the WPS. This image must be exactly the same size as your LCD.\\ }% - \config{\%P{\textbar}filename.bmp{\textbar}} - & Load a Progress Bar image for the WPS. Use \config{\%pb} tag to show the - progress bar\\ \config{\%x{\textbar}n{\textbar}filename{\textbar}x{\textbar}y{\textbar}} & Load and display an image\\ & \config{n}: image ID (a-z and A-Z) for later referencing in \config{\%xd}\\ -- 2.11.4.GIT