README

   1 This is the README for xuni version 0.3.0.
   2
   3 === Contents
   4     - About
   5     - Features
   6     - Code notes
   7     - Contact
   8
   9 === About
  10 xuni is a GUI widget toolkit written with the SDL and released under the
  11 GNU General Public License (GPL) version 2 (or later). See the file COPYING
  12 for licensing details.
  13
  14 xuni stands for "Explore the Universe". It's entirely coincidental that
  15 shifting one of the letters in "xuni" spells UNIX, and that reversing the
  16 letters and adding another letter spells Linux. "xuni" is pronounced "zoo-nee"
  17 in the author's opinion. But "ecks-you-nee" or "ecks-you-en-eye" or other
  18 variations work as well.
  19
  20 xuni was written from the ground up without incorporating any code from my
  21 numerous previous SDL projects. It uses SDL_image, SDL_gfx, and SDL_ttf in
  22 addition to the SDL, along with expat.
  23
  24 === Features
  25 xuni supports many features, including:
  26     - Coordinates as percentages of the parent widget
  27     - Coordinates as mathematical expressions (like "100 / 3") [1]
  28     - No required external resource files (except XML data) [2]
  29     - Portable code [3]
  30     - Reference counting
  31     - Rescalable widgets, images, text -- almost everything
  32     - Screen updates when states of widgets change (optional)
  33     - Theming support
  34     - TrueType font support, along with the SDL_gfx's built-in 8x8 bitmap font
  35     - Text editing, cursor movement, and text insertion and deletion
  36     - XML resource files for all widget data
  37
  38 [1] A simple expression parser written with yacc/bison accomplishes this.
  39
  40 [2] Most of the time, all of xuni's external resources can be deleted and xuni
  41 will still run. The exceptions to this, of course, are the XML data files --
  42 without those xuni has nothing to display.
  43
  44 [3] Besides its dependencies on various libraries, of course, xuni does not use
  45 any features outside of ANSI C99, and can be compiled as C89 by commenting out
  46 the line in version.h that defines "VERSION_STDC_C99". xuni has been tested by
  47 the author under 32- and 64-bit Debian GNU/Linux, along with Windows 98, XP,
  48 and (32-bit) Vista, as well as under Wine.
  49
  50 --- Disclaimers
  51 Note that support for these features may not work with certain releases. It's
  52 hard to keep so many features in working order. If something is broken,
  53 complain about it and it might be fixed by the next release. Alternatively,
  54 try using an earlier version of xuni.
  55
  56 xuni's API changes all of the time. Writing complex programs with it at the
  57 moment is probably not a very good idea, though the author might be willing to
  58 convert programs from one API version to another if asked nicely.
  59
  60 === Code notes
  61 xuni has over 10,000 lines of C source code, and keeping it all organized can
  62 be difficult. But most of xuni's code is well modularized, with few very large
  63 functions. Not many source files are over 1000 lines long. Approximately a
  64 quarter of all of xuni's public functions are documented -- run percentdoc.pl in
  65 doc/ after generating the Doxygen documentation for an exact number.
  66
  67 --- Programs
  68 Doxygen is used to generate documentation from documentation comments in the
  69 source code. Subversion was used for version control, and now git is used.
  70 yacc/bison is used to parse calc.y.
  71
  72 --- Artwork
  73 The neat xuni logo, the cloud backgrounds, menuhover and all other green
  74 glowing images, and all of the themes save raykelm were created by the author
  75 with the Gimp.
  76
  77 The raykelm theme is a modified version of the theme used by the test program
  78 from SDL_gui. The author of this GUI widget toolkit is Ray Kelm, hence the
  79 name of this theme.
  80
  81 The amazing astronomy background pictures are all from NASA.
  82
  83 --- Notes
  84     - Function pointers are used in many different places, for callbacks etc.
  85     - Unions of pointer types are preferred to void pointers at the moment
  86     - Though xuni is quite tied to the SDL, it is not tied to expat (as the mxml
  87         implementation shows) or even to XML resource files
  88     - All memory management is handled by memory.c, unless one can guarantee
  89         that there will only be one pointer to a block of memory -- for
  90         example, if the same function allocates and frees the memory
  91     - Speed is usually considered more important than memory efficiency
  92     - Flexibility is often considered most important of all
  93
  94 === Contact
  95 At the time of this writing, xuni can be obtained from:
  96     http://xuni.sourceforge.net/
  97 The same site has a message board where you can post thoughts about xuni.
  98
  99 You can reach the author by email at dwks at theprogrammingsite period com.
 100
 101 For faster responses, consider posting on the programming message board
 102 CBoard: cboard.cprogramming.com (post in Projects and Job Recruitment)