Fred's Home Page

Window Gadgets and WGBuilder

[ about | news | buildinit | download | screenshots | information | gadgets ]

Latest is wg-0.9.8 and wgbuilder-0.6.4

About

Window Gadgets (WG) is my effort (so-far) at writing a toolkit for X11. It started life when I was writing gametest and decided a simple toolkit was needed (for menus and suchlike). Around that point I stopped working on gametest and went flat-out on WG.

WG is written in C++ (although a rehack into C is still on the cards) and requires X11. Most of the code is 2-3 years old, it's just been lurking on my fs along with vague promises to people about getting it on the net. It would appear that my coding style has changed since then (for the better). Respect to GNU indent. My preferred runes are `-bap -ts8 -i8 -br -ce -nbc -l180'.

Window Gadgets Builder (WGBuilder) is an ``integrated rapid application development environment'' for the X Window System. This basically means that it's a drag-and-drop style graphical design thing. It uses the WG toolkit fairly extensively -- using WG itself, and generating output which uses WG. WGBuilder also used itself fairly extensively during development.

Important note (!): The copyright of Window Gadgets (WG) is owned exclusively by Frederick Barnes (apart from bits of code with appropiately acknowledged sources and the bits written by David Reeve). The copyright of WGBuilder is owned by the University of Kent, Frederick Barnes and David Reeve, with sections owned by Paul Rogers, Steven Fagg and Karim Saykali. WGBuilder was our final-year CS undergraduate project, hence the ownership by the university. However, due to the GPL-age of WG, it can't generate any money in itself -- unless the uni were to buy WG off me (not going to happen).. These, and all associated programs, files, etc. are released under the GNU General Public License (GPL) license. See the Free Software Foundation's website for more information. In essence:

You can use, modify and/or sell this (freely available) software, but the copyright and licensing must be perserved, as per the terms of the GPL. Due to the licensing of WG, any applications created which use it (ie, linked against it) which you wish to make available, must have the sources made publically available (including things like .hpd files, etc.). The other authors and myself would get very unhappy/lawyers if we found parts of this software used in non-GPL software. This can only change if I re-license WG under the LGPL, which would allow it to be linked with non-free software. I'm not planning on doing this however, as I would like it and any decendants to remain fully free software. For private-only use, you may do what you like with it -- just don't make any of it (verbatim or modified) public without freely available sources.

Even though other email addresses appear in the code, etc., all queries/etc. should be sent to me (Fred Barnes) since I'm the only one actively doing anything to it ;).

News

• 02/02/2003 Released version 0.9.8, more WGCanvas'ing.
• 26/01/2003 Released version 0.9.7, now has an almost useful WGCanvas. Couple of minor bug-fixes went in too.
• 10/12/2002 Released version 0.9.6, with some new bits in XConnection and a slightly functional WGCanvas.
• 05/12/2002 More gadget abstractions. Turned out version 0.9.5. WGBuilder still working :).
• 19/11/2002 Tidied up some bits, did one or two more gadgets. Turned out version 0.9.4.
• 17/11/2002 Added abstractions for WGTextOps and WG3DComp to some gadgets, plus interface methods for WGObject. Made version 0.9.3.
• 15/11/2002 11 months on, and one patch-level greater. Added some user-state to visual gadgets.
• 07/12/2001 Not done much for a while, been busy with other stuff. Some WG updates will be appearing at some point though.
• 20/07/2001 Fixed the really irritating bug that was causing the previous version(s) to screw-up when editing a file. Added a license page to WGBuilder, which throws up a stock chunk of GPL. Updated the images for WGPaul and WGSteve, although all five of us should get together for a photo session at some point..
• 09/06/2001 Been through WGBuilder, GPL'd and auto{conf,make}ified it. Seem to be all working OK. There are still some fairly serious bugs in WG/WGBuilder (for instance, editing a callbacks file in WGBuilder tends to do something confusing to WG, resulting in an unresponsive WGBuilder..).
• 07/06/2001 I've put some tarballs of WG and the newtest app here now. This is very much a "I've just been through it and added the GPL, fixed one or two minor things, and bunged into auto{make,conf}". Thus, I make no guarentee that it'll even compile on your system, let alone work ;). It should hopefully be OK though..
• 07/06/2001 Updated buildinit a bit -- still needs some more work in the near future tho. Latest is 1.1.1.

