mangavalk/lcdproc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add the specification for pictogram extension as Docbook article.

Browse Source
This commit is contained in:
mmdolze
2011-10-24 20:27:06 +00:00
parent 57c0645621
commit 760ea0a21a
1 changed files with 152 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/pictogram-spec.docbook
+152
View File
@@ -0,0 +1,152 @@
<?xml version='1.0'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article>
<title>Pictogram Specification For LCDproc</title>
<articleinfo>
<author>
<firstname>Markus</firstname>
<surname>Dolze</surname>
<email>bsdfan@nurfuerspam.de</email>
</author>
<releaseinfo>Prelimary specification</releaseinfo>
</articleinfo>
<sect1><title>Introduction</title>
<para>In addition to alphanumeric characters represented by segments or
pixels, LCD/VFD displays are often capable to show additional pictograms,
mostly arranged around the alphanumeric display part.</para>
<para>These pictograms can be switched on or off, or by changing their
appearance as seen for volume settings.</para>
<para>LCDproc comes with icons that are integrated into the alphanumeric
display part, but is unaware of pictograms as described above.</para>
<para>One current workaround is to use the output() function to pass values to
a driver that uses these values to set pictograms. The downside is that any
application which wants to make use of these pictograms need to know the
exact type of display driver used and how that drivers handles values to the
output() function.</para>
<para>This document aims to specify client language and driver API
extensions address pictograms in a manner not specific to certain drivers.
</para>
<note><para>The common term for pictograms is indeed icons, but to
distinguish the feature from LCDproc's already existing icon feature the
term <termdef>pictogram</termdef> has been chosen.</para></note>
</sect1>
<sect1><title>Client language</title>
<para>This section should talk about the client language.</para>
</sect1>
<sect1><title>Driver API</title>
<para>The driver API (struct lcd_logical_driver in <filename>lcd.h</filename>)
will be extended with a new function to process pictograms:</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>(*set_pictogram)</function></funcdef>
<paramdef>unsigned int <parameter>pictogramID</parameter></paramdef>
<paramdef>int <parameter>value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The pictogram function. The first parameter will be a pictogram
number (ID) and the second parameter will be its value. The function
will return 0 (zero) if the pictogram is understood by the driver
and -1 (minus one) if it is not supported.
</para>
<note>
<para>Their will be no alternative implementation in LCDd core if a
driver does not understand a pictogram (like it is done for icons).
</para>
<para>This function will never be called with multiple pictogram IDs
combined into one. It will be called for each pictogram to be set /
cleared. If a driver wishes to reduce communication with the
hardware it may implement some kind of cache and write the changes
on a call to flush().</para>
</note>
<para>
The pictogram ID is defined in the file called <filename>
lcd_pictograms.h</filename> as an enumerated type. It will have a
symbolic name prefixed with <termdef>PICT_</termdef>. Drivers MUST
NOT address pictograms by their ID number but only by their symbolic
name (e.g. within a switch statement) as the numbers are subject to
change.
</para>
<para>
There will be two types of pictograms:
<variablelist>
<varlistentry>
<term>
Boolean type pictograms
</term>
<listitem><para>
This type of pictograms can be turned on (visible) or off (not visible).
Valid values are 0 (zero) which means off, or 1 (one) which means on.
</para></listitem>
</varlistentry>
<varlistentry>
<term>
Numeric type pictograms
</term>
<listitem><para>
This type of pictograms will change its appearance
according to the value assigned, e.g. a graph or WLAN
strength indicator. Valid values are within the range
0-1000. A value of 0 (zero) turns the pictogram off.
</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
There will be one reserved pictogram ID (symbolic name e.g.
PICT_ALL) which will be of boolean type and means that all
pictograms the driver supports shall be turned off or on.
</para>
<note>
<para>There are currently several options discussed on the mailing
list, given here for reference:</para>
<itemizedlist>
<listitem><para>
There may be a third level for boolean type pictograms
which does highlight it (e.g. make it more brighter or
use a different color).
</para></listitem>
<listitem><para>
Values for numeric type may be negative. This allows
pictograms to have an opposite direction, e.g. graphs
growing from right-to-left instead of from left-to-right.
</para></listitem>
<listitem><para>
Drivers may define their local set of pictogram ID and
assorted client language names.
</para></listitem>
<listitem><para>
Pictograms may be implemented as widgets. In this case
LCDd core will keep track of its value.
</para></listitem>
<listitem><para>
...
</para></listitem>
</itemizedlist>
</note>
</sect1>
<sect1><title>Internal implementation</title>
<para>This section should talk about processing of client messages, mapping
of pictogram names to pictogram IDs.</para>
</sect1>
</article>