Nyaaori/rockbox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add viewports to the manual. Adapted from FS#9934 by Jonas Häggqvist and FS#10553 by David Kauffmann

Browse source 
git-svn-id: svn://svn.rockbox.org/rockbox/trunk@22756 a1c6a512-1295-4272-9138-f99709370657
This commit is contained in:
Alex Parker 2009-09-20 16:48:45 +00:00
parent 16cb628eb7
commit ab563da175
12 changed files with 286 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/CREDITS
View file

@ -493,6 +493,7 @@ Jason Yu
Aaron DeMille
Tomasz Kowalczyk
Michael Lechner
David Kauffmann
The libmad team
The wavpack team

101
manual/advanced_topics/main.tex
View file

@ -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}

15
manual/advanced_topics/viewports/colour-conditional.tex Normal file
View file

@ -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'.

13
manual/advanced_topics/viewports/colour-uivp-syntax.tex Normal file
View file

@ -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.

26
manual/advanced_topics/viewports/colour-vp-syntax.tex Normal file
View file

@ -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}

15
manual/advanced_topics/viewports/grayscale-conditional.tex Normal file
View file

@ -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'.

14
manual/advanced_topics/viewports/grayscale-uivp-syntax.tex Normal file
View file

@ -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.

27
manual/advanced_topics/viewports/grayscale-vp-syntax.tex Normal file
View file

@ -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}

13
manual/advanced_topics/viewports/mono-conditional.tex Normal file
View file

@ -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.

11
manual/advanced_topics/viewports/mono-uivp-syntax.tex Normal file
View file

@ -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.

24
manual/advanced_topics/viewports/mono-vp-syntax.tex Normal file
View file

@ -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}

39
manual/appendix/wps_tags.tex
View file

@ -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}\\