BuildInit

buildinit is a program which generates C++ code to create some gadget (and its children) from a Hierarchical Program Description (HPD) file. HPD files describe an interface in terms of a gadget hierarchy and the properties of those gadgets. Each gadget has an associated mapping (.wgm) file which describes how to set the various properties, what callbacks exist, and what needs to be #include'd to use the gadget. Buildinit combines an HPD file with the various mappings to produce code which will create the interface at run-time.

In order to use buildinit successfully, you'll need the ``mapping.wgm'' file -- I usually park it in the `lib/' directory, but wherever you like really.

Downloads

Code tarballs:

• 02/02/2003 wg-0.9.8.tar.gz (336k), Window-Gadgets version 0.9.8
• 26/01/2003 wg-0.9.7.tar.gz (334k), Window-Gadgets version 0.9.7
• 10/12/2002 wg-0.9.6.tar.gz (333k), Window-Gadgets version 0.9.6
• 05/12/2002 wg-0.9.5.tar.gz (333k), Window-Gadgets version 0.9.5
• 19/11/2002 wg-0.9.4.tar.gz (329k), Window-Gadgets version 0.9.4
• 17/11/2002 wg-0.9.3.tar.gz (328k), Window-Gadgets version 0.9.3
• 15/11/2002 wg-0.9.2.tar.gz (326k), Window-Gadgets version 0.9.2
• 20/07/2001 wgbuilder-0.6.4.patch.gz (15k), WGBuilder patch from 0.6.3 to 0.6.4
• 20/07/2001 wgbuilder-0.6.4.tar.gz (399k), WGBuilder version 0.6.4
• 20/07/2001 wg-0.9.1.tar.gz (303k), Window-Gadgets version 0.9.1
• 07/06/2001 newtest-0.9.tar.gz (130k), newtest demo application version 0.9
• 07/06/2001 buildinit-1.1.1.tar.gz (61k), buildinit tarball

Other needed/useful stuff:

• 07/07/2001 wg_prefs (1k), ~/.wg_prefs WG preferences file
• 07/07/2001 mapping.wgm (20k), combined gadget mappings file
• 09/07/2001 userman.ps.gz (640k), WGBuilder user-manual (quite helpful)

Older stuff:

• 09/06/2001 wgbuilder-0.6.3.tar.gz (397k), WGBuilder version 0.6.3
• 07/06/2001 wg-0.9.tar.gz (285k), Window-Gadgets version 0.9
• 04/04/2001 buildinit-1.1.tar.gz (61k), buildinit tarball
• 04/04/2001 newtest.hpd (61k), example HPD file (from the newtest demo app)

Note: the above downloads will be replaced by a more `together' distribution at some point, but these bits will do for now.. Also, better download the wg_prefs file and put it in `~/.wg_prefs', if you want stuff to look half decent ;).

To build, install, etc., download wg-0.9.tar.gz and newtest-0.9.tar.gz (as above). Create a `~/wg/' directory (or wherever you want to put it), and ungzip/untar the tarballs in there, thus you should end up with `~/wg/wg-0.9/' and `~/wg/newtest-0.9/'. Then configure, make, and install wg; configure and make newtest:

    [host]:/home/me/wg$ cd wg-0.9

    [host]:/home/me/wg/wg-0.9$ ./configure --prefix=/home/me/wg
        ... output from configure ...

    [host]:/home/me/wg/wg-0.9$ make
        ... compile stuff ...

    [host]:/home/me/wg/wg-0.9$ make install
        ... installs into /home/me/wg/lib/ ...

    [host]:/home/me/wg/wg-0.9$ cd ../newtest-0.9

    [host]:/home/me/wg/newtest-0.9$ ./configure --prefix=/home/me/wg
        ... output from configure ...

    [host]:/home/me/wg/newtest-0.9$ make
        ... compile stuff ...

    [host]:/home/me/wg/newtest-0.9$ ./newtest
        ... newtest should run! ...

