153 lines
5.2 KiB
XML
153 lines
5.2 KiB
XML
<?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>
|