Fred's Home Page

Main
About me
Crumble
csh is bad
Debian
FredCam
Guppy
Hardware
Help out
Java-glossary
Job-control
KRoC/Linux (old)
Lambda
Life-stuff
Links
Linux
Mesh
Misc
Music
occam
occam upgrades
occam tutorial
OpenUPSd
Pictures
Programming
Projects (PhD)
Publications
Quick gdb
RAPP
RMoX
Software
UNIX crashcourse
UWG
UWGBuilder
WG / WGBuilder
XDM-Choose
XHPD

Micro Window-Gadgets

[ news | download | about | technical | screenshots | gadgets | properties ]


News

Recent UWG happenings:

  • 03/12/2006 released version 0.2.0
  • 25/08/2006 released version 0.1.6
  • 26/06/2006 released version 0.1.5
  • 26/02/2006 released version 0.1.4
  • 01/06/2005 released version 0.1.3 (still under development)
  • 25/07/2004 released version 0.1.2 (still early days)
  • 12/07/2004 released version 0.1.1 (in extreme development)


About

Micro WG is a C `version' of WG. In general, UWG is somewhat more light-weight than WG. Firstly because it's written in C and not C++. Secondly because it does not yet provide all the features of WG. Also, it should be significantly easier to `connect' UWG to KRoC.

Why UWG ? It's now the case that there are many `widget libraries' for programmers to choose from. The traditional X11 widget libraries (X Toolkit Intrinsics), GTK, QT, Motif, wxWindows, TK, etc.. GTK and QT are probably the most common for an average user's desktop system -- as the graphics libraries of Gnome and KDE respectively. C++, used by WG, provides a largely type-safe environment for gadget programming -- i.e. the structure/nature of gadgets fit neatly into the C++ type (class) heirarchy. However, C++ ultimately suffers from the same problems as some other `object-orientated' languages -- namely leaky encapsulation. When writing WG, some of the limitations (maybe features) of C++ caused significant problems, particularly in the function-pointer department. Object-orientation is a fine model for data, but it does not work well when `bolted-on' to sequential languages -- C++ and Java in particular. Forcing a sequential flow-of-control through something that we tried to break into objects only leads to problems. E.g. when executing inside the method of one object, is it safe to delete another object ? -- well, only if that other object wasn't involved (and still is involved) in the flow-of-control. And this you cannot easily tell. Furthermore, in many cases, `delete' may be substituted for any object interaction (method-call).

