<!--
  Note: While Docbook allows to use block formatted elements like <cmdsynopsis>
  within a term definition, HTML only allows inline formatted elements.
  Therefore <command> and <option> elements are used. Maybe <refentry> should
  be used, but I currently dislike having a separate page for each command.
-->
<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 referred 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. Escaping also works for "\n\r\t", however not all
      widget types or display drivers will handle these characters well.
      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>
	    <command>hello</command>
	  </term>
	  <listitem>
	    <para>
	      Opens the session with the LCDd server program. This command is
	      required before other commands can be issued.
	    </para>
	    <para>
	      The response will be a string in the format:
	    </para>
	    <para>
	      <computeroutput>connect <replaceable>parameter</replaceable>...</computeroutput>
	    </para>
	    <para>
	      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>
		    <computeroutput>LCDproc <replaceable>version</replaceable></computeroutput>
		  </term>
		  <listitem><para>
		      Indicates the version number of LCDd.
		    </para></listitem>
		</varlistentry>
		<varlistentry>
		  <term>
		    <computeroutput>protocol <replaceable>version</replaceable></computeroutput>
		  </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.
		      <note><para>
			Each part of the version number shall be treated as an independent
			numeric value. This means that 0.9 is followed by 0.10.
		      </para></note>
		    </para></listitem>
		</varlistentry>
		<varlistentry>
		  <term>
		    <computeroutput>lcd</computeroutput>
		  </term>
		  <listitem><para>
		      This word introduces the next key / value pairs that
		      describe the display's properties.
		    </para></listitem>
		</varlistentry>
		<varlistentry>
		  <term>
		    <computeroutput>wid <replaceable>int</replaceable></computeroutput>
		  </term>
		  <listitem><para>
		      Tells the client the width of the attached display device in characters.
		    </para></listitem>
		</varlistentry>
		<varlistentry>
		  <term>
		    <computeroutput>hgt <replaceable>int</replaceable></computeroutput>
		  </term>
		  <listitem><para>
		      Tells the client the height of the attached display device in characters.
		    </para></listitem>
		</varlistentry>
		<varlistentry>
		  <term>
		    <computeroutput>cellwid <replaceable>int</replaceable></computeroutput>
		  </term>
		  <listitem><para>
		      How many pixels is a character wide (space between character
		      cells not included)
		    </para></listitem>
		</varlistentry>
		<varlistentry>
		  <term>
		    <computeroutput>cellhgt <replaceable>int</replaceable></computeroutput>
		  </term>
		  <listitem><para>
		      How many pixels is a character high (space between character
		      cells not included)
		    </para></listitem>
		</varlistentry>
	      </variablelist>
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <command>client_set <option>-name <replaceable>name</replaceable></option></command>
	  </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.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="language-screens">
      <title>Screens and widgets</title>

      <variablelist>
	<varlistentry>
	  <term>
	    <command>screen_add <option><replaceable>new_screen_id</replaceable></option></command>
	  </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>
	    <command>screen_del <option><replaceable>screen_id</replaceable></option></command>
	  </term>
	  <listitem>
	    <para>
	      Removes the screen identified by <replaceable>screen_id</replaceable>
	      from the client's screens.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <command>screen_set
	      <option><replaceable>screen_id</replaceable></option>
	      <option><replaceable>attributes</replaceable>...</option>
	    </command>
	  </term>
	  <listitem>
	    <para>
	      Sets attributes for the given screen. The following attributes
	      exist:
	      <variablelist>
		<varlistentry>
		  <term>
		    <option>-name <replaceable>name</replaceable></option>
		  </term>
		  <listitem><para>
		      Sets the screen's name as visible to a user.
		    </para></listitem>
		</varlistentry>
		<varlistentry>
		  <term>
		    <option>-wid <replaceable>int</replaceable></option>
		    <option>-hgt <replaceable>int</replaceable></option>
		  </term>
		  <listitem><para>
		      Sets the size of the screen in characters. If unset, the full display size is assumed.
		    </para></listitem>
		</varlistentry>
		<varlistentry>
		  <term>
		    <option>-priority <replaceable>pri_class</replaceable></option>
		  </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>
			      The screen will never be visible
			    </para></listitem>
		        </varlistentry>
		        <varlistentry>
		          <term><literal>background</literal></term>
			  <listitem><para>
			      The screen is only visible when no normal info screens exists
			    </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>
			      The 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
			      according to the mapping given in the table below.
			    </para>
			    <informaltable frame="all"><tgroup cols="2" colsep="1" rowsep="1">
			      <thead>
			        <row>
				  <entry>range</entry>
				  <entry>priority</entry>
				</row>
			      </thead>
			      <tbody>
			        <row>
				  <entry>1 - 64</entry>
				  <entry>foreground</entry>
			        </row>
			        <row>
				  <entry>65 - 192</entry>
				  <entry>info</entry>
			        </row>
			        <row>
				  <entry>193 - &#x221E;</entry>
				  <entry>background</entry>
			        </row>
			      </tbody>
			    </tgroup></informaltable>
			  </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>
		    <option>-heartbeat { on | off | open }</option>
		  </term>
		  <listitem><para>
		      Changes the heartbeat setting for this screen.
		      If set to <literal>open</literal>, the default,
		      the client's heartbeat setting will be used.
		    </para></listitem>
		</varlistentry>
		<varlistentry>
		  <term>
		    <option>-backlight { on | off | toggle | open | blink | flash }</option>
		  </term>
		  <listitem><para>
		      Changes the screen's backlight setting.
		      If set 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> striking.
		    </para></listitem>
		</varlistentry>
		<varlistentry>
		  <term>
		    <option>-duration <replaceable>value</replaceable></option>
		  </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>
		    <option>-timeout <replaceable>value</replaceable></option>
		  </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>
		    <option>-cursor { on | off | under | block}</option>
		  </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>
		    <option>-cursor_x <replaceable>int</replaceable></option>
		    <option>-cursor_y <replaceable>int</replaceable></option>
		  </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>
	    <command>widget_add
	      <option><replaceable>screen_id</replaceable></option>
	      <option><replaceable>new_widget_id</replaceable></option>
	      <option><replaceable>widgettype</replaceable></option>
	      <optional><option>-in <replaceable>frame_id</replaceable></option></optional>
	    </command>
	  </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 icon. For a list of valid names consult
		      <filename>server/widget.c.</filename>
		    </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>
	    <command>widget_del
	      <option><replaceable>screen_id</replaceable></option>
	      <option><replaceable>widget_id</replaceable></option>
	    </command>
	  </term>
	  <listitem>
	    <para>
	      Deletes the given widget from the screen.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <command>widget_set
	      <option><replaceable>screen_id</replaceable></option>
	      <option><replaceable>widget_id</replaceable></option>
	      <option><replaceable>widgettype_specific_parameters</replaceable></option>
	    </command>
	  </term>
	  <listitem>
	    <para>
	      Sets parameters for a widget. Because not all widgets are created equal,
	      the various widget types require different parameters.
	      <variablelist>
		<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>
		    <note><para>
		      In the current implementation frames can only scroll vertically
		      and only string and hbar widgets work inside frames.
		    </para></note>
		  </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_"

	  # replace the main menu with the client's menu as created above
	  menu_set_main ""
	</programlisting>
      </para>
      <variablelist>
	<varlistentry>
	  <term>
	    <command>client_add_key
	      <optional>
	        <option>-exclusively</option> | <option>-shared</option>
	      </optional>
	      <option><replaceable>key</replaceable></option>...
	    </command>
	  </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>
	    <command>client_del_key
	      <option><replaceable>key</replaceable>...</option>
	    </command>
	  </term>
	  <listitem>
	    <para>
	      Ends the reservation of the given key(s).
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <command>menu_add_item
	      <option><replaceable>menu_id</replaceable></option>
	      <option><replaceable>new_item_id</replaceable></option>
	      <option><replaceable>type</replaceable></option>
	      <optional><option><replaceable>text</replaceable></option></optional>
	      <optional><option><replaceable>item_specific_options</replaceable></option></optional>
	    </command>
	  </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 item specific options
	      are described under menu_set_item below. Use of <replaceable>text</replaceable>
	      is optional and is a shortcut for "-text <replaceable>text</replaceable>"
	      option.
	    </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>
		<para>
		  If you want to use a text label that starts with a '-' (minus)
		  character, you have to use the "-text <replaceable>text</replaceable>"
		  option.
		</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>&gt;</literal>. When selected, the submenu becomes the
		      active menu.
		    </para></listitem>
		</varlistentry>
	      </variablelist>
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <command>menu_del_item
	      <option><replaceable>menu_id</replaceable></option>
	      <option><replaceable>item_id</replaceable></option>
	    </command>
	  </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>
	    <command>menu_set_item
	      <option><replaceable>menu_id</replaceable></option>
	      <option><replaceable>item_id</replaceable></option>
	      <option><replaceable>item_specific_options</replaceable></option>
	    </command>
	  </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>
			    <option>-text <replaceable>string</replaceable></option>
			  </term>
			  <listitem><para>
			      The visible text of the item.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-is_hidden { true | false}</option> (false)
			  </term>
			  <listitem><para>
			      If the item currently should not appear in a menu.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-next <replaceable>successor_id</replaceable></option>
			  </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>
			    <option>-prev <replaceable>predecessor_id</replaceable></option>
			  </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>
			    <option>-menu_result { none | close | quit}</option> (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>
			    <option>-value { off | on | gray }</option>
			  </term>
			  <listitem><para>
			      Set the value of the item.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-allow_gray { false | true}</option> (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>
			    <option>-value <replaceable>int</replaceable></option> (0)
			  </term>
			  <listitem><para>
			      Sets the index in the stringlist that is currently selected.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-strings <replaceable>string</replaceable></option> (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>
			    <option>-value <replaceable>int</replaceable></option> (0)
			  </term>
			  <listitem><para>
			      Sets its current value.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-mintext <replaceable>string</replaceable></option> ("")
			  </term>
			  <term>
			    <option>-maxtext <replaceable>string</replaceable></option> ("")
			  </term>
			  <listitem><para>
			      The texts at the left and right side of the slider.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-minvalue <replaceable>int</replaceable></option> (0)
			  </term>
			  <term>
			    <option>-maxvalue <replaceable>int</replaceable></option> (100)
			  </term>
			  <listitem><para>
			      The minimum and maximum values of the slider.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-stepsize <replaceable>int</replaceable></option> (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>
			    <option>-value <replaceable>int</replaceable></option> (0)
			  </term>
			  <listitem><para>
			      Sets its current value.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-minvalue <replaceable>int</replaceable></option> (0)
			  </term>
			  <term>
			    <option>-maxvalue <replaceable>int</replaceable></option> (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>
			    <option>-value <replaceable>string</replaceable></option> ("")
			  </term>
			  <listitem><para>
			      Sets its current value.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-password_char <replaceable>string</replaceable></option> ("")
			  </term>
			  <listitem><para>
			      If used, instead of the typed characters, this
			      character will be visible.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-minlength <replaceable>int</replaceable></option> (0)
			  </term>
			  <term>
			    <option>-maxlength <replaceable>int</replaceable></option> (10)
			  </term>
			  <listitem><para>
			      Sets the minimum and maximum allowed lengths.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-allow_caps { false | true }</option> (true)
			  </term>
			  <term>
			    <option>-allow_noncaps { false | true }</option> (false)
			  </term>
			  <term>
			    <option>-allow_numbers { false | true }</option> (false)
			  </term>
			  <listitem><para>
			      (Dis)allow these groups of characters.
			    </para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>
			    <option>-allowed_extra <replaceable>string</replaceable></option> ("")
			  </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>
			    <option>-value <replaceable>string</replaceable></option> ("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>
			    <option>-v6 { false | true }</option> (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>&gt;</literal>'. When selected, the submenu becomes the
		      active menu.
		      <variablelist>
			<varlistentry>
			  <term>
			    <option>-parent <replaceable>parentid</replaceable></option>
			  </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>
	    <command>menu_goto
	      <option><replaceable>menu_id</replaceable></option>
	      <optional><option><replaceable>parent_id</replaceable></option></optional>
	    </command>
	  </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>
	    <command>menu_set_main
	      <option><replaceable>menu_id</replaceable></option>
	    </command>
	  </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>
	    <command>backlight {
	      <option>on</option> |
	      <option>off</option> |
	      <option>toggle</option> |
	      <option>blink</option> |
	      <option>flash</option> }
	    </command>
	  </term>
	  <listitem>
	    <para>
	      Sets the client's backlight state.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <command>output {
	      <option>on</option> |
	      <option>off</option> |
	      <option><replaceable>int</replaceable></option> }
	    </command>
	  </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>
	    <command>info</command>
	  </term>
	  <listitem>
	    <para>
	      This command provides information about the driver.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <command>noop</command>
	  </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>
	    <command>sleep
	      <option><replaceable>int</replaceable></option>
	    </command>
	  </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>
      </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>
	    <computeroutput>success</computeroutput>
	  </term>
          <listitem><para>
            This is the response to a command in case everything went OK.
	  </para></listitem>
	</varlistentry>
        <varlistentry>
          <term>
	    <computeroutput>huh? <errortext>error_description</errortext></computeroutput>
	  </term>
          <listitem><para>
            This is the response 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>
	    <computeroutput>listen <replaceable>screen_id</replaceable></computeroutput>
	  </term>
          <term>
	    <computeroutput>ignore <replaceable>screen_id</replaceable></computeroutput>
	  </term>
          <listitem><para>
            The screen with the <replaceable>screen_id</replaceable> given is now
	    visible on the display (<literal>listen</literal>) or it is not visible
	    anymore on the display (<literal>ignore</literal>).
	  </para></listitem>
	</varlistentry>
        <varlistentry>
          <term>
	    <computeroutput>key <replaceable>key</replaceable></computeroutput>
	  </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>
	    <computeroutput>menuevent
	      <replaceable>event_type</replaceable>
	      <replaceable>id</replaceable>
	      <optional><replaceable>value</replaceable></optional>
	    </computeroutput>
	  </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 currently 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>