==============================
Freeciv Theme and Widget Layer
==============================

Freeciv Theme and Widget Layer (FTWL) is a low-level library for 
manipulating the graphics and input systems on your computer,
and displaying screens with widgets based on themes loaded from 
configuration files.

A few naming conventions:

  be_*		backend functions
  te_*		theme engine functions
  sw_*		widget related functions
  osda		off-screen drawing area buffer

Programming in FTWL is quite simple. Here is an annotated example:

==========================

	#include <config.h>

   Always remember this one, folks, otherwise you end up with bugs 
   that are horribly difficult to figure out.  I speak from 
   experience...

	#include <assert.h>
	#include <stdio.h>

	#include "shared.h"
	#include "support.h"

   These are utility files.

	#include "back_end.h"
	#include "widget.h"

   These two contain the public API of FTWL.

	struct sw_widget *root;

   A variable to point to the root window.

	void nullfunc(int socket); /* prototype */

	static bool my_key_handler(struct sw_widget *widget,
	                           const struct be_key *key, void *data)
	{
	  assert(ct_key_is_valid(key));
	  if (key->type == BE_KEY_NORMAL && key->key == 'q') {
	    exit(0);
	    return TRUE;
	  }
	  return FALSE;
	}

   The above function is a callback that handles all keypresses that
   are received on the root window.  We use this to add a convenient
   way to exit our example application.

	void nullfunc(int socket)
	{
	  return;
	}

   The main loop expects a function pointer that can give it input
   from outside devices, eg the network.  We just use an empty 
   function here.

	int main(int argc, char **argv)
	{
	  struct ct_size res;
	  struct ct_size size;

	  res.width = 640;
	  res.height = 480;
	  sw_init();
	  be_init(&res, FALSE);

   Now we have set up the main window at 640x480.

	  /* Error checking */
	  be_screen_get_size(&size);
	  if (size.width != res.width || size.height != res.height) {
	    die("Instead of the desired screen resolution (%dx%d) "
	        "got (%dx%d). This may be a problem with the window-manager.",
	        res.width, res.height, size.width, size.height);
	  }

   Error checking is always nice.

	  root = sw_create_root_window();

   Set up the root window.

	  sw_window_set_key_notify(root, my_key_handler, NULL);

   Register our key handler from above.  You need to register key 
   handlers for any widget that is supposed to receive key presses.

	  sw_mainloop(nullfunc);

   Start the main loop.  Unlike more primitive libraries, FTWL has a 
   built-in main loop, and your program must be callback-driven.

	  return 0;
	}

   That's it.

==========================

TODO: 
 - Add more documentation!
 - Support UNICODE
 - Support more depth on the existing backend
 - Create a backend with palette mode (no transparency, no AA)
 - OpenGL, Quartz and DirectX backends