home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 September / PCWELT_9_2006.ISO / pcwsoft / Freeciv-2.0.8-win32-gtk2-setup.exe / doc / README.ftwl < prev    next >
Encoding:
Text File  |  2005-10-13  |  2.9 KB  |  119 lines
  1. ==============================
  2. Freeciv Theme and Widget Layer
  3. ==============================
  4.  
  5. Freeciv Theme and Widget Layer (FTWL) is a low-level library for 
  6. manipulating the graphics and input systems on your computer,
  7. and displaying screens with widgets based on themes loaded from 
  8. configuration files.
  9.  
  10. A few naming conventions:
  11.  
  12.   be_*        backend functions
  13.   te_*        theme engine functions
  14.   sw_*        widget related functions
  15.   osda        off-screen drawing area buffer
  16.  
  17. Programming in FTWL is quite simple. Here is an annotated example:
  18.  
  19. ==========================
  20.  
  21.     #include <config.h>
  22.  
  23.    Always remember this one, folks, otherwise you end up with bugs 
  24.    that are horribly difficult to figure out.  I speak from 
  25.    experience...
  26.  
  27.     #include <assert.h>
  28.     #include <stdio.h>
  29.  
  30.     #include "shared.h"
  31.     #include "support.h"
  32.  
  33.    These are utility files.
  34.  
  35.     #include "back_end.h"
  36.     #include "widget.h"
  37.  
  38.    These two contain the public API of FTWL.
  39.  
  40.     struct sw_widget *root;
  41.  
  42.    A variable to point to the root window.
  43.  
  44.     void nullfunc(int socket); /* prototype */
  45.  
  46.     static bool my_key_handler(struct sw_widget *widget,
  47.                                const struct be_key *key, void *data)
  48.     {
  49.       assert(ct_key_is_valid(key));
  50.       if (key->type == BE_KEY_NORMAL && key->key == 'q') {
  51.         exit(0);
  52.         return TRUE;
  53.       }
  54.       return FALSE;
  55.     }
  56.  
  57.    The above function is a callback that handles all keypresses that
  58.    are received on the root window.  We use this to add a convenient
  59.    way to exit our example application.
  60.  
  61.     void nullfunc(int socket)
  62.     {
  63.       return;
  64.     }
  65.  
  66.    The main loop expects a function pointer that can give it input
  67.    from outside devices, eg the network.  We just use an empty 
  68.    function here.
  69.  
  70.     int main(int argc, char **argv)
  71.     {
  72.       struct ct_size res;
  73.       struct ct_size size;
  74.  
  75.       res.width = 640;
  76.       res.height = 480;
  77.       sw_init();
  78.       be_init(&res, FALSE);
  79.  
  80.    Now we have set up the main window at 640x480.
  81.  
  82.       /* Error checking */
  83.       be_screen_get_size(&size);
  84.       if (size.width != res.width || size.height != res.height) {
  85.         die("Instead of the desired screen resolution (%dx%d) "
  86.             "got (%dx%d). This may be a problem with the window-manager.",
  87.             res.width, res.height, size.width, size.height);
  88.       }
  89.  
  90.    Error checking is always nice.
  91.  
  92.       root = sw_create_root_window();
  93.  
  94.    Set up the root window.
  95.  
  96.       sw_window_set_key_notify(root, my_key_handler, NULL);
  97.  
  98.    Register our key handler from above.  You need to register key 
  99.    handlers for any widget that is supposed to receive key presses.
  100.  
  101.       sw_mainloop(nullfunc);
  102.  
  103.    Start the main loop.  Unlike more primitive libraries, FTWL has a 
  104.    built-in main loop, and your program must be callback-driven.
  105.  
  106.       return 0;
  107.     }
  108.  
  109.    That's it.
  110.  
  111. ==========================
  112.  
  113. TODO: 
  114.  - Add more documentation!
  115.  - Support UNICODE
  116.  - Support more depth on the existing backend
  117.  - Create a backend with palette mode (no transparency, no AA)
  118.  - OpenGL, Quartz and DirectX backends
  119.