Fred's Home Page

About me
csh is bad
Help out
KRoC/Linux (old)
occam upgrades
occam tutorial
Projects (PhD)
Quick gdb
UNIX crashcourse
WG / WGBuilder

Window Gadgets and WGBuilder

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

Latest is wg-0.9.8 and wgbuilder-0.6.4


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 ;).


  • 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 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.


Code tarballs:

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 (640k), WGBuilder user-manual (quite helpful)

Older stuff:

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:

wgb_gadgets_visual.sovisualSelection of WG visual gadgets
wgb_gadgets_extra.soextraSelection of WG extra gadgets
wgb_supplib.sosuppExample not-in-WG gadget


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

newtest screenshot WGBuilder initial screenshot
newtest WG demo applicationWGBuilder 0.6.3 (build 677) just after launching
screenshot with the splash window screenshot with lots of stuff going on
After importing the splash window .hpd fileImported even more, plus showing object information for one of the gadgets


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:

window-gadgets 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'.


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.

WG3DRendermore-hackingvisualSimple 3D rendering thing
WGBevelmore-hackingvisualProvides lines / box which can appear raised/sunken
WGBitBtnmore-hackingvisualButton with little image
WGButtonmore-hackingvisualButton (and IE style)
WGCanvasmore-hackingvisualCanvas (drawing thing)
WGCDUtilnot-startednon-visualCD-player controller thing (PD)
WGCMessageWinmore-hackingvisualColoured multi-line message box
WGColorDlgnot-startedcomposite'Color' dialogue box
WGComboBoxmore-hackingvisualDrop-down combo box
WGContainermore-hackingvisualSimple container with optional 3 borders for use with WGTabTops
WGDavemore-hackingextra64 x 64 gray-scale piccy of Dave
WGDirOutlinenot-startedextraDirectory outline tree thing
WGDudemore-hackingextra64 x 64 little dude that does stuff :)
WGEditmore-hackingvisualSingle-line edit box
WGFileListnot-startedextraFile list box
WGFileListImgnot-startedextraFile list box with pretty images showing file type
WGFindDlgnot-startedcomposite'Find'/search dialogue box
WGFontDlgnot-startedcomposite'Font' dialogue box
WGFrednearly-thereextra64 x 64 gray-scale piccy of me (Fred)
WGGaugemore-hackingvisual%-bar gauge
WGGroupBoxmore-hackingvisualBorder with a label
WGHPScanmore-hackingextraHP SCSI scanner toy thing (PD)
WGHeadernot-startedextraSectioned visual control (status windows at screen bottoms)
WGISockClinearly-therenon-visualInternet socket client
WGISockSvrmore-hackingnon-visualInternet socket server
WGIUDPClinot-startednon-visualInternet datagram client
WGIUDPSvrnot-startednon-visualInternet datagram server
WGImagemore-hackingvisualDisplays an image / piccy thing
WGIniFilemore-hackingnon-visualini file access type thing
WGKarimmore-hackingextra64 x 64 gray-scale piccy of Karim
WGLabelmore-hackingvisualSimple label
WGLcarsButtonmore-hackingextraStar-trek style lcars button
WGLcarsEButtonmore-hackingextraStar-trek style lcars button with a bit for an lcars-panel
WGLcarsPanelmore-hackingextraStar-trek style lcars panel
WGLcarsSectionmore-hackingextraStar-trek style lcars section header
WGLcarsSplitmore-hackingextraStar-trek style lcars split-thing (for RHS of lcars-panel)
WGLcarsTitlemore-hackingextraStar-trek style lcars title bit (for top of an lcars-panel)
WGLinkednot-startednon-visualGeneric linked-list
WGListBoxmore-hackingvisualList box - select one or many
WGMSQLnot-startednon-visualMSQL database client bit (would require MSQL API)
WGMainMenumore-hackingvisualFor displaying across-the-top menus on WGWindow's
WGManagedmore-hackingvisualManaged window (for building window-manager type things)
WGMaskEditnot-startedextraMasked edit box (for dates, etc.)
WGMemonot-startedextraMulti-line edit box
WGMessageDlgmore-hackingcompositeSimple message dialogue (with optional icons :))
WGMessageWinmore-hackingvisualMulti-line message box
WGMitShmmore-hackingextraMIT-SHM gadget (provides raster, plus shading thing and plasma-generator)
WGNVisualnearly-therecoreAncestor of all non-visual objects
WGNotebooknot-startedvisualStack of pages, with one at the top (hence visible)
WGObjectnearly-therecoreUtter ancestor for all objects
WGOpenDlgnot-startedcomposite'Open' dialogue box
WGOutlinemore-hackingextraOutline thing - see directory trees in 95
WGPOP3not-startednon-visualPOP3 client
WGPaulmore-hackingextra64 x 64 gray-scale piccy of Paul
WGPicturemore-hackingvisualPicture (like an image, but with borders)
WGPipemore-hackingnon-visualUnix named-pipe
WGPopupmore-hackingvisualFor displaying drop-down menus on any visual component
WGQueuemore-hackingnon-visualGeneric queue
WGRadiomore-hackingvisualRadio-button (mutually exclusive)
WGRadioBtnmore-hackingvisualRadio-style image buttons
WGRecordSetmore-hackingnon-visualRecord-set for holding data
WGSMTPnot-startednon-visualSMTP client
WGSaveDlgnot-startedcomposite'Save' dialogue box
WGScrollBarmore-hackingvisualScroll-bar, both horizontal and vertical
WGScrollBoxnot-startedextraScrollable window (basically)
WGSpeedButtonmore-hackingvisualButton with only image
WGStackmore-hackingnon-visualGeneric stack
WGStevemore-hackingextra64 x 64 gray-scale piccy of Steve
WGStringGridnot-startedextraString grid, for displaying spread-sheet like things
WGStringListmore-hackingnon-visualString list
WGStringTreemore-hackingnon-visualString tree
WGTabTopsmore-hackingvisualThe little tab-bits (like in a file)
WGTerminalnot-startednon-visualThe TTY thing (for our controlling one)
WGTimermore-hackingnon-visualInterval timer (or alarm-clock) - implementation requires thought
WGUSockClinot-startednon-visualUnix socket client
WGUSockSvrnot-startednon-visualUnix socket server
WGVisualnearly-therecoreAncestor of all visual objects
WGWatchernearly-therenon-visualSimple thing that watches file-descriptors for activity
WGWinGaugemore-hackingvisualWin-95 'little-boxes' style gauge
WGWindowmore-hackingvisualTop-level application window (border and borderless)
XColorServernearly-therecoreColor handling routines
XConnectionnearly-therecoreWhat everything sits on
XDisplayServernearly-therecoreVisual link-up
XFontServernearly-therecoreFont handling routines
XPixmapServernearly-therecorePixmap handling routines
XUtilServernearly-therecoreGeneral handy routines
Last modified: 2003-11-01 17:06:21.000000000 +0000 by Fred Barnes [ls] [plain]
Page generated: Sun Apr 28 11:39:34 2013
Valid XHTML 1.0! Valid CSS!