LCDproc client/server protocol
---------------------------------------------


QUICKSTART
----------
 - Open a socket to the LCDproc port (usually 13666).
 - say "hello"
 - the server will notify you of a good connection, and some info
   on the type of display available.
 - Identify yourself.  "client_set name some_sort_of_name"
 - Add a new screen.  "screen_add my_screen"
 - Put a widget on the screen.  
   "screen_add_widget my_screen my_widget string"
 - Now, update the widget whenever your status info changes...
   "screen_set_widget my_screen my_widget 1 1 Booger!"

 - When you're done, just close the socket.
 - You probably want to read on for more information, once you've
   gotten the LCDproc server to display something.  :)



DETAILS
-------

There are two parts to the spec:
	A language for client/server to interact with.
	A protocol guiding interactions.

=================== The protocol ==================================

The protocol is context-free.  So, no commands require responses; and
responses are simply commands.

The client may send updated info at any time, and the server decides
whether to display it.  An ideal communication may flow like this:
	client->server		server->client
	------------------	-------------------
	 (idle)			 (nothing)
	 (idle)			"I'm listening"
	new stats...		 (nothing; displays updated stats)
	new stats...		 (nothing...)
	new stats...		 (nothing...)
	new stats...		"Okay, be quiet"
	 (idle)			 (nothing; displays new screen)
	...			...
	 (idle)			"Your slider moved up"
	Set slider value: 43	(nothing; displays updated slider)
	 (idle)			(nothing)
	...			...
But the client could safely continue to send new stats, knowing that
the server isn't listening and won't display it.  Also, the client could
ignore the slider change, and the slider onscreen simply wouldn't move.


=================== The syntax ==================================

The language is ascii-based, so a human can telnet to a port and talk
to the server.  This helps with development and debugging.

With that in mind, a commandline-like syntax seems good:

	function arg1 arg2 arg3 ...

The syntax dictates that the first word is a function name, and the
rest of the line is passed to that function as an argument.
String-type arguments should always come last.  So, for example:

	set_label 23 3 2 Hey, booger.  What's up?

The first argument is a label id number, the 2nd and 3rd are x,y
coordinates onscreen, and the rest of the line is a string.


=================== The command set ==================================

The naming convention dictates that function names are lower-case,
with underscores ("_"'s) between words.

The naming convention also requires that function-name words go in
descending order.  So, "screen_set_priority" would be okay, but
"set_screen_priority" would not.

Id's are strings.  (the "#id" things)

In general, we're trying to keep the command set small.  Especially the
server->client functions, so that clients won't have to handle a lot of
different types of input.

Now, the function list:

client->server functions
-------------------------
hello
	Client init.  You must send this before the server will pay 
	any attention to you.  You'll get some info about the server
	in return...
client_set [name #id]
	Set client's name and other info
client_add_key #id
	Tells the server the client can handle keypresses of type #id.
	#id is probably just "A", "B", and so on...
	All keypresses are disabled by default, so you'll have to tell
	the server which ones you want to accept...
client_del_key #id
	Tells the server to never send that keypress.
	All keypresses are disabled by default.

screen_add #id
	Add a new screen
screen_del #id
	Remove a screen
screen_set #id [priority #priority] [name "my_name"]
	Initialize a screen, or reset its data.
screen_widget_add #screen #id type
	Add something onscreen
	Widget types can be any of the following:  "string", "hbar",
	"vbar", "title", "icon", ... "scroller"? ... more later?
	Widgets are drawn in the order you create them.
screen_widget_del #screen #id
	Kill something onscreen
screen_widget_set #screen #id data
	Set (reset) widget's data
	Note that the "string" type should be used for frame buffers.
	Strings should not be bigger than the screen.
	The widgets take these arguments for data:
		string		x y text
		hbar		x y length_in_pixels
		vbar		x y length_in_pixels
		icon		x y binary_data
		title		text
		scroller?	x y direction speed text
			A scroller is a string which scrolls.
			This is useful for things such as the disk
			usage screen, which may be very tall.
			The speed is how many display frames to delay
			between scrolling.  Each display frame is
			1/8th of a second.

--- Not implemented in this release: menu_* and driver_* ---

menu_add #id
	Add a new menu.  
menu_del #id
	Get rid of a menu.
menu_set [top] [name my_menu_name]
	if (top) Gets added to "Client Menus".
	else Client must insert it into its own menu heirarchy.
menu_item_add #menu #id
	Add a new, blank menu item.
menu_item_del #menu #id
	Delete a menu item.
menu_item_set #menu #id type [value] text
	(re)Set the menu item's data.
	If type is "checkbox" or "slider" or "menu", [value] should
	contain appropriate info.  (like true, 43, or #menuid)

driver_add #id? type args
	Start up a new output driver.
	Nice if you want to check on your machine remotely with the 
	curses driver.
driver_del #id? (or type)
	Stop a running output driver.
	Good for reclaiming your joystick when you want to play games...


server->client functions
-------------------------
connect args
	Verifies connection; gives info about the LCD, etc...
bye
	Notifies the client of a server shutdown.
huh? [info]
	Notifies the client of a request error.
listen [#screen [#widget [#widgets...]]]
	Notifies client that "server is listening for data".

ignore [#screen [#widget [#widgets...]]]
	Tells the client "shut up".

key #id
	Sends a keypress to the client.

menu #menu #item #action
	Tells the client that a menu item was selected/used/etc...
	The action can be "click", "up", or "down".  The client should
	handle this according to what type of menu item has been
	activated, and should probably send the server a new item
	definition if the item was a checkbox or slider.



