Write about the client language.
This commit is contained in:
mmdolze
+89
-14
@@ -15,7 +15,7 @@ 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
|
||||
These pictograms can be switched on or off, or can change their appearance
|
||||
as seen for volume settings.
|
||||
|
||||
LCDproc comes with icons that are integrated into the alphanumeric display
|
||||
@@ -27,7 +27,7 @@ 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
|
||||
This document aims to specify client language and driver API extensions to
|
||||
address pictograms in a manner not specific to certain drivers.
|
||||
|
||||
.. note::
|
||||
@@ -40,7 +40,87 @@ address pictograms in a manner not specific to certain drivers.
|
||||
Client language
|
||||
===============
|
||||
|
||||
This section should talk about the client language.
|
||||
The LCDproc client language will be extended with two new functions that can
|
||||
be called by a client.
|
||||
|
||||
pictogram_list
|
||||
--------------
|
||||
|
||||
.. code::
|
||||
|
||||
pictogram_list
|
||||
|
||||
If this function is called the server will respond with a list of supported
|
||||
pictograms.
|
||||
|
||||
Clients are required to call this command first to retrieve the list of
|
||||
supported pictograms. If the server does not support the pictogram feature,
|
||||
it will respond with "huh? unknown command". Clients must not use
|
||||
pictogram_set then.
|
||||
|
||||
If the server does support pictograms, it will respond with a list of
|
||||
pictograms that are currently understood by at least one driver.
|
||||
|
||||
This means the list changes accordingly to the loaded drivers and may even
|
||||
be empty if no loaded driver uses pictograms!
|
||||
|
||||
The response will look like:
|
||||
|
||||
.. code::
|
||||
|
||||
pictograms [name:type[:group_id:group_type]]*
|
||||
|
||||
List entries are separated by a space character. Each list entry does consist
|
||||
of 2 or 4 fields, separated by colon:
|
||||
|
||||
Name:
|
||||
The name by which the pictogram is known to the server. It is an US-ASCII
|
||||
string not containing any spaces.
|
||||
Type:
|
||||
The type of the pictogram. This will be the string 'bool' for boolean-type
|
||||
or 'num' for numeric-type pictograms.
|
||||
Group_id:
|
||||
This optional part contains a group identifier. The group_id is a number
|
||||
in the range 1-(2^32-1). It is used by the driver to inform the client
|
||||
that certain pictograms have a relation.
|
||||
Group_type:
|
||||
The group_type must be present if a group_id is set. It describes how
|
||||
pictograms in the same group behave. It will be either the string 'alt'
|
||||
(alternate) for groups in which only one pictogram can be active at any
|
||||
time or 'mul' (multiple) for groups which can have several pictograms
|
||||
active at the same time.
|
||||
|
||||
Client shall process the strings case-insensitive.
|
||||
|
||||
|
||||
pictogram_set
|
||||
-------------
|
||||
|
||||
.. code::
|
||||
|
||||
pictogram_set pictogram_name:value
|
||||
|
||||
By calling this command a single pictogram is changed. The pictogram is
|
||||
referenced by its name and a value, according to the given type. The reserved
|
||||
name 'all' can be used to turn off all pictograms at the same time.
|
||||
|
||||
.. note:: It has not yet been defined if 'all' can be used to turn on all
|
||||
pictograms at the same time.
|
||||
|
||||
For boolean-type pictograms the following values are recognized:
|
||||
|
||||
* String 'on' (case-insensitive) or value 1:
|
||||
|
||||
This will turn the pictogram on.
|
||||
|
||||
* String 'off' (case-insensitive) or value 0:
|
||||
|
||||
This will turn the pictogram off.
|
||||
|
||||
.. note:: Strings are to be used without the quotes.
|
||||
|
||||
For numeric-type pictograms value is a number between 0-1000 (inclusive).
|
||||
The value 0 shall turn the pictogram off.
|
||||
|
||||
|
||||
Driver API
|
||||
@@ -59,15 +139,13 @@ 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::
|
||||
There will be no alternative implementation in LCDd core if a driver does
|
||||
not understand a pictogram (like it is done for icons).
|
||||
|
||||
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().
|
||||
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:
|
||||
@@ -103,9 +181,6 @@ shall be turned off or on.
|
||||
* 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
|
||||
=======================
|
||||
|
||||
Reference in New Issue
Block a user