Replace the Docbook version of pictogram spec with one using reStructuredText.
The idea was to write on Docbook to be able to copy and paste the spec into the Developer's Guide. However, writing a quickly changing document in Docbook turned out to be complicated. RST is faster to update and can be converted into nice HTML using docutils.
This commit is contained in:
mmdolze
@@ -1,243 +0,0 @@
|
||||
<?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>
|
||||
There are two language commands that can be called by the client:
|
||||
pictograms_get and pictogram_set.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<command>pictograms_get</command>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>This command may be called by a client to get a list of
|
||||
available pictograms. If pictograms are not support by the
|
||||
particular version of LCDd, it will respond with an error
|
||||
message (huh? unknown command).</para>
|
||||
|
||||
<note>
|
||||
<para>Clients should either check the version number returned as
|
||||
response to the 'hello' command or the response to
|
||||
'pictograms_get' to check if LCDd supports pictograms before
|
||||
calling 'pictogram_set' (see below).</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
The response will be a string in the format:
|
||||
</para>
|
||||
<para>
|
||||
<computeroutput>pictograms <replaceable>pictogram list</replaceable>...</computeroutput>
|
||||
</para>
|
||||
<para>
|
||||
The pictogram list will be a sequence of pictogram
|
||||
definitions separated by a space character. Each pictogram
|
||||
definition consists of up to four fields separated by a colon.
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<computeroutput><replaceable>Name</replaceable></computeroutput>
|
||||
</term>
|
||||
<listitem><para>
|
||||
The text representation of the pictogram name.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<computeroutput><replaceable>Type</replaceable></computeroutput>
|
||||
</term>
|
||||
<listitem><para>
|
||||
The type of the pictogram: 'n' for numerical pictograms
|
||||
and 'b' for boolean type pictograms.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<computeroutput><replaceable>Group ID</replaceable></computeroutput>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>The Group ID is optional and if present is a number greater than zero
|
||||
that models the driver's idea of a several pictograms that form a group. This
|
||||
may e.g. be used for media source pictograms.</para>
|
||||
<note>
|
||||
<para>The group ID is only informational for the client and is not used
|
||||
within LCDd. The driver however may make use of groups internally.</para>
|
||||
</note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<computeroutput><replaceable>Group type</replaceable></computeroutput>
|
||||
</term>
|
||||
<listitem><para>
|
||||
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<command>pictogram_set
|
||||
<option><replaceable>pictogram</replaceable>:<replaceable>value</replaceable></option>
|
||||
</command>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
</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>
|
||||
@@ -0,0 +1,114 @@
|
||||
===================================
|
||||
Pictogram Specification For LCDproc
|
||||
===================================
|
||||
|
||||
:Author: Markus Dolze
|
||||
:Contact: <bsdfan@nurfuerspam.de>
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
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.
|
||||
|
||||
These pictograms can be switched on or off, or by changing their appearance
|
||||
as seen for volume settings.
|
||||
|
||||
LCDproc comes with icons that are integrated into the alphanumeric display
|
||||
part, but is unaware of pictograms as described above.
|
||||
|
||||
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.
|
||||
|
||||
This document aims to specify client language and driver API extensions
|
||||
address pictograms in a manner not specific to certain drivers.
|
||||
|
||||
.. note::
|
||||
|
||||
The common term for pictograms is indeed icons, but to distinguish the
|
||||
feature from LCDproc's already existing icon feature the term
|
||||
[Definition: pictogram] has been chosen.
|
||||
|
||||
|
||||
Client language
|
||||
===============
|
||||
|
||||
This section should talk about the client language.
|
||||
|
||||
|
||||
Driver API
|
||||
==========
|
||||
|
||||
The driver API (struct lcd_logical_driver in lcd.h) will be extended with a
|
||||
new function to process pictograms:
|
||||
|
||||
.. code:: c
|
||||
|
||||
int (*set_pictogram)(unsigned int pictogramID, int value);
|
||||
|
||||
|
||||
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.
|
||||
|
||||
.. note::
|
||||
|
||||
Their will be no alternative implementation in LCDd core if a driver does
|
||||
not understand a pictogram (like it is done for icons).
|
||||
|
||||
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().
|
||||
|
||||
The pictogram ID is defined in the file called lcd_pictograms.h as an
|
||||
enumerated type. It will have a symbolic name prefixed with [Definition:
|
||||
PICT\_]. 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.
|
||||
|
||||
There will be two types of pictograms:
|
||||
|
||||
Boolean type pictograms
|
||||
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.
|
||||
|
||||
Numeric type pictograms
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
.. note:: There are currently several options discussed on the mailing list,
|
||||
given here for reference:
|
||||
|
||||
* 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).
|
||||
|
||||
* 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.
|
||||
|
||||
* Drivers may define their local set of pictogram ID and assorted client
|
||||
language names.
|
||||
|
||||
* Pictograms may be implemented as widgets. In this case LCDd core will
|
||||
keep track of its value.
|
||||
|
||||
|
||||
Internal implementation
|
||||
=======================
|
||||
|
||||
This section should talk about processing of client messages, mapping of
|
||||
pictogram names to pictogram IDs.
|
||||
Reference in New Issue
Block a user