
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.

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


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

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

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

Example file:

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

<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>/home/damon/builder/graphics/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.


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

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 (relative or absolute?).
e.g.
 <bg_pixmap:NORMAL>/home/damon/builder/graphics/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>/home/damon/builder/graphics/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


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

  modifiers, key, signal


Style
-----

  similar to named styles.


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

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