Menus

This file originally described how the menus should become implemented.
Now that they are implemented, the description is also in the source:
server/menu.h. The current menu contents can be found in server/menus.c.
Reading these files it becomes easy to understand the menus.

I (Joris) have given the file you are reading a new purpose:
client-supplied menus.

fixme: some of this stuff is described better in
       ./docs/lcdproc-dev/language.docbook so this file should
       probably be removed after extracting the information that is
       not anywhere else; see also ./docs/netstuff.txt (Volker)


INTERNAL SERVER DATA

In the server dir there is a file named client_menus.h from 3 april 2000
which describes the data structures that we should probably need.

typedef struct client_menu {
	char id[];
	LL *items;
} client_menu;

(LL is a list)

typedef struct client_menu_item {
	char id[];
	int type;						  // Title, function, submenu, slider, checkbox, etc...
	int value;						  // Holds stuff like "true", 43, etc...
	char text[];					  // Text to display here...
	char child[];					  // For the "submenu" type
} client_menu;



DEFINING BY CLIENTS

To define a menuitem using the widget language the following functions have
been defined in the file client_functions.c:
(In my opinion the menu_add functions can be left away, because a submenu
is an item as well.)

menu_add_item
menu_del_item
menu_set_item

The functions are not implemented yet, but looking at what we need, the
parameters could look like this:

menu_add_item itemname itemstring itemtype [-m menu] -v initvalue
menu_del_item itemname
menu_set_item itemname [-v value] [-s itemstring]

You should not need to define the first menu of a client. The name of the
client is known and will be used to give the menu a name. The first level
menu will simply be created automatically when a client defines an item in
it's menu.
(Or is there any reason why the client should create its own menu ? A client
should not be able to create two main menus anyway)

The following item types exist:
title		A title to be used on the top of the menu.
menu		A submenu. Refer to this new menu using the -m option.
action		An action. The client is notified that the user wants the
		action to be executed.
checkbox	A checkbox. The client is notified whenever the state is
		changed.
slider		A checkbox. The client is notified whenever the slider is
		moved.

fixme: missing description of numeric, alpha, ip, ..., see
       ./docs/lcdproc-dev/language.docbook (Volker)

Note that I have changed the 'function' menu type to 'action' here. The name
'function' was only appropriate internally, because a function was called.
For clients we only know an action will be performed.

fixme: missing reference to lcdexec (Volker)


RETURNED DATA

The server should inform the client on events. It should be able to return 
strings like:

action itemname
checkbox itemname newvalue
slider itemname newvalue


EXAMPLE SESSION

We have an M3 player here.

menu_add_item action play "Play"
menu_add_item action stop "Stop"
menu_add_item menu tracks "Select Track"
menu_add_item action track1 "1: Leg"
menu_add_item action track2 "2: Palomine"
menu_add_item action track3 "3: Kid's allright"
menu_add_item action track4 "4: brain-Tag"
menu_add_item menu CDs "Select CD"
menu_add_item action cd1 "1: Bettie Serveert - Palomine"
menu_add_item action cd2 "2: Rammstein - Herzeleid"
menu_add_item slider volume "Volume"

When you should switch CD using the second submenu, the client will be
informed with:

action cd2

Then the client knows the user has selected the second CD, and the items of
the Track menu should be changed according to the contents of the CD:

menu_set_item track1 -s "1: Wollt ihr das bett in flammen sehen"
menu_set_item track2 -s "2: Der meister"
menu_set_item track3 -s "3: Weisses fleish"

When the user changes the volume slider, the client will be informed with:

slider volume 40

When it is set at 40%.



fixme: missing description of menu_goto for session control (Volker)


--
Complete rewrite, Joris Robijn, 20011015