Buildinit is not actually needed to build newtest, since the buildinit'd .hpd files are included in the distribution. However, if you want to change anything, you'll need to grab, configure, make and install buildinit-1.1.1.tar.gz. The command I used to create the _init.[ch] files for newtest was:

    [host]:/home/me/wg/newtest-0.9$ ../bin/buildinit -m ~/wg/lib/mapping.wgm -s ./newtest.hpd

obviously, you'll need mapping.wgm to do this.

For WGBuilder, download and unpack it somewhere, then configure it with the same prefix as used for WG. Make and install in the usual way. For example:

    [host]:/home/me/wgbuilder-0.6.3$ ./configure --prefix=/home/me/wg
        ... output from configure ...

    [host]:/home/me/wgbuilder-0.6.3$ make
        ... compile stuff (takes a while) ...

    [host]:/home/me/wgbuilder-0.6.3$ make install
        ... installs into /home/me/wg/lib and /home/me/wg/bin ...

When you start WGBuilder for the first time, it will prompt you to supply some libraries and bring up the ``User Preferences'' window. Go to the ``Libraries'' tab and supply the libraries ``make install'' left in /home/me/wg/lib. You'll need to supply full paths to these things. The default libraries (and prefixes) are:

Screenshots

Here's a collection of various screenshots (click on the images for a full-size version):

newtest WG demo application		WGBuilder 0.6.3 (build 677) just after launching
After importing the splash window .hpd file		Imported even more, plus showing object information for one of the gadgets

Information

Here's a quick run-down of some WG features:

• Internally divided into clients and servers (gadgets are clients)
• Pixmap, Font and Colour servers to ease X interactions
• Redirection of gadget events
• Non-visual gadgets for interactions with sockets, etc.
• Modalisation of gadgets (and their children)

WG comprises of a pile of C++ classes for the most part. The choice of C++ was for inheritance and the handy subtyping mechanisms, not for the (non-)merits of OO. Below is a picture showing the object heirarchy:

Essentially, everything ultimately descends from `WGObject', which implements some basic stuff to make life easy for everything. This includes a pointer to the `XConnection' class and some functions which handle timeouts and message passing. There's also a pointer to some identifying string. Visual (ie, on-the-screen) gadgets descend from the `WGVisual' class, and non-visual (eg, sockets, etc.) gadgets descent from the `WGNVisual' class.

The main bulk of the WG core is contained in the `XConnection' class. The majority of this is managing gadgets at run-time, largely processing the incomming X events and handing them to a particular gadget. There's also all the stuff to deal with message passing, timers, signal handling, handling the little popup `hint-window', etc. Various server classes exist (`X...Server') which provide services to gadgets. The `XDisplayServer' class, for instance, handles the actual connection to the X server. The `XFontServer' is used to manage fonts, and so on.

The seperation between `XConnection' and `XDisplayServer' is to allow a single WG application to run on multiple X servers. This isn't quite finished yet, but the results could be quite interesting.

Since gadgets only need to descend from `WGNVisual' if they use blocking file-descriptors, etc., there are some non-visual gadgets which descend directly from `WGObject'.

Gadgets

Here is the current list of gadgets. The `state' refers to the current development state of the gadget, ie, `nearly-there', `more-hacking' or `not-started'. WG as a whole is not nearly-there yet however. There's still some stuff which might get changed or removed in the near future.