README

   1 This is the README for xuni version 1.0.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     - Garbage collection (really just a reference counter)
  29     - No required external resource files (except XML data) [2]
  30     - Portable code [3]
  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] xuni does not use any features outside of ANSI C99, and can be compiled as
  45 C89 by commenting out the line in version.h that defines "VERSION_STDC_C99".
  46 xuni has been tested by the author under 32- and 64-bit Debian GNU/Linux,
  47 along with Windows 98, XP, and (32-bit) Vista.
  48
  49 --- Disclaimers
  50 Note that support for these features may not work with certain releases. It's
  51 hard to keep so many features in working order. If something is broken,
  52 complain about it and it might be fixed by the next release. Alternatively,
  53 try using an earlier version of xuni.
  54
  55 xuni's API changes all of the time. Writing complex programs with it at the
  56 moment is probably not a very good idea, though the author might be willing to
  57 convert programs from one API version to another if asked nicely.
  58
  59 === Code notes
  60 xuni has over 10,000 lines of C source code, and keeping it all organized can
  61 be difficult. But most of xuni's code is well modularized, with few very large
  62 functions. Not many source files are over 1000 lines long. Unfortunately,
  63 however, there are precious few comments.
  64
  65 --- Programs
  66 Doxygen is used to generate documentation from documentation comments in the
  67 source code. Subversion is used for version control (although the repository
  68 is not hosted online just yet). yacc/bison is used to parse calc.y.
  69
  70 --- Artwork
  71 The neat xuni logo, the cloud backgrounds, menuhover and all other green
  72 glowing images, and all of the themes save raykelm were created by the author
  73 with the Gimp.
  74
  75 The raykelm theme is a modified version of the theme used by the test program
  76 from SDL_gui. The author of this GUI widget toolkit is Ray Kelm, hence the
  77 name of this theme.
  78
  79 The amazing astronomy background pictures are all from NASA.
  80
  81 --- Notes
  82     - Function pointers are used in many different places, for callbacks etc.
  83     - Unions of pointer types are preferred to void pointers at the moment
  84     - Though xuni is quite tied to the SDL, it is not tied to expat or even
  85         to XML resource files
  86     - All memory management is handled by memory.c, unless one can guarantee
  87         that there will only be one pointer to a block of memory -- for
  88         example, if the same function allocates and frees the memory
  89     - Speed is usually considered more important than memory efficiency
  90
  91 === Contact
  92 At the time of this writing, xuni can be obtained from:
  93     http://dwks.theprogrammingsite.com/myprogs/xuni.htm
  94
  95 You can reach the author by email at dwks at theprogrammingsite period com.
  96
  97 For faster responses, consider posting on the programming message board
  98 CBoard: cboard.cprogramming.com (post in Projects and Job Recruitment)