9 files changed, 158 insertions, 0 deletions

diff --git a/manual/advanced_topics/viewports/colour-conditional.tex b/manual/advanced_topics/viewports/colour-conditional.tex
new file mode 100644
index 0000000000..bcef715263
--- /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 0000000000..e681f45fc8
--- /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 0000000000..c88451724c
--- /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 0000000000..390a043f49
--- /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 0000000000..3b420ce7d5
--- /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 0000000000..9f15b514b2
--- /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 0000000000..fef1488ba7
--- /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 0000000000..bdf0a28eaa
--- /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 0000000000..3126d81a10
--- /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}