File: file_format.txt

package info (click to toggle)
glade-nonus 0.6.4-5
  • links: PTS
  • area: main
  • in suites: woody
  • size: 12,152 kB
  • ctags: 3,879
  • sloc: ansic: 54,332; sh: 6,839; makefile: 743; sed: 93
file content (459 lines) | stat: -rw-r--r-- 13,859 bytes parent folder | download | duplicates (3)
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
64
65
66
67
68
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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459

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
====

Most project options now have default values. See the section below.

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.


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

Project Options
===============

  name			DESC	: the displayed name of the project.
			TYPE    : string
			DEFAULT : none

  program_name		DESC	: the application binary filename.
			TYPE    : string
			DEFAULT : none

  directory		DESC	: the project directory, relative to the XML
				  file.
			TYPE    : string
			DEFAULT : "" (i.e. the same directory that the XML file
				  is in.)

  source_directory	DESC	: the source code directory, relative to the
				  XML file.
			TYPE    : string
			DEFAULT : "src"

  pixmaps_directory	DESC	: the pixmaps directory, relative to the XML
				  file.
			TYPE    : string
			DEFAULT : "pixmaps"

  language		DESC	: the source code language to use.
			TYPE    : string ("C", "C++", "Ada 95", "Perl", or
				  "Eiffel" - see GladeLanguages[] in
				  glade_project.c)
			DEFAULT : "C"

  gnome_support		DESC	: whether to support Gnome.
			TYPE    : boolean
			DEFAULT : TRUE

C Output Options:

  gettext_support	DESC	: whether to support gettext, i.e. by using
				  the standard _() and N_() macros around all
				  strings.
			TYPE    : boolean
			DEFAULT : TRUE

  use_widget_names	DESC	: whether to set the widget names in the source
				  code (useful for rc files).
			TYPE    : boolean
			DEFAULT : FALSE

  output_main_file	DESC	: whether to output a main.c file, if it
				  doesn't already exist.
			TYPE    : boolean
			DEFAULT : TRUE

  output_support_files	DESC	: whether to output the support files. This may
				  be turned off if the developer is using
				  several Glade XML files, otherwise they may
				  end up with several copies of the support
				  files in the project.
			TYPE    : boolean
			DEFAULT : TRUE

  output_build_files	DESC	: whether to output all the files to build the
				  project, e.g. configure.in, Makefile.am.
				  The developer may be using an alternative
				  method for building.
			TYPE    : boolean
			DEFAULT : TRUE

  backup_source_files	DESC	: whether to backup source files before they
				  are rebuilt, just in case.
			TYPE    : boolean
			DEFAULT : TRUE

  gnome_help_support	DESC	: whether to output support for the Gnome Help
				  system. Currently we just output the
				  GNOME_UIINFO_HELP macro at the top of the
				  Help GnomeUIInfo structs, but we will output
				  a template help file with build files in
				  future.
			TYPE    : boolean
			DEFAULT : FALSE

  main_source_file	DESC	: the file to contain the code to build all the
				  windows/dialogs, relative to the source
				  directory.
			TYPE    : string
			DEFAULT : "interface.c"

  main_header_file	DESC	: the header to go with main_source_file,
				  relative to the source directory.
			TYPE    : string
			DEFAULT : "interface.h"

  handler_source_file	DESC	: the file to contain the signal handler
				  callbacks, relative to the source directory.
			TYPE    : string
			DEFAULT : "callbacks.c"

  handler_header_file	DESC	: the header to go with handler_source_file.
			TYPE    : string
			DEFAULT : "callbacks.h"

  support_source_file	DESC	: the file to contain support functions.
			TYPE    : string
			DEFAULT : "support.c"

  support_header_file	DESC	: the header to go with support_source_file.
			TYPE    : string
			DEFAULT : "support.h"

LibGlade Options:

  output_translatable_strings
			DESC	: whether to output all strings which could be
				  translated into other languages into a
				  special file, to be read by xgettext.
			TYPE    : boolean
			DEFAULT : FALSE

  translatable_strings_file
			DESC	: the file to place the translatable strings
				  in.
			TYPE    : string
			DEFAULT : none

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

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?