
                     DUI -- Data Under the Interface
                   (aka DWI -- Data With Interaction)
                   ----------------------------------

This is a fairly simple environment for quickly creating data-driven 
applications, that is, graphical applications that manipulate
and show info from a database.  This environment differs from others in
that it is focused on native GTK/Gnome support through the Glade GUI 
designer, and thus allows you to build user interfaces as elegant as 
you can make them in Glade.

At this point, this system has enough features to be adequate for creating 
basic form-editing and reporting applications.  Multiple SQL database
vendors are supported through ODBC (http://www.iodbc.org) or libdbi
(http://libdbi.sourceforge.net) drivers.  There is very simple db-driver 
infrastructure so its easy to support for additional SQL API's.
The system supports all of the basic Gtk widgets, and an additional
half-dozen Gnome I/O widgets, such as GnomeDateEntry.

DWI is powered by an 'engine' that has some fairly generic proceedures
for mapping 'fields', such as sql table columns or widget values,
between each other, and also between other things, such as objects,
hash tables and etc.   This engine is currently being expanded
so that it becomes possible to easily add support for all kinds
of new object systems: i.e. for the engine to become a generic
re-mapper between not just SQL and GTK but between many differnt
types of object systems and data sources/sinks.

Built on top of this engine is a DWI application that parses an
XML-based file, the "DWI file", that describes the connections between
glade widgets and database tables.  Currently, the only way to create
DWI files is by hand.  Unfortunately, this can be a fairly long and
laborious process itself, especially when creating something a bit
more sophisticated.  In the future, we hope to have an extension to
Glade, or possibly an extension to a database-browsing tool that will
allow you to graphically make such connections.
(Work has begun on such a tool, written in DWI itself).

The grim reality is that DWI won't ever become popular without a
graphical designer.  Although fairly complex apps can be readily
created using DWI, it does have a non-trivial learning curve. When we say "can
be created quickly", we mean "days" or "weeks", as opposed to "months" for
traditional database application development cycles.   Graphical RAD tools have
a way of being brainlessly pleasent to use, and give the impression of an even
faster development cycle, even though the learning curve is identical.

Note that the design of the XML format is sufficiently generic that it 
is not directly tied to Glade.  It is envisioned that it could be used
to create data-driven web pages.  That is, Glade is currently the only
GUI driver, but other drivers for other GUI's should be possible.

==================================
The 'app' directory contains the DWI XML-file parser and the stand-alone
DWI application.  If you just want to run a pure DWI-XML app, use this
app.

A number of examples, both of pure DWI scripts, and DWI-to-pre-existing
GTK-app examples can be found in the 'examples' directory.  The
'testbasic.dui' script provides an extensive heavily-documented 
starter example.

The 'db_drivers' directory contains the iODBC and libdbi support.
To compile for one or the other, modify the Makefile to -DUSE_ODBC
and/or -DUSE_LIBDBI.

The 'src' directory contains the sources to the DWI engine.  The engine
does *not* use XML; it provides the infrastructure for making the 
mapping between widgets and databases possible.  These sources are
being structured so that DWI can be embedded in other applications.

==================================
Compiling & Pre-requisites

DWI requires libglade2 (to get at the glade widgets).
DWI requires glib-2.0 (in order to bootstrap itself).
DWI requires gnome-2.x
DWI requires libxml2
DWI requires qof  (http://qof.sourceforge.net)
DWI requires gob2 (in order to run the bike-calc example)

If you don't have the above installed, not much will happen.

To build, type "./autogen.sh" and then, "make"

==================================

A pre-alpha attempt at building a graphical editor for DWI can be found
in glade/connector.*  It doesn't do much, yet.

==================================
Theoretical comments:
---------------------
Note that the DWI design is fundamentally "declarative"; i.e. it works
like a declarative language.  The nature of the interface is 
declared in the XML file.  The "run-dwi" evaluator reads in this static
file, sets up structures that correspond to the XML declaration.  Then
the evaluator goes into the main loop, and signals and events make 
everything happens according to the pre-determined definitions in the
XML file.   There is no run-time interpretation. There is no 'just-in-time'
compilation.  It just runs along the fixed paths,  where each path had
been pre-defined in the XML file, and each run-through is initiated by 
the user clicking or typing in the GUI.


News
====
For more recent news, see the NEWS file in this directory!


DWI version 0.5.0 March 2004
============================
Version 0.5.0 is a port of DWI to the gnome-2.x libraries.  It
also includes a small number of fixes, including an effort to
make sure that all of the example programs actually work as 
documented.

This version will not compile with or link to the gnom-1.4 libraries;
if you need gnome-1.4 support, you need to stick to version 0.4.0

DWI version 0.4.0 October 2003
==============================
Version 0.4.0 features a major redesign of much of the guts of DWI.
The goal of the redesign is to allow DWI to better support entirely
new object systems, and not just SQL and Gtk.  The proximate goal
was to allow DWI to be possibley incorporated into GnuCash (maybe).

This version does not add any new XML file format features, nor
does it support any new widgets.  It does however add support
for the libdbi SQL database interface (libdbi.sourceforge.net).


DWI and GnuCash -- Linas Vepstas September 2003
===============================================

I'm currently tearing up the guts of "DWI" http://dwi.sourceforge.net
DWI was originally (and still is) a way of 'quickly' developing glade
apps that are hooked to an SQL db.  I wrote a kind of tracking tool
using the thing for a client (tracking maintenance of pipes & pumps),
so DWI has been vetted with a 'real life' project.  I've been planning
on creating a whiz-bang open source bug tracker & etc with it, but
never got around to it.
                                                                                
My tear-up of the guts of DWI is turning it into a generic 'data pump'.
It can suck data out of one place and stick it in somewhere else.
Originally, the two places it worked with are sql tables and gnome
widgets, but its in fact far more general than that.  In particular,
I'm planning on prototyping a hookup to the GnuCash objects (aka qof
objects) real soon now.  (which is why the qof objects get setters as
well as getters in the CVS tree).
                                                                                
Part of the beauty of the thing is it does not force a 1-to-1 mapping
between SQL tables and objects.  The mappings can go any which way:
data from different sql tables can be joined and pushed out to various
assortments of widgets (including columned widgets such as ctree/clist).
So its kind of a realization of my long standing complaint that I should
be able to press a button, and bingo, some object turns into an SQL
record(s), and back.
                                                                                
I'm not done with the DWI internal tearup yet, but soon ... After that,
I'll start prototyping integration with the qof objects (probably within
the DWI cvs tree).  When I'm done with that, I'm going to try to unleash
the thing to create teh backend for the GnuCash business Objects.  My
goal is to have very very little code for this: mostly, a specification
of the SQL tables, and a mapping: 'this business object field goes into
that sql field', and that's that.  The goal/side effect is that this
should make adding new objects to GnuCash backend 'real easy'.
                                                                                

DWI Initial Announce -- Linas Vepstas March 2002
================================================ 
DWI went live in March 2002, with above project description.

