
The Glade XML File Format
=========================

This file documents the Glade XML file format, used when saving and loading
projects in Glade. This format is also intended to be read by programs which
convert it into source code in various languages.

XML was chosen as it is a language-independent format which is likely to
become very popular in the near future. Parsers will be widely available,
and many programmers are already familiar with the basic syntax due to HTML.
It may also prove useful for internationalization at some point.

There is no DTD at present, though this may be added in future if useful.
(But due to the way we use XML, a DTD may not be very useful when support
for external widgets with arbitrary properties is added, since we use
property names as XML tag names.)

If you spot anything that doesn't conform to XML, please let me know.


NEWS
====

Since ':' is used in XML tags for namespaces, we now use '-' instead for the
style tags, e.g. instead of 'fg:NORMAL' we now use 'fg-NORMAL'.

I've added a 'last_modification_time' tag for the signals. It uses the
standard RFC1123 format, e.g. 'Sun, 06 Nov 1994 08:49:37 GMT'.
It's used so we can simply append new signal handler prototypes, instead of
completely overwriting the file each time the source code is written.
It is only updated if the signal name, handler or data changes, since
the object and after fields are only used when connecting the signal and
do not affect the prototype.

Styles aren't fully supported in Glade, so you can skip those bits for now.

--------------------------------------------------------------------------

Basic File Structure
====================

1. XML version
2. Document root element - "<GTK-Interface>"
3. Project options.
4. Named styles - which can be shared among several widgets.
5. UI Components - hierarchies of widgets.
6. End of document - "</GTK-Interface>"

Example file:

<?xml version="1.0"?>
<GTK-Interface>

<project>
  <name>Project70</name>
  <program_name>project70</program_name>
  <directory></directory>
  <source_directory>src</source_directory>
  <pixmaps_directory>pixmaps</pixmaps_directory>
  <language>Ada 95</language>
  <gnome_support>True</gnome_support>
  <gettext_support>True</gettext_support>
  <use_widget_names>False</use_widget_names>
  <output_main_file>True</output_main_file>
  <output_support_files>True</output_support_files>
  <output_build_files>True</output_build_files>
  <backup_source_files>True</backup_source_files>
  <main_source_file>interface.c</main_source_file>
  <main_header_file>interface.h</main_header_file>
  <handler_source_file>callbacks.c</handler_source_file>
  <handler_header_file>callbacks.h</handler_header_file>
  <support_source_file>support.c</support_source_file>
  <support_header_file>support.h</support_header_file>
  <translatable_strings_file></translatable_strings_file>
</project>

<style>
  <style_name>MyStyle</style_name>
  <fg-NORMAL>198,80,111</fg-NORMAL>
  <fg-PRELIGHT>181,93,139</fg-PRELIGHT>
  <bg-NORMAL>131,214,165</bg-NORMAL>
  <bg_pixmap-NORMAL>clist.xpm</bg_pixmap-NORMAL>
</style>

<widget>
  <class>GtkWindow</class>
  <name>window1</name>
  <title>window1</title>
  <position>GTK_WIN_POS_NONE</position>
  <allow_shrink>False</allow_shrink>
  <allow_grow>True</allow_grow>
  <auto_shrink>False</auto_shrink>

  <widget>
    <class>GtkTable</class>
    <name>table1</name>
    <homogeneous>False</homogeneous>
    <row_spacing>0</row_spacing>
    <column_spacing>0</column_spacing>
    <style_name>MyStyle</style_name>
    <Signal>
      <name>need-resize</name>
      <handler>on_table1_need-resize</handler>
    </Signal>
  </widget>
</widget>

</GTK-Interface>


This file has one named style, "MyStyle", and one component - a window with
a table in it. The table uses the style "MyStyle", and also has a signal
handler associated with it.

All filenames are specified relative to the XML file, except pixmap
files which should be in the project's pixmaps directory.


--------------------------------------------------------------------------

Named Styles
============

These are used to share styles among a number of widgets. Widgets can use one
of the named styles, or can have their own individual style.

A special named style, "Default", specifies the default style to apply to
widgets which have no style set explicitly (or via style propagation.)
The "Default" style should appear first, if it is defined, so that styles
can be created as they are read in. If no "Default" style is defined, then
the GTK default style should be used.

Styles have 4 colours ('fg', 'bg', 'text' & 'base'), and a background pixmap
for each of the 5 widget states ( "NORMAL", "ACTIVE", "PRELIGHT", "SELECTED",
& "INSENSITIVE").

They may also have a font. Note that only the properties which differ from the
default values are written to the file.


Colours are defined as "red,green,blue" with values ranging from 0-255.
e.g.
 <fg-NORMAL>198,80,111</fg-NORMAL>

This is the foreground colour for the GTK_STATE_NORMAL widget state, with
red=198, green=80 and blue=111.


Background pixmaps are defined as filenames. The pixmap file should be in the
project's pixmaps directory.
e.g.
 <bg_pixmap-NORMAL>clist.xpm</bg_pixmap-NORMAL>