Also, a lot of modern GUI toolkits seem unnecessarily bloated. C++ (and other `frilly' languages) can be blamed for some of this, but not all of it. WG isn't bloated yet, but it's not far off. UWG is therefore an attempt at a lightweight (size and speed) gadget toolkit for X11, programmed in C.


Download and Installation

Here are the downloads for UWG. At the moment, the distribution is fairly basic, but it should work. Prior to version 0.1.6, UWG didn't really install itself anywhere. Now it will attempt to park itself in the right places.

  • uwg_prefs preferences file (for UWG 0.2.0 and later), edit as desired and copy to ~/.uwg_prefs (default included in distribution)

UWG, by default, will configure itself for a regular installation -- i.e. it expects to be installed (this is because the generated uwg_config.h contains the locations of files which other packages can scan for). You can park it somewhere else in the usual way, for example:


    bash:~/uwg-0.2.0/$ ./configure --prefix=/home/fred/uwg
    ...  configure output
    bash:~/uwg-0.2.0/$ make install

Then unpack the other packages (ubuildinit, uwg-examples), configure with:


    bash:~/ubuildinit-0.2.0/$ ./configure --prefix=/home/fred/uwg \
        --with-uwg-config=/home/fred/uwg/include/uwg
    ...  configure output
    bash:~/ubuildinit-0.2.0/$ make install


    bash:~/uwg-examples-0.2.0/$ ./configure --with-uwg-config=/home/fred/uwg/include/uwg
    ...  configure output
    bash:~/uwg-examples-0.2.0/$ make


Technical

One slight disadvantage to not using C++ is that the code gets uglier. The gadget types are C structures that contain the gadget's state, along with various function-pointers for performing actions, etc. Instead of the multitude of `get/set' methods, gadgets have single `get' and `set' methods, that use a `uwg_prop_t' parameter and var-args. As part of the gadget's state is a `UWGVisual' pointer. This is a generic visual gadget that replaces `WGVisual' in WG. Gadget callbacks are now wrapped up in a separate structure, rather than being part of the gadget structure, e.g. `UWGButtonCB'. Gadgets maintain a pointer to their callbacks.

The various event callbacks (e.g. `xc_paint') are still separate. However, since these are now function-pointers, gadgets can override the default behaviours of other gadgets -- e.g. the UWGVDE gadget does this to control interactions with its children. As far as looking after children goes, WG used to maintain the visual heirarchy of gadgets. It no longer does this. Gadgets that need to be aware of their children can use the `xc_addchild' and `xc_delchild' callbacks, invoked by gadgets when created on them. To maintain a complete visual heirarchy, the `xc_{add,del}child' callbacks can be re-assigned as new gadgets are created; the intervening code can then decide whether to keep the event for itself, or pass it on to the original gadget (if it has an appropriate handler).

The central-point of UWG is the `UWGXContext' virtual gadget. This abstracts a connection to an X11 server, used by the various gadgets and the application. Unlike some other gadget toolkits, a UWG application can connect to many X servers -- if desired. This might be useful for multi-client applications -- e.g. a simple multi-user game. However, the first aim of UWG is to provide a toolkit -- application `help' is secondary, but still considered.

The use of C and functions with variable numbers of arguments creates a number of potential pitfalls -- such as calling a var-args function with incorrect parameters, that will most likely (and currently) result in a run-time error or undefined behaviour. The gadgets themselves will perform some checks, but mostly it is down to correct application programming. E.g. an attempt to set a gadget property that doesn't exist is benign, but an attempt to set a property using a different type than was expected will cause serious problems.

Fortunately, and much like WG, it is not expected that programmers write the code for creating and initialising (visual) interfaces themselves. WG uses a tool called `buildinit' to transform HPD (heirarchial program description) files into C++ code that creates (and destroys) whole interfaces -- typically top-level windows. UWG posesses a similar tool, but one that converts XHPD files into C code. XHPD files are `XML heirarchial program description' files, that use XML to describe the interface. A related program, RAPP (remote applications), can already process these XHPD files usefully. Rather than generating code, RAPP dynamically creates the described interface.

The follow shows an example of XHPD, that describes a simple button:


    <gadget type="UWGBitBtn" name="button2">
        <property name="geometry" value="100,32,144,40" />
        <property name="hint" value="this is a hint!" />
        <property name="font" value="fixed" />
        <property name="caption" value="more click!" />
        <property name="style" value="popup" />
        <property name="img-up" value="/usr/include/X11/pixmaps/screen.xpm" />
        <property set="cpref" />

        <action name="on_click">
            <property name="shadow" />
            <property source="mylabel" name="font" />
        </action>
    </gadget>

This particular example is designed for RAPP -- where the contents of the `<action>' tag are properties to be reported with the event. For producing C code to create interfaces, more useful would be application code. For example:


    <action name="on_click">
        <![CDATA[
            printf ("The button (%s) was clicked!\n", button2->visual->idstr);
        ]]>
    </action>

<update> and <command> blocks are interpreted by both "ubuildinit" and RAPP. For example:


    <action name="on_create">
        <command name="add_item">
	    <arg value="UWGPanel" />
	</command>
    </action>


Screenshots

Here are some screenshots of UWG. Note that more will appear as development progresses..

UWG testapp screenshot 1 UWG/ubuildinit test screenshot 4 UWG VDE
UWG testapp screenshot another (ubuildinit-generated) XHPD example initial VDE efforts in action, XHPD file
UWGBuilder splash screen UWGBuilder screen-shot igame2 arena screen-shot
Beginnings of UWGBuilder, a UWG version of WGBuilder A vaguely functional UWGBuilder Beginnings of a remake of gametest


Gadgets

Here is the current list of supported gadgets. There is an on-going process of converting WG gadgets into UWG gadgets -- it's not too difficult, but is quite time consuming. Gadgets will be added to this list as they are dealt with. See the WG gadget-list for `missing' content.

GadgetVersionStateDescription
UWGBitBtn0.9nearly thereButton with an image
UWGButton0.9nearly thereBasic button
UWGCanvas0.1just startingGeneral canvas gadget
UWGCheckBox0.9nearly thereBasic check-box
UWGChildProcess0.9nearly thereChild-process gadget (piped stdin/stdout)
UWGCMessageWin0.9nearly thereColour-capable message window
UWGComboBox0.1in progressDrop-down combo box
UWGContainer0.9nearly thereContainer gadget (e.g. for tab pages)
UWGCrypto0.9nearly thereCryptographic key handling (uses libgcrypt)
UWGDave0.9nearly thereDave gadget
UWGEdit0.9in progressEdit box
UWGFred0.9nearly thereFred gadget
UWGGroupBox0.9nearly thereFramed/captioned box
UWGIcon0.1in progressIcon gadget (with label)
UWGImage0.9nearly thereImage gadget
UWGIniFile0.9deprecated.ini-file style reader/writer (deprecated in favour of UWGSpecsFile)
UWGIDGramSvr0.1in progressUDP socket server
UWGISockCli0.9in progressTCP socket client
UWGISockSvr0.1in progressTCP socket server
UWGKarim0.9nearly thereKarim gadget
UWGLabel0.9nearly thereBasic label
UWGLayout0.1in progressAutomatic layout gadget
UWGLcarsButton0.9nearly thereStar-trek style button
UWGLcarsCheckBox0.9nearly thereStar-trek style check-box
UWGLcarsContainer0.9nearly thereStar-trek style container, to fit in the panel
UWGLcarsEButton0.9in progressStar-trek style bigger button
UWGLcarsMeter0.9nearly thereStar-trek style gauge/meter, fits in the panel
UWGLcarsPanel0.9in progressStar-trek style panel
UWGLcarsSection0.9in progressStar-trek style section title (along the top)
UWGLcarsSplit0.1queuedStar-trek style splitter
UWGLcarsTButton0.2in progressStar-trek style tab buttons
UWGLcarsTitle0.9in progressStar-trek style title (stick out from the side type)
UWGListBox0.9in progressBasic list-box
UWGMainMenu0.9nearly thereMain-menu gadget
UWGMitShm0.2in progressMIT-SHM gadget
UWGMVLayout0.9nearly thereMovement (drag-around) layout manager
UWGPanel0.9nearly thereBasic panel
UWGPaul0.9nearly therePaul gadget
UWGPicture0.1just startingPicture gadget
UWGPopup0.5in progressPopup menu
UWGPropSet0.1in progressGadget `property-set' wrapper
UWGRadioBtn0.1just startingOne-of-many selection buttons
UWGScrollBar0.9nearly thereHorizontal/vertical scroll-bar
UWGSpecsFile0.1in progress"specs" file reader/writer
UWGSpeedBtn0.9nearly thereImage-only button
UWGSteve0.9nearly thereSteve gadget
UWGStringTree0.2in progressHashed tree of strings (nodes + leaves)
UWGSDLAudio0.1just startingNon-visual gadget providing sound fuctionality via SDL
UWGTabTops0.9nearly thereTab-tops
UWGTiledArena0.1just startingTiled arena gadget
UWGTiledArenaMap0.1just startingMinature map for a UWGTiledArena
UWGTimer0.1just startingTimer gadget
UWGVDE0.1in progress`Visual Design Environment' from WGBuilder
UWGVGraph0.2in progressVisual graph (nodes and edges)
UWGWindow0.9nearly thereTop-level window
UWGXMLParser0.2in progressXML parser gadget


Properties

Gadgets typically have `get_property' and `set_property' ``methods'' (function-pointers). These take a property constant and some values. `get_property' always takes a pointer to the type that `set_property' takes -- and if a pointer is `returned', it is the gadget's own, not a copy (e.g. string properties).

Here is the current list of properties; the `Property' is a C enumeration (as a type called `uwg_prop_t').

PropertyType(s)Description
PROP_ACTIVE_BACKGROUNDunsigned long pixelactive background color value
PROP_ACTIVE_BACKGROUND_STRchar *coloractive background color string
PROP_ALERT_COLORunsigned long pixel`alert' pixel value
PROP_ALERT_COLOR_STRchar *color`alert' colour string
PROP_ALIGN_TO_GRIDint atgtruth value indicating whether child gadgets should be aligned to the parent grid
PROP_ALIGNMENTuwg_align_t aligntext alignment
PROP_ALLOW_TYPEint allowtruth value indicating whether a gadget that accepts text should allow typing
PROP_ANGLESint count, int a1, int a2, ...angles for certain gadgets
PROP_ANGLES_STRchar *strcomma-separated list of angles for certain gadgets
PROP_APP_NAMEchar *strapplication name (for the window-manager)
PROP_APP_CLASSchar *strapplication class (for the window-manager)
PROP_ARGSint count, char *arg1, char *arg2, ...arguments for certain gadgets
PROP_ARGS_STRchar *strcomma-separated list of arguments for certain gadgets
PROP_BACKGROUNDunsigned long pixelbackground pixel value
PROP_BACKGROUND_STRchar *colorbackground colour string
PROP_BORDER_PIXELunsigned long pixelborder pixel value
PROP_BORDER_PIXEL_STRchar *colorborder colour string
PROP_BORDER_WIDTHint bwidthborder width
PROP_BTNSTYLEuwg_btnstyle_t stylebutton style
PROP_CAPTIONchar *strcaption text
PROP_COPY_FROM_PARENTint cfptruth value indicating whether child gadgets should inherit properties from their parent
PROP_DIRECTIONint dirdirection value for certain gadgets/effects
PROP_DROP_IMAGEint droptruth value indicating whether images on buttons (and others) should move when the button is pressed
PROP_ENABLEDint visibletruth value indicating whether the gadget is enabled
PROP_EXPOSURESint exposetruth value indicating whether a gadget should generate exposure events (if it doesn't by default)
PROP_FOCUS_GADGETUWGVisual *gadgetfocused gadget within a window
PROP_FOCUSEDint focusedtruth value indicating whether a gadget has keyboard focus
PROP_FONTchar *fnamefont
PROP_FOREGROUNDunsigned long pixelforeground pixel value
PROP_FOREGROUND_STRchar *colorforeground colour string
PROP_GEOM_Xint xX position of the gadget (parent relative)
PROP_GEOM_Yint yY position of the gadget (parent relative)
PROP_GEOM_WIDTHint widthwidth of the gadget
PROP_GEOM_HEIGHTint heightheight of the gadget
PROP_GEOMETRYint x, y, width, heightgeometry of the gadget
PROP_HIGHLIGHTunsigned long pixel3D highlight pixel value
PROP_HIGHLIGHT_STRchar *color3D highlight colour string
PROP_HINTchar *hintpopup `hint' text
PROP_HINT_BACKGROUNDunsigned long pixelhint background pixel value
PROP_HINT_BACKGROUND_STRchar *colorhint background colour string
PROP_HINT_DELAYint secs, usecsdelay before a gadget hint is displayed
PROP_HINT_FONTchar *fontfont used for gadget hints
PROP_HINT_FOREGROUNDunsigned long pixelhint foreground pixel value
PROP_HINT_FOREGROUND_STRchar *colorhint foreground colour string
PROP_HOSTchar *hostnamehost-name (for socket gadgets, etc.)
PROP_ICON_NAMEchar *stricon-name text (for the window-manager)
PROP_IECOLORunsigned long pixel`interesting extra' pixel value, generally used for highlighting on mouse-over
PROP_IECOLOR_STRchar *color`interesting extra' colour string
PROP_IMG_DISABLED_FILEchar *filenamefilename of the image used for the `disabled' state on some gadgets
PROP_IMG_DOWN_FILEchar *filenamefilename of the image used for the `down' state on some gadgets
PROP_IMG_OFF_FILEchar *filenamefilename of the image used for the `off' state on some gadgets
PROP_IMG_UP_FILEchar *filenamefilename of the image used for the `up' state on some gadgets (also the default image)
PROP_INACTIVE_BACKGROUNDunsigned long pixelinactive background color value
PROP_INACTIVE_BACKGROUND_STRchar *colorinactive background color string
PROP_INACTIVE_FOREGROUNDunsigned long pixelinactive foreground color value
PROP_INACTIVE_FOREGROUND_STRchar *colorinactive foreground color string
PROP_INDENTint indent`indentation' for 3D effect
PROP_INVALIDgeneric invalid property
PROP_KEYBTNint buttonbutton value for a click event when the keyboard is used (on the focused gadget)
PROP_LAYOUTuwg_layout_t layoutlayout of gadget (for child gadgets of a layout)
PROP_LCARS1unsigned long pixelpixel value for star-trek style lcars-gadgets
PROP_LCARS1_STRchar *strcolour string for start-trek style lcars-gadgets
PROP_LCARS2unsigned long pixelpixel value for star-trek style lcars-gadgets
PROP_LCARS2_STRchar *strcolour string for start-trek style lcars-gadgets
PROP_LCARS3unsigned long pixelpixel value for star-trek style lcars-gadgets
PROP_LCARS3_STRchar *strcolour string for start-trek style lcars-gadgets
PROP_LCARS4unsigned long pixelpixel value for star-trek style lcars-gadgets
PROP_LCARS4_STRchar *strcolour string for start-trek style lcars-gadgets
PROP_LEADING_SPACEint pixelsleading space for some gadgets
PROP_LIMIT_MAXint maxmaximum limit for some gadgets
PROP_LIMIT_MINint minminimum limit for some gadgets
PROP_LIMITSint min, maxminimum and maximum limits for some gadgets
PROP_LOCK_TO_PARENTint ltptruth value indicating whether child gadgets should be wholly inside their parent window
PROP_MASK_DISABLED_FILEchar *filenamefilename of the mask used for the `disabled' state on some gadgets
PROP_MASK_DOWN_FILEchar *filenamefilename of the mask used for the `down' state on some gadgets
PROP_MASK_OFF_FILEchar *filenamefilename of the mask used for the `off' state on some gadgets
PROP_MASK_UP_FILEchar *filenamefilename of the mask used for the `up' state on some gadgets (also the default mask)
PROP_MAX_SIZEint maxmaximum text-entry size
PROP_MOUSE_MOTIONint motionwhether or not the gadget reports mouse movements
PROP_NAMEDchar *propname, ...non-standard named properties
PROP_ORDERuwg_order_t orderordering of items
PROP_PARENTUWGVisual *gadgetparent gadget
PROP_PASSWORD_CHARint chcharacter to be displayed instead of text
PROP_PATHchar *pathpath (file or directory) for certain gadgets
PROP_PORTint portport (for socket gadgets, etc.)
PROP_POSITIONuwg_winpos_t poswindow positioning
PROP_SAVE_UNDERint save_undertruth value indicating whether the contents underneath a window should be saved
PROP_SCROLLERUWGScrollBar *scrollerassociated scrollbar gadget
PROP_SCROLLTYPEuwg_scroll_t stypescroller type
PROP_SEL_BACKGROUNDunsigned long pixelselected background pixel value
PROP_SEL_BACKGROUND_STRchar *colorselected background colour string
PROP_SEL_FOREGROUNDunsigned long pixelselected foreground pixel value
PROP_SEL_FOREGROUND_STRchar *colorselected foreground colour string
PROP_SEL_INDEXint idxindex of selected item
PROP_SEL_MODEuwg_sel_tselection mode
PROP_SHADOWunsigned long pixel3D shadow pixel value
PROP_SHADOW_STRchar *color3D shadow colour string
PROP_SHOW_BOUNDARYint showshows boundaries on certain gadgets (vde, layout)
PROP_SIZEint sizesize value for certain gadgets/effects
PROP_SPLIT_DATAint splitnumber of colums
PROP_STATUSint statusstatus for certain gadgets
PROP_STEPPINGint stepincrement/decrement for some gadgets
PROP_STYLEuwg_winstyle_t stylewindow style
PROP_SWALLOW_KEYSint skeystruth value indicating whether the gadget swallows all keystrokes when focused
PROP_TAB_STOPint tstab-stop ordering (for switching focus)
PROP_TENTRYunsigned long pixelbackground pixel value for text-entry boxes
PROP_TENTRY_STRchar *colorbackground colour string for text-entry boxes
PROP_TEXTchar *strtext-entry text
PROP_TIMEOUTint timeouttimeout in milli-seconds
PROP_TOP_INDEXint tidxindex of first displayed item
PROP_WARNING_COLORunsigned long pixel`warning' pixel value
PROP_WARNING_COLOR_STRchar *color`warning' colour string
PROP_VALUEint valvalue for some gadgets
PROP_VISIBLEint visibletruth value indicating whether the gadget is visible
PROP_VISIBLE_VALUEint vvalvisible `value-range' for some gadgets


UWG Types

UWG has various enumerated types for certain properties. In WG, these sorts of things were pre-processor `#define's.

Constant/TypeDescription
uwg_align_ttext alignment
ALIGN_LEFTleft aligned
ALIGN_CENTERcentre aligned
ALIGN_RIGHTright aligned
uwg_btnstyle_tbustrongon style
BUTTON_NORMALordinary style bustrongon
BUTTON_POPUPpopup style bustrongon
uwg_cpref_tpreferable colours
CPREF_FOREGROUNDpreferred foreground colour
CPREF_BACKGROUNDpreferred background colour
CPREF_HIGHLIGHTpreferred highlight colour
CPREF_SHADOWpreferred shadow colour
CPREF_EXTRApreferred `extra' colour
CPREF_TENTRYpreferred text-entry background colour
CPREF_SELBACKpreferred selected background colour
CPREF_SELFOREpreferred selected foreground colour
uwg_layout_tgadget layout
LAYOUT_NONEfixed layout
LAYOUT_FLOAT_LEFTgadget floats left
LAYOUT_FLOAT_RIGHTgadget floats right
LAYOUT_FLOAT_TOPgadget floats towards the top
LAYOUT_FLOAT_BOTgadget floats towards the bottom
LAYOUT_STRETCH_HORIZgadget stretches horizontally
LAYOUT_STRETCH_VERTgadget stretches vertically
uwg_order_titem ordering
ORDER_NONEuse created order
ORDER_ALPHA_ASCENDorder alphabetically, ascending
ORDER_ALPHA_DESCENDorder alphabetically, descending
uwg_sel_tselection mode
SELECT_NONEdo not allow any selection
SELECT_ONEallow one item to be selected
SELECT_MANYallow many items to be selected
uwg_winstyle_twindow style
WINDOW_BORDERnon-resizable with border
WINDOW_BORDERLESSnon-resizable without border
WINDOW_SIZEABLEresizable with border
uwg_winpos_twindow position
WINPOS_EXPLICITuse given position
WINPOS_CENTERplace in the center of the screen
WINPOS_USERwindow-manager/user to place the window
uwg_open_topen-mode constants
OPEN_READopen read-only
OPEN_WRITEopen write-only
OPEN_RWopen read-write
uwg_sel_tselection style constants
SELECT_NONEnothing allowed to be selected
SELECT_ONEallow a single item to be selected
SELECT_MANYallow multiple items to be selected
uwg_scroll_tscrollbar-style constants
SCROLL_HORIZhorizontal scroll-bar
SCROLL_VERTvertical scroll-bar
uwg_order_titem ordering constants
ORDER_NONEuse program-given order
ORDER_ALPHA_ASCENDorder alphabetically, ascending
ORDER_ALPHA_DESCENDorder alphabetically, descending
uwg_visflags_tflags controlling behaviour of UWGVisual
VISFLAG_NONEdefault/unset
VISFLAG_HOLDMSGhold UWGMessage delivery for this gadget
Last modified: 2006-12-31 01:10:09.000000000 +0000 by Fred Barnes [ds] [plain]
Page generated: Sun Apr 28 11:39:35 2013
Valid XHTML 1.0! Valid CSS!