From Freeciv

[edit] 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