INTERNALS 4.68 KB
Newer Older
Paolo Borelli's avatar
Paolo Borelli committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
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).

64 65 66 67 68
 * 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.

Paolo Borelli's avatar
Paolo Borelli committed
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
 * 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