/usr/share/doc/freeciv-data/README.ftwl is in freeciv-data 2.3.2-1+deb7u1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | ==============================
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
|