diff --git a/docs/pictogram-spec.docbook b/docs/pictogram-spec.docbook deleted file mode 100644 index 0bc1453..0000000 --- a/docs/pictogram-spec.docbook +++ /dev/null @@ -1,243 +0,0 @@ - - -
-Pictogram Specification For LCDproc - - - Markus - Dolze - bsdfan@nurfuerspam.de - -Prelimary specification - - -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. - - -The common term for pictograms is indeed icons, but to -distinguish the feature from LCDproc's already existing icon feature the -term pictogram has been chosen. - - - -Client language - - There are two language commands that can be called by the client: - pictograms_get and pictogram_set. - - - - - - pictograms_get - - - 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). - - - 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). - - - - The response will be a string in the format: - - - pictograms pictogram list... - - - 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. - - - - - Name - - - The text representation of the pictogram name. - - - - - Type - - - The type of the pictogram: 'n' for numerical pictograms - and 'b' for boolean type pictograms. - - - - - Group ID - - - 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. - - The group ID is only informational for the client and is not used - within LCDd. The driver however may make use of groups internally. - - - - - - Group type - - - - - - - - - - - - - pictogram_set - - - - - - - - - - - - -Driver API - -The driver API (struct lcd_logical_driver in lcd.h) -will be extended with a new function to process pictograms: - - - - 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. - - - 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 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. - - - - 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. - - - -
diff --git a/docs/pictogram-spec.rst b/docs/pictogram-spec.rst new file mode 100644 index 0000000..81f2141 --- /dev/null +++ b/docs/pictogram-spec.rst @@ -0,0 +1,114 @@ +=================================== +Pictogram Specification For LCDproc +=================================== + +:Author: Markus Dolze +:Contact: + +.. 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.