This is the background pixmap for the GTK_STATE_NORMAL widget state.


Fonts are defined as X Logical Font Description fontnames,
e.g.
 <style_font>-adobe-utopia-bold-r-normal-*-*-160-*-*-p-*-iso8859-1</style_font>


Named style example:

<style>
  <style_name>MyStyle</style_name>
  <fg-NORMAL>198,80,111</fg-NORMAL>
  <fg-PRELIGHT>181,93,139</fg-PRELIGHT>
  <bg-NORMAL>131,214,165</bg-NORMAL>
  <bg_pixmap-NORMAL>clist.xpm</bg_pixmap-NORMAL>
</style>

--------------------------------------------------------------------------

UI Components
=============

The UI Component - windows, dialog boxes and popup-menus - are stored as
hierarchies of widgets. Each widget has a number of properties, and optionally
a style, accelerators, and signal handlers. Children of the widget appear
last, and are indented for clarity. (The children are placed after the
widget's properties so that the widgets can be easily created as the file is
read.)
e.g.

<widget>
  <class>GtkWindow</class>
  <name>window1</name>
  <title>window1</title>
  <position>GTK_WIN_POS_NONE</position>
  <allow_shrink>False</allow_shrink>
  <allow_grow>True</allow_grow>
  <auto_shrink>False</auto_shrink>

  <widget>
    <class>GtkTable</class>
    <name>table1</name>
    <homogeneous>False</homogeneous>
    <row_spacing>0</row_spacing>
    <column_spacing>0</column_spacing>
    <style_name>MyStyle</style_name>
    <Signal>
      <name>need-resize</name>
      <handler>on_table1_need-resize</handler>
    </Signal>
  </widget>
</widget>


Some properties have default values, so that we can cut down on unnecessary
output. (It is likely that more default values will be used in future.)


Basic Properties
----------------

  class			- The widget class, e.g. GtkLabel.
			  The special value, 'Placeholder' indicates that this
			  is a placeholder (i.e. an 'empty slot') in the
			  interface. This means that the interface hasn't been
			  completed, so a source code writer could issue a
			  warning, though it could ignore the placeholder and
			  carry on creating the rest of the interface.

  (These appear on the 'Basic' page of Glade's property editor)

  name			- The name of the widget, unique (in window/project?)
  x			- The x coordinate of the widget, only applicable to
			  toplevel widgets and widgets in fixed containers.
  y			- The y coordinate of the widget, only applicable to
			  toplevel widgets and widgets in fixed containers.
  width			- The width of the widget.
  height		- The height of the widget.
  visible		- If the widget is initially shown.
  sensitive		- If the widget is sensitive.
  tooltip		- The tooltip to show for the widget.
  can_default		- If the widget should have CAN_DEFAULT set.
  has_default		- If the widget should grab the default.
  can_focus		- If the widget should have CAN_FOCUS set.
  has_focus		- If the widget should grab the focus.
  events		- Which events the widget wants to receive.
  extension_events	- Which extension events to receive.


  Property		Type		Default

  name			string		none
  x			int		none/-1
  y			int		none/-1
  width			int		none/-1
  height		int		none/-1
  visible		bool		TRUE
  sensitive		bool		TRUE
  tooltip		string		none
  can_default		bool		FALSE
  has_default		bool		FALSE
  can_focus		bool		FALSE
  has_focus		bool		FALSE
  events		int		0
  extension_events	string		GDK_EXTENSION_EVENTS_NONE


Special Properties According To The Widgets Parent
--------------------------------------------------

  (These appear on the 'Place' page of Glade's property editor)

Widgets in a table have these additional properties, which map to the arguments
used in the gtk_table_attach() function.

  left_attach, right_attach, top_attach, bottom_attach
  xpad, ypad, xexpand, yexpand, xshrink, yshrink, xfill, yfill

For widgets in a box (but not button boxes):

  padding, expand, fill, pack (default = "GTK_PACK_START")


These properties are placed in the 'child' section, e.g.

    <widget>
      <class>GtkLabel</class>
      <name>label1</name>
      <child>
        <left_attach>0</left_attach>
        <right_attach>1</right_attach>
        <top_attach>0</top_attach>
        <bottom_attach>1</bottom_attach>
        <xpad>0</xpad>
        <ypad>0</ypad>
        <xexpand>True</xexpand>
        <yexpand>True</yexpand>
        <xshrink>False</xshrink>
        <yshrink>False</yshrink>
        <xfill>True</xfill>
        <yfill>True</yfill>
      </child>
      <label>label1</label>
      <justify>GTK_JUSTIFY_CENTER</justify>
      <xalign>0.5</xalign>
      <yalign>0.5</yalign>
      <xpad>0</xpad>
      <ypad>0</ypad>
    </widget>


Signals
-------

  name, handler, object, after, data, last_modification_time


Accelerators
------------

  modifiers, key, signal


Style
-----

  similar to named styles.


Special Widgets
---------------

Dialog buttons, clist titles, notebook tabs? scrolled window?