1715 lines
53 KiB
Plaintext
1715 lines
53 KiB
Plaintext
<chapter id="language">
|
|
<title>The LCDproc client language</title>
|
|
|
|
<sect1 id="language-intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
The LCDproc clients, for example lcdproc, connect over the network to
|
|
LCDd. In their communication they use a protocol, often refered to as
|
|
the "widget language". In this chapter the widget language will be
|
|
discussed.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="language-open-session">
|
|
<title>Opening a session</title>
|
|
|
|
<para>
|
|
The essence of talking to LCDd is quite simple. First you will need
|
|
to connect to the LCDproc port (usually 13666) on the correct IP
|
|
address (by default localhost). Once you have established the
|
|
connection you should say "hello", to let LCDd know you are a good guy.
|
|
It will respond by telling some LCDproc data, like version and screen
|
|
width and height. Now your session is open and you can start sending
|
|
'real' commands.
|
|
</para>
|
|
|
|
<para>
|
|
LCDd can send a number of strings itself. As a response to your commands,
|
|
it will usually send a "success" string, or a string starting with "huh"
|
|
in case of any error. See further below for other strings sent by LCDd.
|
|
</para>
|
|
|
|
<para>
|
|
You can test all these commands by opening a TCP/IP connection manually,
|
|
like with:
|
|
<screen>telnet localhost 13666</screen>
|
|
This way, you can check how the various commands work. It's in this case
|
|
best to have no other clients. If you do have other clients, you will
|
|
receive "listen" and "ignore" messages that will disturb your typing.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="language-commands">
|
|
<title>Command reference</title>
|
|
<para>
|
|
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
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><link linkend="language-basic">Basic stuff</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="language-screens">Screens and widgets</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="language-menus">Menu stuff</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="language-misc">Miscellaneous</link></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<sect2 id="language-basic">
|
|
<title>Basic stuff</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>hello</command>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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:
|
|
<cmdsynopsis>
|
|
<command>connect</command>
|
|
<arg rep="repeat" choice="plain"><replaceable>parameter</replaceable></arg>
|
|
</cmdsynopsis>
|
|
The client should read all parameters it needs and store their values.
|
|
The following parameters are in use:
|
|
<variablelist><!--<title>hello response parameters</title>-->
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">LCDproc <replaceable>version</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
Indicates the version number of LCDd.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">protocol <replaceable>version</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">wid <replaceable>int</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
Tells the client the width of the attached display device in characters.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">hgt <replaceable>int</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
Tells the client the height of the attached display device in characters.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">cellwid <replaceable>int</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
How many pixels is a character wide (space between character
|
|
cells not included)
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">cellhgt <replaceable>int</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
How many pixels is a character high (space between character
|
|
cells not included)
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">lcd</arg>
|
|
</term>
|
|
<listitem><para>
|
|
This word is NOT followed by a value !
|
|
Hey do we really need this word in the response string ?
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>client_set</command>
|
|
<arg choice="plain">-name <replaceable>name</replaceable></arg>
|
|
<!-- not implemented on the server side
|
|
<arg rep="repeat" choice="plain"><replaceable>options</replaceable></arg>
|
|
-->
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<replaceable>name</replaceable> is the client's name as visible to a user.
|
|
<!-- not implemented on the server side
|
|
</para>
|
|
The following <replaceable>options</replaceable> are accepted:
|
|
<variablelist><title>client_set options</title>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-heartbeat
|
|
<group choice="req">
|
|
<arg choice="plain">on</arg>
|
|
<arg choice="plain">off</arg>
|
|
<arg choice="plain">open</arg>
|
|
</group>
|
|
</arg>
|
|
</term>
|
|
<listitem><para>
|
|
Sets the client's heartbeat setting.
|
|
This setting overrides the screen's setting,
|
|
so you can enable the heartbeat for all your screens at once.
|
|
If <literal>open</literal>, which is the default,
|
|
the screen's setting will be used.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-backlight
|
|
<group choice="req">
|
|
<arg choice="plain">on</arg>
|
|
<arg choice="plain">off</arg>
|
|
<arg choice="plain">toggle</arg>
|
|
<arg choice="plain">open</arg>
|
|
<arg choice="plain">blink</arg>
|
|
<arg choice="plain">flash</arg>
|
|
</group>
|
|
</arg>
|
|
</term>
|
|
<listitem><para>
|
|
Sets the client's backlight setting.
|
|
This setting overrides the screen's setting,
|
|
so you can enable the backlight for all your screens at once.
|
|
If <literal>open</literal>, which is the default,
|
|
the screen's setting will be used.
|
|
See <command>screen_set</command> for details on the backlight modes.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
-->
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect2>
|
|
|
|
<sect2 id="language-screens">
|
|
<title>Screens and widgets</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>screen_add</command>
|
|
<arg choice="plain"><replaceable>new_screen_id</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Adds a screen to be displayed. The screen will be identified
|
|
by the string <replaceable>new_screen_id</replaceable>, which
|
|
is used later when manipulating on the screen.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>screen_del</command>
|
|
<arg choice="plain"><replaceable>screen_id</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Removes the screen identified by <replaceable>screen_id</replaceable>
|
|
from the client's screens.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>screen_set</command>
|
|
<arg choice="plain"><replaceable>screen_id</replaceable></arg>
|
|
<arg choice="plain" rep="repeat"><replaceable>attributes</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets attributes for the given screen. The following attributes
|
|
exist:
|
|
<variablelist><!--<title>screen_set attributes</title>-->
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-name <replaceable>name</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
Sets the screen's name as visible to a user.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-wid <replaceable>int</replaceable></arg>
|
|
</term>
|
|
<term>
|
|
<arg choice="plain">-hgt <replaceable>int</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
Sets the size of the screen in characters. If unset, the full display size is assumed.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-priority <replaceable>pri_class</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
Sets the screen's priority.
|
|
The following priority classes exist:
|
|
<variablelist><!--<title>screen priority classes</title>-->
|
|
<varlistentry>
|
|
<term><literal>hidden</literal></term>
|
|
<listitem><para>
|
|
screen will never be visible
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>background</literal></term>
|
|
<listitem><para>
|
|
only visible when no normal info screens exist
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>info</literal></term>
|
|
<listitem><para>
|
|
normal info screen, default priority
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>foreground</literal></term>
|
|
<listitem><para>
|
|
an active client
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>alert</literal></term>
|
|
<listitem><para>
|
|
screen has an important message for the user
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>input</literal></term>
|
|
<listitem><para>
|
|
the client is doing interactive input
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><replaceable>int</replaceable></term>
|
|
<listitem><para>
|
|
a positive integer that maps to priority classes above
|
|
using the usual logic for priorities:
|
|
the lower the number the higher the priority.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
LCDd will only show screens with the highest priority at that moment.
|
|
So when there are three <literal>info</literal> screens and one
|
|
<literal>foreground</literal> screen,
|
|
only the <literal>foreground</literal> screen will be visible.
|
|
Only <literal>background</literal>, <literal>info</literal> and
|
|
<literal>foreground</literal> screens will rotate;
|
|
higher classes do not rotate because their purpose is not suitable for rotation.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-heartbeat
|
|
<group choice="req">
|
|
<arg choice="plain">on</arg>
|
|
<arg choice="plain">off</arg>
|
|
<arg choice="plain">open</arg>
|
|
</group>
|
|
</arg>
|
|
</term>
|
|
<listitem><para>
|
|
Changes the heartbeat setting for this screen.
|
|
If the to <literal>open</literal>, the default,r
|
|
the client's heartbeat setting will be used.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-backlight
|
|
<group choice="req">
|
|
<arg choice="plain">on</arg>
|
|
<arg choice="plain">off</arg>
|
|
<arg choice="plain">toggle</arg>
|
|
<arg choice="plain">open</arg>
|
|
<arg choice="plain">blink</arg>
|
|
<arg choice="plain">flash</arg>
|
|
</group>
|
|
</arg>
|
|
</term>
|
|
<listitem><para>
|
|
Changes the screen's backlight setting.
|
|
If iset to the default value <literal>open</literal>,
|
|
the state will be determined by the client's setting.
|
|
<literal>blink</literal> is a moderately striking backlight variation,
|
|
<literal>flash</literal> is <emphasis>very</emphasis> strinking.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-duration <replaceable>value</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
A screen will be visible for this amount of time every rotation.
|
|
The <replaceable>value</replaceable> is in eights of a second.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-timeout <replaceable>value</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
After the screen has been visible for a total of this amount of time,
|
|
it will be deleted. The <replaceable>value</replaceable> is in eights of a second.
|
|
Currently the client will not be informed of the deletion (TODO?).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-cursor
|
|
<group choice="req">
|
|
<arg choice="plain">on</arg>
|
|
<arg choice="plain">off</arg>
|
|
<arg choice="plain">under</arg>
|
|
<arg choice="plain">block</arg>
|
|
</group>
|
|
</arg>
|
|
</term>
|
|
<listitem><para>
|
|
Determines the visibility of a cursor.
|
|
If <literal>on</literal>, a cursor will be visible.
|
|
Depending on your hardware, this will be a hardware or software cursor.
|
|
The specified cursor shape (<literal>block</literal> or <literal>under</literal>)
|
|
might not be available in which case an other cursor shape will be used instead.
|
|
Default is <literal>off</literal>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-cursor_x <replaceable>int</replaceable></arg>
|
|
</term>
|
|
<term>
|
|
<arg choice="plain">-cursor_y <replaceable>int</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
Set the cursor's x and y coordinates respectively.
|
|
If not given, the cursor will be set to
|
|
the leftmost (<option>-cursor_x</option>) resp.
|
|
topmost (<option>-cursor_y</option>) position.
|
|
Coordinates are always 1-based.
|
|
So the default top-left corner is denoted by (1,1).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>widget_add</command>
|
|
<arg choice="plain"><replaceable>screen_id</replaceable></arg>
|
|
<arg choice="plain"><replaceable>new_widget_id</replaceable></arg>
|
|
<arg choice="plain"><replaceable>widgettype</replaceable></arg>
|
|
<arg>-in <replaceable>frame_id</replaceable></arg>]
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Adds a widget to the given screen.
|
|
The <replaceable>new_widget_id</replaceable> sets the identifier for this widget.
|
|
The optional <option>-in <replaceable>frame_id</replaceable></option>
|
|
places the widget into the given frame.
|
|
The following widget types exist:
|
|
<variablelist><!--<title>widget types</title>-->
|
|
<varlistentry>
|
|
<term>
|
|
<literal>string</literal>
|
|
</term>
|
|
<listitem><para>
|
|
A simple text.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>title</literal>
|
|
</term>
|
|
<listitem><para>
|
|
A title bar on top of the screen.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>hbar</literal>
|
|
</term>
|
|
<listitem><para>
|
|
A horizontal bar.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>vbar</literal>
|
|
</term>
|
|
<listitem><para>
|
|
A vertical bar.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>icon</literal>
|
|
</term>
|
|
<listitem><para>
|
|
A predefined or client-defined icon.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>scroller</literal>
|
|
</term>
|
|
<listitem><para>
|
|
A variation of the string type that scrolls the text
|
|
horizontally or vertically.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>frame</literal>
|
|
</term>
|
|
<listitem><para>
|
|
A frame with that can contain widgets itself. In fact a
|
|
frame displays an other screen in it.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>num</literal>
|
|
</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>widget_del</command>
|
|
<arg choice="plain"><replaceable>screen_id</replaceable></arg>
|
|
<arg choice="plain"><replaceable>widget_id</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Deletes the given widget from the screen.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>widget_set</command>
|
|
<arg choice="plain"><replaceable>screen_id</replaceable></arg>
|
|
<arg choice="plain"><replaceable>widget_id</replaceable></arg>
|
|
<arg choice="plain"><replaceable>widgettype_specific_parameters</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets parameters for a widget. Because not all widgets are created equal,
|
|
the various widget types require different parameters.
|
|
<variablelist><!--<title>widget_set required parameters per widget type</title>-->
|
|
<varlistentry>
|
|
<term>
|
|
<literal>string</literal>
|
|
</term>
|
|
<listitem>
|
|
<cmdsynopsis>
|
|
<arg choice="plain"><replaceable>x</replaceable></arg>
|
|
<arg choice="plain"><replaceable>y</replaceable></arg>
|
|
<arg choice="plain"><replaceable>text</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<para>
|
|
Displays <replaceable>text</replaceable> at position
|
|
(<replaceable>x</replaceable>,<replaceable>y</replaceable>).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>title</literal>
|
|
</term>
|
|
<listitem>
|
|
<cmdsynopsis>
|
|
<arg choice="plain"><replaceable>text</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<para>
|
|
Uses <replaceable>text</replaceable> as the title to display.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>hbar</literal>
|
|
</term>
|
|
<term>
|
|
<literal>vbar</literal>
|
|
</term>
|
|
<listitem>
|
|
<cmdsynopsis>
|
|
<arg choice="plain"><replaceable>x</replaceable></arg>
|
|
<arg choice="plain"><replaceable>y</replaceable></arg>
|
|
<arg choice="plain"><replaceable>length</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<para>
|
|
Displays a horizontal (<literal>hbar</literal>) resp.
|
|
vertical (<literal>vbar</literal>) starting at
|
|
position (<replaceable>x</replaceable>,<replaceable>y</replaceable>)
|
|
that is <replaceable>length</replaceable> pixels wide resp. high.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>icon</literal>
|
|
</term>
|
|
<listitem>
|
|
<cmdsynopsis>
|
|
<arg choice="plain"><replaceable>x</replaceable></arg>
|
|
<arg choice="plain"><replaceable>y</replaceable></arg>
|
|
<arg choice="plain"><replaceable>iconname</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<para>
|
|
Displays the icon <replaceable>iconname</replaceable> at
|
|
position (<replaceable>x</replaceable>,<replaceable>y</replaceable>).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>scroller</literal>
|
|
</term>
|
|
<listitem>
|
|
<cmdsynopsis>
|
|
<arg choice="plain"><replaceable>left</replaceable></arg>
|
|
<arg choice="plain"><replaceable>top</replaceable></arg>
|
|
<arg choice="plain"><replaceable>right</replaceable></arg>
|
|
<arg choice="plain"><replaceable>bottom</replaceable></arg>
|
|
<arg choice="plain"><replaceable>direction</replaceable></arg>
|
|
<arg choice="plain"><replaceable>speed</replaceable></arg>
|
|
<arg choice="plain"><replaceable>text</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<para>
|
|
Displays a scroller spanning from position
|
|
(<replaceable>left</replaceable>,<replaceable>top</replaceable>)
|
|
to (<replaceable>right</replaceable>,<replaceable>bottom</replaceable>)
|
|
scrolling <replaceable>text</replaceable> in horizontal (<literal>h</literal>),
|
|
vertical (<literal>v</literal>) or marquee (<literal>m</literal>) direction
|
|
at a speed of <replaceable>speed</replaceable>, which is the number of
|
|
movements per rendering stroke (8 times/second).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>frame</literal>
|
|
</term>
|
|
<listitem>
|
|
<cmdsynopsis>
|
|
<arg choice="plain"><replaceable>left</replaceable></arg>
|
|
<arg choice="plain"><replaceable>top</replaceable></arg>
|
|
<arg choice="plain"><replaceable>right</replaceable></arg>
|
|
<arg choice="plain"><replaceable>bottom</replaceable></arg>
|
|
<arg choice="plain"><replaceable>width</replaceable></arg>
|
|
<arg choice="plain"><replaceable>height</replaceable></arg>
|
|
<arg choice="plain"><replaceable>direction</replaceable></arg>
|
|
<arg choice="plain"><replaceable>speed</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<para>
|
|
Sets up a frame spanning from
|
|
(<replaceable>left</replaceable>,<replaceable>top</replaceable>)
|
|
to (<replaceable>right</replaceable>,<replaceable>bottom</replaceable>)
|
|
that is <replaceable>width</replaceable> columns wide and
|
|
<replaceable>height</replaceable> rows high.
|
|
It scrolls in either horizontal (<literal>h</literal>) or
|
|
vertical (<literal>v</literal>) direction at a speed
|
|
of <replaceable>speed</replaceable>, which is the number of
|
|
movements per rendering stroke (8 times/second).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>num</literal>
|
|
</term>
|
|
<listitem>
|
|
<cmdsynopsis>
|
|
<arg choice="plain"><replaceable>x</replaceable></arg>
|
|
<arg choice="plain"><replaceable>int</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<para>
|
|
Displays decimal digit <replaceable>int</replaceable> at
|
|
the horizontal position <replaceable>x</replaceable>,
|
|
which is a normal character x coordinate on the display.
|
|
The special value 10 for <replaceable>int</replaceable>
|
|
displays a colon.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect2>
|
|
|
|
<sect2 id="language-menus">
|
|
<title>Menu stuff</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
TODO: example for normal (static) menu structure.
|
|
</para>
|
|
<para>
|
|
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:
|
|
<programlisting>
|
|
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 "<replaceable>" -maxtext "</replaceable>" -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 ""
|
|
</programlisting>
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>client_add_key</command>
|
|
<group>
|
|
<arg choice="plain">-excl</arg>
|
|
<arg choice="plain">-shared</arg>
|
|
</group>
|
|
<arg choice="plain" rep="repeat"><replaceable>key</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>client_del_key</command>
|
|
<arg choice="plain" rep="repeat"><replaceable>key</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Ends the reservation of the given key(s).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>menu_add_item</command>
|
|
<arg choice="plain"><replaceable>menu_id</replaceable></arg>
|
|
<arg choice="plain"><replaceable>new_item_id</replaceable></arg>
|
|
<arg choice="plain"><replaceable>type</replaceable></arg>
|
|
<arg><replaceable>options</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<title>Note:</title>
|
|
<para>
|
|
Some menu commands (<command>menu_goto</command>) and options
|
|
(<option>-prev</option>, <option>-next</option>) assume that
|
|
<replaceable>menu_ids</replaceable> are <emphasis>unique</emphasis>
|
|
(at least within a clients menu hierarchy).
|
|
</para>
|
|
</note>
|
|
<variablelist><title>menu item types</title>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>action</literal>
|
|
</term>
|
|
<listitem><para>
|
|
This item should trigger an action. It consists of simple text.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>checkbox</literal>
|
|
</term>
|
|
<listitem><para>
|
|
Consists of a text and a status indicator. The
|
|
status can be on (Y), off (N) or gray (o).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>ring</literal>
|
|
</term>
|
|
<listitem><para>
|
|
Consists of a text and a status indicator. The
|
|
status can be one of the strings specified for the
|
|
item.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>slider</literal>
|
|
</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>numeric</literal>
|
|
</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>alpha</literal>
|
|
</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>ip</literal>
|
|
</term>
|
|
<listitem><para>
|
|
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).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>menu</literal>
|
|
</term>
|
|
<listitem><para>
|
|
This is a submenu. It is visible as a text, with an
|
|
appended <literal>></literal>. When selected, the submenu becomes the
|
|
active menu.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>menu_del_item</command>
|
|
<arg choice="plain"><replaceable>menu_id</replaceable></arg>
|
|
<arg choice="plain"><replaceable>item_id</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Removes a menu item <replaceable>item_id</replaceable> from menu
|
|
<replaceable>menu_id</replaceable>. The menu with the special id ""
|
|
(i.e. the empty string) is the client's main menu.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>menu_set_item</command>
|
|
<arg choice="plain"><replaceable>menu_id</replaceable></arg>
|
|
<arg choice="plain"><replaceable>item_id</replaceable></arg>
|
|
<arg choice="plain" rep="repeat"><replaceable>item_specific_options</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets parameters for the menu item(s). Each item type knows different parameters.
|
|
<variablelist><title>options for the various menu items</title>
|
|
<varlistentry>
|
|
<term>for all item types
|
|
</term>
|
|
<listitem><para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-text <replaceable>string</replaceable></arg>
|
|
</term>
|
|
<listitem><para>
|
|
The visible text of the item.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-is_hidden
|
|
<group choice="req">
|
|
<arg choice="plain">false</arg>
|
|
<arg choice="plain">true</arg>
|
|
</group>
|
|
</arg>
|
|
(false)
|
|
</term>
|
|
<listitem><para>
|
|
If the item currently should not appear in a menu.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-next <replaceable>successor_id</replaceable></arg>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets the menu item to show after hitting
|
|
the ENTER key when this item is
|
|
active. This works for
|
|
<emphasis>all</emphasis> menu item types
|
|
<emphasis>except menus</emphasis>
|
|
i.e. also for menu item types without an
|
|
own screen e.g., checkbox, ring and
|
|
action.
|
|
<variablelist>
|
|
<title>Special values</title>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>_close_</literal>
|
|
</term>
|
|
<listitem><para>
|
|
Equivalent to <option>-menu_result close</option>: Close
|
|
the menu.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>_quit_</literal>
|
|
</term>
|
|
<listitem><para>
|
|
Equivalent to <option>-menu_result quit</option>: Quit
|
|
the menu system.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>_none_</literal>
|
|
</term>
|
|
<listitem><para>
|
|
Equivalent to <option>-menu_result none</option>: Keep
|
|
the item open.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-prev <replaceable>predecessor_id</replaceable></arg>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets the menu item to show after hitting
|
|
the ESCAPE key when this Item is
|
|
active. This works for
|
|
<emphasis>all</emphasis> menu item types
|
|
i.e. also for menu item types without an
|
|
own screen e.g., checkbox, ring and
|
|
action.
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<title>Note:</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
This option accepts the same special
|
|
values as the <option>-next</option> option.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>action</literal>
|
|
</term>
|
|
<listitem><para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-menu_result
|
|
<group choice="req">
|
|
<arg choice="plain">none</arg>
|
|
<arg choice="plain">close</arg>
|
|
<arg choice="plain">quit</arg>
|
|
</group>
|
|
</arg>
|
|
(none)
|
|
</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>checkbox</literal>
|
|
</term>
|
|
<listitem><para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-value
|
|
<group choice="req">
|
|
<arg choice="plain">off</arg>
|
|
<arg choice="plain">on</arg>
|
|
<arg choice="plain">gray</arg>
|
|
</group>
|
|
</arg>
|
|
</term>
|
|
<listitem><para>
|
|
Set the value of the item.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-allow_gray
|
|
<group choice="req">
|
|
<arg choice="plain">false</arg>
|
|
<arg choice="plain">true</arg>
|
|
</group>
|
|
</arg>
|
|
(false)
|
|
</term>
|
|
<listitem><para>
|
|
Sets if a grayed checkbox is allowed.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>ring</literal>
|
|
</term>
|
|
<listitem><para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-value <replaceable>int</replaceable></arg> (0)
|
|
</term>
|
|
<listitem><para>
|
|
Sets the index in the stringlist that is currently selected.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-strings <replaceable>string</replaceable></arg> (empty)
|
|
</term>
|
|
<listitem><para>
|
|
This single string should contain the strings that can be selected. They should be tab-separated (\t).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>slider</literal>
|
|
</term>
|
|
<listitem><para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-value <replaceable>int</replaceable></arg> (0)
|
|
</term>
|
|
<listitem><para>
|
|
Sets its current value.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-mintext <replaceable>string</replaceable></arg> ("")
|
|
</term>
|
|
<term>
|
|
<arg choice="plain">-maxtext <replaceable>string</replaceable></arg> ("")
|
|
</term>
|
|
<listitem><para>
|
|
The texts at the left and right side of the slider.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-minvalue <replaceable>int</replaceable></arg> (0)
|
|
</term>
|
|
<term>
|
|
<arg choice="plain">-maxvalue <replaceable>int</replaceable></arg> (100)
|
|
</term>
|
|
<listitem><para>
|
|
The minimum and maximum values of the slider.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-stepsize <replaceable>int</replaceable></arg> (1)
|
|
</term>
|
|
<listitem><para>
|
|
The stepsize of the slider. If you use 0, you can control the movement completely from your client.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>numeric</literal>
|
|
</term>
|
|
<listitem><para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-value <replaceable>int</replaceable></arg> (0)
|
|
</term>
|
|
<listitem><para>
|
|
Sets its current value.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-minvalue <replaceable>int</replaceable></arg> (0)
|
|
</term>
|
|
<term>
|
|
<arg choice="plain">-maxvalue <replaceable>int</replaceable></arg> (100)
|
|
</term>
|
|
<listitem><para>
|
|
The minimum and maximum values that are allowed. If one
|
|
of them is negative, the user will be able to enter
|
|
negative numbers too.
|
|
</para>
|
|
<para>
|
|
TODO: floats!
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>alpha</literal>
|
|
</term>
|
|
<listitem><para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-value <replaceable>string</replaceable></arg> ("")
|
|
</term>
|
|
<listitem><para>
|
|
Sets its current value.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-password_char <replaceable>string</replaceable></arg> ("")
|
|
</term>
|
|
<listitem><para>
|
|
If used, instead of the typed characters, this
|
|
character will be visible.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-minlength <replaceable>int</replaceable></arg> (0)
|
|
</term>
|
|
<term>
|
|
<arg choice="plain">-maxlength <replaceable>int</replaceable></arg> (10)
|
|
</term>
|
|
<listitem><para>
|
|
Sets the minimum and maximum allowed lengths.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-allow_caps
|
|
<group choice="req">
|
|
<arg choice="plain">false</arg>
|
|
<arg choice="plain">true</arg>
|
|
</group>
|
|
</arg>
|
|
(true)
|
|
</term>
|
|
<term>
|
|
<arg choice="plain">-allow_noncaps
|
|
<group choice="req">
|
|
<arg choice="plain">false</arg>
|
|
<arg choice="plain">true</arg>
|
|
</group>
|
|
</arg>
|
|
(false)
|
|
</term>
|
|
<term>
|
|
<arg choice="plain">-allow_numbers
|
|
<group choice="req">
|
|
<arg choice="plain">false</arg>
|
|
<arg choice="plain">true</arg>
|
|
</group>
|
|
</arg>
|
|
(false)
|
|
</term>
|
|
<listitem><para>
|
|
(Dis)allow these groups of characters.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-allowed_extra <replaceable>string</replaceable></arg> ("")
|
|
</term>
|
|
<listitem><para>
|
|
The chars in this string are also allowed.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>ip</literal>
|
|
</term>
|
|
<listitem><para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-value <replaceable>string</replaceable></arg> ("192.168.1.245")
|
|
</term>
|
|
<listitem><para>
|
|
Set the value of the item,
|
|
e.g. "192.168.1.245" (v4) or
|
|
":::ffff:ffff:ffff:ffff:ffff" (v6).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-v6
|
|
<group choice="req">
|
|
<arg choice="plain">false</arg>
|
|
<arg choice="plain">true</arg>
|
|
</group>
|
|
</arg>
|
|
(false)
|
|
</term>
|
|
<listitem><para>
|
|
Changes IP version from default v4.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>menu</literal>
|
|
</term>
|
|
<listitem><para>
|
|
This is a submenu. It is visible as a text, with an
|
|
appended '<literal>></literal>'. When selected, the submenu becomes the
|
|
active menu.
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<arg choice="plain">-parent <replaceable>parentid</replaceable></arg>
|
|
</term>
|
|
<listitem><para> (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. </para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>menu_goto</command>
|
|
<arg choice="plain"><replaceable>menu_id</replaceable></arg>
|
|
<arg><replaceable>parent_id</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Changes current menu to <replaceable>menu_id</replaceable>. Depending on the
|
|
configure option <option>--enable-permissive-menu-goto</option> the
|
|
client may switch to any (if enabled) or his menus only
|
|
(if not enabled).
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable>menu_id</replaceable>
|
|
</term>
|
|
<listitem><para>
|
|
The menu item to go to (any menu type e.g. an
|
|
action or a menu).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><replaceable>parent_id</replaceable>
|
|
</term>
|
|
<listitem><para>
|
|
Resets the parent of <replaceable>menu_id</replaceable>. 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 !
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>menu_set_main</command>
|
|
<arg choice="plain"><replaceable>menu_id</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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 <option>--enable-permissive-menu-goto</option> is used.
|
|
(See <filename>menuscreens.c</filename> for the menu ids of the server menus.)
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable>menu_id</replaceable>
|
|
</term>
|
|
<listitem><para>
|
|
The new main menu, restricted to the client's own
|
|
menus. Special values:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
"" (i.e. the empty string)
|
|
</term>
|
|
<listitem><para>
|
|
The client's main menu.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>_main_</literal>
|
|
</term>
|
|
<listitem><para>
|
|
Resets main to the "real" main menu.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect2>
|
|
|
|
<sect2 id="language-misc">
|
|
<title>Miscellaneous</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>backlight</command>
|
|
<group choice="req">
|
|
<arg choice="plain">on</arg>
|
|
<arg choice="plain">off</arg>
|
|
<arg choice="plain">toggle</arg>
|
|
<arg choice="plain">blink</arg>
|
|
<arg choice="plain">flash</arg>
|
|
</group>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets the client's backlight state.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>output</command>
|
|
<group choice="req">
|
|
<arg choice="plain">on</arg>
|
|
<arg choice="plain">off</arg>
|
|
<arg choice="plain"><replaceable>int</replaceable></arg>
|
|
</group>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sets the general purpose output on some display modules to
|
|
this value. Use <literal>on</literal> to set all outputs to high state,
|
|
and <literal>off</literal> 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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>info</command>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This command provides information about the driver.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>noop</command>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>sleep</command>
|
|
<arg choice="plain"><replaceable>int</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Sleep for the given number of seconds. <replaceable>int</replaceable>
|
|
must be a positive integer in the range from 1 to 60.
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<title>Note:</title>
|
|
<para>
|
|
This command is currently ignored on the server side.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<!-- not yet implemented but might be useful
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>quit</command>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Terminates connection to the server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
-->
|
|
</variablelist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="language-messages">
|
|
<title>LCDd messages</title>
|
|
<para>
|
|
LCDd can send messages back to the client. These messages can be
|
|
directly related to the last command, or generated for some other
|
|
reason. Because messages can be generated at any moment, the client
|
|
should read from the connection at regular intervals. A very simple client
|
|
could simply ignore all received messages. Not reading the messages will
|
|
cause trouble !
|
|
</para>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>success</command>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem><para>
|
|
This is the reponse to a command in case everything went ok.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>huh?</command>
|
|
<arg choice="plain"><replaceable>errorr_description</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem><para>
|
|
This is the reponse to a command in case something has gone wrong.
|
|
The description is not meant to be parsed, it's only meant for
|
|
the programmer of the client. It might be that your command has
|
|
only been partially executed, for example if you try to reserve 3
|
|
keys, and one fails. Your client might need to undo its actions
|
|
completely.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>listen</command>
|
|
<arg choice="plain"><replaceable>screen_id</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>ignore</command>
|
|
<arg choice="plain"><replaceable>screen_id</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem><para>
|
|
The given screen is now visible on the display (listen) or it is
|
|
not visible anymore on the display (ignore).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>key</command>
|
|
<arg choice="plain"><replaceable>key</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem><para>
|
|
This message will be sent if there was a keypress that should be
|
|
delivered to the current client.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<cmdsynopsis>
|
|
<command>menuevent</command>
|
|
<arg choice="plain"><replaceable>event_type</replaceable></arg>
|
|
<arg choice="plain"><replaceable>id</replaceable></arg>
|
|
<arg><replaceable>value</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</term>
|
|
<listitem><para>
|
|
The user did something with a client supplied menu. The type of
|
|
event can be:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>select</literal> (action)
|
|
</term>
|
|
<listitem><para>
|
|
The item was activated.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>update</literal> (checkbox, ring, numeric, alpha)
|
|
</term>
|
|
<listitem><para>
|
|
The item was modified by the user, so LCDd sends an updated
|
|
<replaceable>value</replaceable>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>plus</literal> (slider)
|
|
</term>
|
|
<term>
|
|
<literal>minus</literal> (slider)
|
|
</term>
|
|
<listitem><para>
|
|
The slider was moved to left (<literal>minus</literal>)
|
|
or right (<literal>plus</literal>), so
|
|
LCDd sends an updated <replaceable>value</replaceable>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>enter</literal>
|
|
</term>
|
|
<listitem><para>
|
|
This item has been entered, which means it is currently
|
|
active on the screen. The client could now for example
|
|
update the value of the item. If it is a menu, it may be
|
|
needed to update the values of the items in it too,
|
|
because they may be visible too.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>leave</literal>
|
|
</term>
|
|
<listitem><para>
|
|
This item has been left, so it is currenly not the (main)
|
|
active item anymore.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
Multiple messages may be generated by one action of the user.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
|