Glade3 internals

~~~~~~~~~~~~~~~~

about this document

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

This is a short description of the designs goals and of the

implementation choices of Glade3. It isn't complete, but

I hope that it may be useful.

 * Note: not only I'm not the original author/designer of 

   glade3, but also I have not touched glade3 for many months.

The only reason why I'm writing this doc is that glade3 development

has been stagnating for a long time... now it seems that there are some

developers interested in resuming work on it, so I thought that it was 

right to put down some notes on what I remember to ease their way

through the glade3 codebase.

Everyone who spots errors and inaccuracies in this doc, or who wants to

add informations to it, should feel free to improve it!

1) Introduction

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

As you probably know the idea behind glade and libglade is to serialize

the description of a Gtk+ GUI to an xml file.

 * libglade takes care of reading such file at runtime and generates

   the interface

 * glade is a tool to create and edit the desired interface in an easy

   way and then automatically serialize it to the xml file.

Glade3 is a complete rewrite of the original glade and takes advantage

of the introspection properties of the GTK+2 toolkit.

2) Design goals

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

Here are some of the goals which were considered when designing glade3

 * allow to easily "plug-in" new sets ("catalogs") of GtkWidgets. For

   instance the collections of GNOME widgets, which was hardcoded in

   glade2, should be provided as an external addition.

   In theory all what is required to add support for an extra collection

   of widgets is some xml describing the widgets and, if needed, a shared

   object which overrides some of the properties of the widgets which

   cannot be correctly handled with introspection. [Note: as of this

   writing this system is not fully functional and the only catalog

   available is the normal GTK+ widget collection]

 * implement full UNDO/REDO for the actions supported by glade

 * implement the glade tools (palette, editor, etc) as widget themselves

   so that it would be possible without too much work to embed them in 

   another program (e.g. an IDE).

 * get rid of code generation. Code generation is considered a bad idea,

   the way to go is to use libglade to dinamically load the GUI from the

   xml file. If someone really wants to have code generation, it really

   belongs in an external program which generates code from the xml file.

 * FIXME: ADD OTHERS

3) File Map

===========

Here is a (not complete) list of the source files of glade3, with a brief

explanation of what they do.

src subdir:

 * main.c - self explanatory, it parses options, loads the available

            catalogs and creates the main window

 * glade-project-window.[ch] - the main window of glade, with menus,

                               toolbar, etc.

                               The GladeProjectWindow struct also

                               contains the general state of the program

                               (e.g. the list of open projects).

                               There is just one instance of this

                               structure.

 * glade-palette.[ch]

   glade-editor.[ch]

   glade-signal-editor.[ch]

   glade-clipboard.[ch]

   glade-clipboard-view.[ch]

   glade-project-view.[ch] - the editing tools offered by glade

 * glade-commands.[ch] - editing actions available in glade.

                         Implements UNDO/REDO.

 * glade-projects.[ch] - object correspong to each project currently open

                         in glade, for instance it contains the list of

                         toplevels widgets and if the project has been

                         modified.

 * glade-widget.[ch] - probably the most important file: each GtkWidget

                       in the project has an associated GladeWidget

                       which contains the name, the properties, the name,

                       the signals etc.

 * glade-catalog.[ch] - a collection of widget classes

 * glade-widget-class.[ch] - a structure describing each type of widget

                             in a catalog.

 * FIXME: add the other files

 * glade-gtk.c: this implements the shared object that contains

                overridden properties for gtk widget catalog.

widgets subdir

 * *.xml: each widget in a catalog has a corresponding xml description.

          At some point it may be worth collapse them in just one file

          per catalog, at the moment they are split in a file per widget

          because at the beginning glade3 required all the properties

          to be described in xml, but now only the properties which

          need special handling are listed