
GQBUILDER
=========

GQBuilder, short for Gnocl/Q Interface Builder, is a GUI builder for the Q
programming language (http://q-lang.sf.net). GQBuilder is based on Q's Tcl/Tk
interface and Peter G. Baum's Gnocl (http://gnocl.sf.net), a very nice Tcl
extension for creating GNOME/GTK+ applications. Thanks to Gnocl, GNOME/GTK+
GUIs for Q applications can be created with GQBuilder quite easily. Simple GUI
designs can often be done in a matter of minutes.

The package also contains the gnocl.q script which provides helper functions
to create Gnocl applications. This script is needed by GQBuilder itself as
well as GQBuilder-generated code, and of course you can also use the
operations of this module in your own Gnocl/Q applications.

The GQBuilder package is free software distributed under the GNU General
Public License (GPL) version 2 or later. Please see the accompanying COPYING
file for details.

While this version of GQBuilder has already been taken through its paces with
Gnocl 0.9.90 and later on Linux, GUI builders are dauntingly complex programs,
so expect some bugs. Please send bug reports, patches and other comments to
the Q mailing list at q-lang.sf.net or mail me directly at
Dr.Graef@t-online.de.


INSTALLATION
============

If you installed Q from a binary package, then GQBuilder is most likely
included in that package so you already have it. To install from the source,
first make sure that your Q installation includes the 'tk' module and that you
have Tcl/Tk and Gnocl installed, GQBuilder depends on those. Then just become
root and run 'make prefix=$prefix install' where $prefix is the install prefix
of your Q installation (usually '/usr/local' or '/usr'). If you omit the
'prefix=$prefix' option then GQBuilder will be installed under '/usr/local'
which is also Q's default installation path. The gnocl.q script is installed
on the Q library path ($prefix/share/q/lib) while the rest of the package goes
into the $prefix/share/q/gqbuilder directory. A link to the gqbuilder.q script
is created in $prefix/bin so that gqbuilder can be executed by just typing
'gqbuilder' on the command line.

NOTE: Gnocl 0.9.91 now also works on Windows, so GQBuilder and the Q Gnocl
interface should work there, too, but this hasn't been tested yet.


QUICK START
===== =====

To run GQBuilder, you need to have Tcl/Tk and Gnocl installed, as well as the
GNOME and GTK+ libraries. The program is invoked as `gqbuilder [filename]'
where `filename' is optional and may denote a Q script containing a GUI design
which was previously saved with GQBuilder.

Documentation still needs to be written, but if you know Gnocl a bit then
using the program should be fairly straightforward. After starting the
GQBuilder program, it initially shows two windows, the main window and the
"toolbox". The main window is split into an upper pane which displays the
widget tree, and a lower pane which shows the attributes a.k.a. options of the
widget currently selected in the widget tree. It also contains the menu,
toolbar and statusbar of the application. The toolbox is a kind of widget
toolbar which gives quick access to the different widget types.

Start out by adding a toplevel window. To these ends, hold the mouse over the
items in the toolbox, they will then show a short description as a tooltip so
that you can learn what the different items are (you can also switch the
toolbox to text buttons in the "Widget" menu of the main window, if you prefer
that). Locate the "Window" button at the end of the "Container" section of the
toolbox and click on it. Note that the new window instantly appears on your
desktop, and a new entry for the window is now shown in the widget tree.
Select the "window" entry in the widget tree (click on it) and add another
"box" container to it (click on the "Box" icon in the toolbox). (The layout
direction as well as the frame setup of newly created boxes can be controlled
with the small strip of buttons at the end of the statusbar of the GQBuilder
main window, or with the corresponding operations in the "Widget" menu.) Next
select the new "box" container and start adding other widgets to it, like
buttons, display widgets, entries, etc. Whatever you choose, the display of
the created toplevel window will be updated accordingly and you can test-drive
your new application right away.

Right-clicking on a widget in the widget tree selects the widget and pops up a
menu with general editing operations and specific options for that widget.
Right-clicking on an attribute in the lower pane gives you options for editing
the selected attribute. You can also move around widgets in the tree by
cutting, copying and pasting widgets. These operations use the clipboard as
intermediate storage, so that you can also cut/copy/paste widgets between
different instances of GQBuilder. There are actually two different paste
operations, "Paste" which inserts the copied widget as a new child at the end
of the selected widget, and "Paste Here" which inserts the widget right before
the selected widget and thus also allows you to rearrange the order of the
children of a container. (Due to the inner workings of the Gnocl API, "Paste
Here" is much more costly than "Paste" as the entire list of children
following the inserted widget has to be recreated.) Moreover, in the "Edit"
menu you can also find operations for defining and inserting "compound
widgets" (complete widget subtrees which are used frequently, so it makes
sense to store them under a name), and for finding widgets in the tree
according to different search criteria. Last but not least, there's an
unlimited Undo/Redo facility which is handy if you accidentally delete
something or an edit command doesn't quite produce the results that you
wanted.

When you're done with your design, save it to a file. The written file is an
ordinary Q script which can be run directly with the Q interpreter, and you
can also edit the file to add callbacks and other Q code needed by your
application. (Just make sure that you stay away from the "#!DATA" section in
the script, this is where GQBuilder actually stores the widget tree.) You can
also run the application from GQBuilder using the "Run" command in the menu or
the toolbar.

Ok, hopefully this is enough to get you started. Some examples to play with
can be found in the examples subdirectory.


ACKNOWLEDGEMENTS
================

Thanks are due to Peter G. Baum for creating Gnocl. Without it, a specialized
GUI builder for Q probably would have never come into being. The widget icons
used in GQBuilder's toolbox were pilfered from the excellent Glade GUI builder
(http://glade.gnome.org), thanks to the Glade team for those.


Enjoy! :)

September 2007
Albert Graef
Dr.Graef@t-online.de
