Add viewports to the manual. Adapted from FS#9934 by Jonas Häggqvist and FS#10553 by David Kauffmann
git-svn-id: svn://svn.rockbox.org/rockbox/trunk@22756 a1c6a512-1295-4272-9138-f99709370657
diff --git a/docs/CREDITS b/docs/CREDITS
index 9066778..c8b61f8 100644
--- a/docs/CREDITS
+++ b/docs/CREDITS
@@ -493,6 +493,7 @@
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 f956922..53bb984 100644
--- a/manual/advanced_topics/main.tex
+++ b/manual/advanced_topics/main.tex
@@ -132,6 +132,42 @@
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 @@
\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 @@
\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 0000000..bcef715
--- /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 0000000..e681f45
--- /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 0000000..c884517
--- /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 0000000..390a043
--- /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 0000000..3b420ce
--- /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 0000000..9f15b51
--- /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 0000000..fef1488
--- /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 0000000..bdf0a28
--- /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 0000000..3126d81
--- /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 9be085d..7c4fd54 100644
--- a/manual/appendix/wps_tags.tex
+++ b/manual/appendix/wps_tags.tex
@@ -27,7 +27,33 @@
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 @@
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 @@
\opt{lcd_bitmap}{
-\section{Images}
+\section{\label{ref:wps_images}Images}
\begin{table}
\begin{tagmap}{}{}
\nopt{archos}{%
@@ -239,9 +265,6 @@
& 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}\\