In this section all commands and their parameters are listed, along with the responses you can expect. If you need a space or a special char in a string, you should quote the string with double quotes. If you need to use a double quote, escape it with a backslash. The listing is divided into subsections for
hello
Opens the session with the LCDd server program. This command is required before other commands can be issued. The response will be a string in the format:
connect
parameter
...
The client should read all parameters it needs and store their values. The following parameters are in use:
version
Indicates the version number of LCDd.
version
Indicates the widget language version number. This number is only changed when the language of a newer version has become incompatible with the previous version.
int
Tells the client the width of the attached display device in characters.
int
Tells the client the height of the attached display device in characters.
int
How many pixels is a character wide (space between character cells not included)
int
How many pixels is a character high (space between character cells not included)
This word is NOT followed by a value ! Hey do we really need this word in the response string ?
client_set
-name name
Sets attributes for the current client. The current client is the one from the connection that you send this command on, in other words: yourself.
name
is the client's name as visible to a user.
screen_add
new_screen_id
Adds a screen to be displayed. The screen will be identified
by the string new_screen_id
, which
is used later when manipulating on the screen.
screen_del
screen_id
Removes the screen identified by screen_id
from the client's screens.
screen_set
screen_id
attributes
...
Sets attributes for the given screen. The following attributes exist:
name
Sets the screen's name as visible to a user.
int
,
-hgt int
Sets the size of the screen in characters. If unset, the full display size is assumed.
pri_class
Sets the screen's priority. The following priority classes exist:
hidden
The screen will never be visible
background
The screen is only visible when no normal info screens exists
info
normal info screen, default priority
foreground
an active client
alert
The screen has an important message for the user.
input
The client is doing interactive input.
int
a positive integer that maps to priority classes above according to the mapping given in the table below.
range | priority |
---|---|
1 - 64 | foreground |
65 - 192 | info |
193 - ∞ | background |
LCDd will only show screens with the highest priority at that moment.
So when there are three info
screens and one
foreground
screen,
only the foreground
screen will be visible.
Only background
, info
and
foreground
screens will rotate;
higher classes do not rotate because their purpose is not suitable for rotation.
Changes the heartbeat setting for this screen.
If set to open
, the default,
the client's heartbeat setting will be used.
Changes the screen's backlight setting.
If iset to the default value open
,
the state will be determined by the client's setting.
blink
is a moderately striking backlight variation,
flash
is very strinking.
value
A screen will be visible for this amount of time every rotation.
The value
is in eights of a second.
value
After the screen has been visible for a total of this amount of time,
it will be deleted. The value
is in eights of a second.
Currently the client will not be informed of the deletion (TODO?).
Determines the visibility of a cursor.
If on
, a cursor will be visible.
Depending on your hardware, this will be a hardware or software cursor.
The specified cursor shape (block
or under
)
might not be available in which case an other cursor shape will be used instead.
Default is off
.
int
,
-cursor_y int
Set the cursor's x and y coordinates respectively.
If not given, the cursor will be set to
the leftmost (-cursor_x
) resp.
topmost (-cursor_y
) position.
Coordinates are always 1-based.
So the default top-left corner is denoted by (1,1).
widget_add
screen_id
new_widget_id
widgettype
[-in frame_id
]
Adds a widget to the given screen.
The new_widget_id
sets the identifier for this widget.
The optional -in
places the widget into the given frame.
The following widget types exist:
frame_id
string
A simple text.
title
A title bar on top of the screen.
hbar
A horizontal bar.
vbar
A vertical bar.
icon
A predefined or client-defined icon.
scroller
A variation of the string type that scrolls the text horizontally or vertically.
frame
A frame with that can contain widgets itself. In fact a frame displays an other screen in it.
num
A big number. They have a size of 3x4 characters. The special number 10 is a colon, that you can use for a clock. This character is 1x4.
widget_del
screen_id
widget_id
Deletes the given widget from the screen.
widget_set
screen_id
widget_id
widgettype_specific_parameters
Sets parameters for a widget. Because not all widgets are created equal, the various widget types require different parameters.
string
x
y
text
Displays text
at position
(x
,y
).
title
text
Uses text
as the title to display.
hbar
,
vbar
x
y
length
Displays a horizontal (hbar
) resp.
vertical (vbar
) starting at
position (x
,y
)
that is length
pixels wide resp. high.
icon
x
y
iconname
Displays the icon iconname
at
position (x
,y
).
scroller
left
top
right
bottom
direction
speed
text
Displays a scroller spanning from position
(left
,top
)
to (right
,bottom
)
scrolling text
in horizontal (h
),
vertical (v
) or marquee (m
) direction
at a speed of speed
, which is the number of
movements per rendering stroke (8 times/second).
frame
left
top
right
bottom
width
height
direction
speed
Sets up a frame spanning from
(left
,top
)
to (right
,bottom
)
that is width
columns wide and
height
rows high.
It scrolls in either horizontal (h
) or
vertical (v
) direction at a speed
of speed
, which is the number of
movements per rendering stroke (8 times/second).
num
x
int
Displays decimal digit int
at
the horizontal position x
,
which is a normal character x coordinate on the display.
The special value 10 for int
displays a colon.
In this section all commands for creation, modification of menus and for interaction with them are described. Although keys may be used for other tasks they are listed here too.
TODO: example for normal (static) menu structure.
Menus may be even be used for wizards (the user is automatically guided through a number of configuration options) by virtue of the options -next and -prev. Here a complete example:
client_set name Parenttest
# to be entered on escape from test_menu (but overwritten
# for test_{checkbox,ring})
menu_add_item "" ask menu "Leave menus?" -is_hidden true
menu_add_item "ask" ask_yes action "Yes" -next _quit_
menu_add_item "ask" ask_no action "No" -next _close_
menu_add_item "" test menu "Test"
menu_add_item "test" test_action action "Action"
menu_add_item "test" test_checkbox checkbox "Checkbox"
menu_add_item "test" test_ring ring "Ring" -strings "one\ttwo\tthree"
menu_add_item "test" test_slider slider "Slider" -mintext "" -maxtext "
" -value "50"
menu_add_item "test" test_numeric numeric "Numeric" -value "42"
menu_add_item "test" test_alpha alpha "Alpha" -value "abc"
menu_add_item "test" test_ip ip "IP" -v6 false -value "192.168.1.1"
menu_add_item "test" test_menu menu "Menu"
menu_add_item "test_menu" test_menu_action action "Submenu's action"
# no successor for menus. Since test_checkbox and test_ring have their
# own predecessors defined the "ask" rule will not work for them
menu_set_item "" test -prev "ask"
menu_set_item "test" test_action -next "test_checkbox"
menu_set_item "test" test_checkbox -next "test_ring" -prev "test_action"
menu_set_item "test" test_ring -next "test_slider" -prev "test_checkbox"
menu_set_item "test" test_slider -next "test_numeric" -prev "test_ring"
menu_set_item "test" test_numeric -next "test_alpha" -prev "test_slider"
menu_set_item "test" test_alpha -next "test_ip" -prev "test_numeric"
menu_set_item "test" test_ip -next "test_menu" -prev "test_alpha"
menu_set_item "test" test_menu_action -next "_close_"
menu_set_main ""
client_add_key
[ -exclusively | -shared ] key
...
Tells the server that the current client wants to make use of the given key(s). If you reserve the key(s) in shared mode, other clients can still reserve these keys too. If you reserve the key(s) in exclusive mode no other client can reserve them again. Key(s) reserved in shared mode will only be returned when a screen of the current client is active. These keys can be used for interaction with a visible screen (default). Key(s) reserved in exclusive mode will be returned regardless of which screen is active. They can be used to trigger a special feature or to make a screen come to foreground. Note that you cannot reserve a key in exclusive mode when an other client has reserved it in shared mode.
client_del_key
key
...
Ends the reservation of the given key(s).
menu_add_item
menu_id
new_item_id
type
[options
]
Adds a new menu item to a menu. The main menu of a client, will be created automatically as soon as the client adds an item. This main menu has an empty id ("") and the name is identical to the name of the client. The options are described under menu_set_item below.
Some menu commands (menu_goto) and options
(-prev
, -next
) assume that
menu_ids
are unique
(at least within a clients menu hierarchy).
menu item types
action
This item should trigger an action. It consists of simple text.
checkbox
Consists of a text and a status indicator. The status can be on (Y), off (N) or gray (o).
ring
Consists of a text and a status indicator. The status can be one of the strings specified for the item.
slider
Is visible as a text. When selected, a screen comes up that shows a slider. You can set the slider using the cursor keys. When Enter is pressed, the menu returns.
numeric
Allows the user to input an integer value. Is visible as a text. When selected, a screen comes up that shows the current numeric value, that you can edit with the cursor keys and Enter. The number is ended by selecting a 'null' input digit. After that the menu returns.
alpha
Is visible as a text. When selected, a screen comes up that shows the current string value, that you can edit with the cursor keys and Enter. The string is ended by selecting a 'null' input character. After that the menu returns.
ip
Allows the user to input an ip number (v4 or v6). When selected, a screen comes up that shows an ip number that can be edited - digit by digit - via left/right (switch digit) and up/down keys (increase/decrease).
menu
This is a submenu. It is visible as a text, with an
appended >
. When selected, the submenu becomes the
active menu.
menu_del_item
menu_id
item_id
Removes a menu item item_id
from menu
menu_id
. The menu with the special id ""
(i.e. the empty string) is the client's main menu.
menu_set_item
menu_id
item_id
item_specific_options
...
Sets parameters for the menu item(s). Each item type knows different parameters.
options for the various menu items
string
The visible text of the item.
If the item currently should not appear in a menu.
successor_id
Sets the menu item to show after hitting the ENTER key when this item is active. This works for all menu item types except menus i.e. also for menu item types without an own screen e.g., checkbox, ring and action.
Special values
_close_
Equivalent to -menu_result close
: Close
the menu.
_quit_
Equivalent to -menu_result quit
: Quit
the menu system.
_none_
Equivalent to -menu_result none
: Keep
the item open.
predecessor_id
Sets the menu item to show after hitting the ESCAPE key when this Item is active. This works for all menu item types i.e. also for menu item types without an own screen e.g., checkbox, ring and action.
If you define a predecessor for e.g., a checkbox and its parent menu too, the menu's predecessor is ignored in favor of the checkboxes one.
This option accepts the same special
values as the -next
option.
action
Sets what to do with the menu when this action is selected: none: the menu stays as it is; close: the menu closes and returns to a higher level; quit: quits the menu completely so you can foreground your app.
checkbox
Set the value of the item.
Sets if a grayed checkbox is allowed.
ring
int
(0)
Sets the index in the stringlist that is currently selected.
string
(empty)
This single string should contain the strings that can be selected. They should be tab-separated (\t).
slider
int
(0)
Sets its current value.
string
("")
,
-maxtext string
("")
The texts at the left and right side of the slider.
int
(0)
,
-maxvalue int
(100)
The minimum and maximum values of the slider.
int
(1)
The stepsize of the slider. If you use 0, you can control the movement completely from your client.
numeric
int
(0)
Sets its current value.
int
(0)
,
-maxvalue int
(100)
The minimum and maximum values that are allowed. If one of them is negative, the user will be able to enter negative numbers too.
TODO: floats!
alpha
string
("")
Sets its current value.
string
("")
If used, instead of the typed characters, this character will be visible.
int
(0)
,
-maxlength int
(10)
Sets the minimum and maximum allowed lengths.
(Dis)allow these groups of characters.
string
("")
The chars in this string are also allowed.
ip
string
("192.168.1.245")
Set the value of the item, e.g. "192.168.1.245" (v4) or ":::ffff:ffff:ffff:ffff:ffff" (v6).
Changes IP version from default v4.
menu
This is a submenu. It is visible as a text, with an
appended '>
'. When selected, the submenu becomes the
active menu.
parentid
(Re)sets the parent of this menu. Parentid has to be of type menu. This function does not change any menu (neither the old nor the new parent) since this option is normally used with hidden menus. Otherwise use menu_add/del_item. Applying this option is equivalent to second argument of the menu_goto command.
menu_goto
menu_id
[parent_id
]
Changes current menu to menu_id
. Depending on the
configure option --enable-permissive-menu-goto
the
client may switch to any (if enabled) or his menus only
(if not enabled).
menu_id
The menu item to go to (any menu type e.g. an action or a menu).
parent_id
Resets the parent of menu_id
. This
optional parameter can be used to reuse a menu
from different places (for wizards etc.). Use it
with caution: This may lead to a messy menu
structure in particular due to the fact that the
menus are not changed !
menu_set_main
menu_id
Sets the entry point into the menu system. Use this to
make the server menu invisible. Note that you may only set
the menu to your own clients menus unless the configure
option --enable-permissive-menu-goto
is used.
(See menuscreens.c
for the menu ids of the server menus.)
menu_id
The new main menu, restricted to the client's own menus. Special values:
The client's main menu.
_main_
Resets main to the "real" main menu.
backlight
{ on | off | toggle | blink | flash }
Sets the client's backlight state.
output
{ on | off | int
}
Sets the general purpose output on some display modules to
this value. Use on
to set all outputs to high state,
and off
to set all to low state.
The meaning of the integer value depends on your specific device,
usually it is a bit pattern describing the state of each output line.
info
This command provides information about the driver.
noop
This command does nothing and is always successful. Can be useful to be sent at regular intervals to make sure your connection is still alive.
sleep
int
Sleep for the given number of seconds. int
must be a positive integer in the range from 1 to 60.
This command is currently ignored on the server side.