
This file will contain info for developers of Glade.

Overview
========

Describe GbWidgets

Describe structs, file formats

Writing source code - use same style as GTK (& GNU), i.e. the standard output
of GNU indent.



Brief Description of the Glade Source Files
===========================================

Main files:

  project.c	  - the main project window & all its functions.
  palette.c	  - the widget palette & its functions - very simple.
  property.c	  - the property window & all its functions.

  editor.c	  - the bulk of the user interface editing code.
  gbwidget.c	  - functions for manipulating the GbWidgets.

  glade_keys_dialog.c
		  - a dialog box which shows the list of GDK keysyms to
		    select for accelerators (encapsulated as a widget).
  glade_menu_editor.c
		  - a dialog box for editing menubars/popup menus
		    (encapsulated as a widget).
  tree.c	  - the window showing a hierarchical view of the widgets.

  load.c	  - functions used when loading project files.
  save.c	  - functions used when saving project files.
  source.c	  - functions used when writing C source code.

  gtkfontsel.c    - My GtkFontSelection/Dialog widgets, which will be in
		    GTK 1.1.

Simple additional files:

  gbwidgetarray.c - array of names of all GbWidgets available + pointers to
		    their initialization functions.
  keys.c	  - array of Gdk keysyms which can be used for accelerators.
  utils.c	  - a few utility functions, currently 3 simple dialog boxes.

  gb.h		  - this is included by all gbwidget source files and includes
		    all the glade header files. (It is used so that we don't
		    have to change every gbwidget source file each time a new
		    header file is added.)

  palettebutton.c - basically a copy of the GtkRadioButton which doesn't
		    display the borders all the time, so it looks nicer.
		    GTK 1.1 supports different styles, so when we move to
		    that we can get rid of this.

GbWidgets
=========

Each file in gbwidgets/ directory corresponds to one GtkWidget, and includes
functions for creating a new widget, getting & setting the properties
particular to that widget, adding items to the popup context-sensitive menus,
and writing the C source code.

I've used a flat structure (i.e. GbWidgets can't have subclasses/superclasses)
for simplicity. A class structure may have eliminated some duplicated code,
but would have been more complex to set up. Maybe in future...

Of course, if GTK had support for reflection then a lot of the GbWidgets'
code would be unnecessary - much of it could be handled in a generic way.
(But its difficult to see how much without getting it all working!)


GbWidgetData
============

Each widget has a GbWidgetData struct which contains extra information
for the widget. For example, it holds flags specifying whether the widget
should be visible and whether it should grab the focus & the default.
It also contains a list of accelerators and signals added to the widget.

It may also contain the widget's size and position, though this depends on
where the widget is used in the interface. For most widgets the position
is set by the parent container, but for toplevel windows and widgets in
fixed containers, the position can be set explicitly.


Properties
==========

  The property hashes for looking up value widgets, ( + labels & buttons)
  Storing values of properties in the data hash of the value widget


'Placeholders'
==============

Placeholders are used to represent spaces in boxes/tables etc. into which a
widget can be placed by the user.

The macro GB_WIDGET_IS_PLACEHOLDER(widget) can be used to see if the
widget (a GtkWidget*) is a placeholder.


** 'Holding widgets'
** =================
** 
** A holding widget is a GTKEventBox which is placed above a widget in the
** interface being designed so that we can capture X events aimed at widget.
** This is necessary since not all GtkWidgets have X Windows, and hence would
** not normally receive all the necessary events.
** 
** The macro GB_WIDGET_IS_HOLDING_WIDGET(widget) can be used to see if the
** widget (a GtkWidget*) is a holding widget.

I've got rid of holding widgets now, since they were causing too much trouble.
We now use the widget tree exactly as it will be in the finished interface.
We need to be a bit more intelligent when we receive mouse events, to see if
they are intended for widgets with no windows, but this is much easier than
checking for holding widgets all over the place.


'GbStyles'
==========

The GbStyle struct stores information about styles used for widgets created
in Glade. GbStyles can be named so that they can be easily shared between
widgets. The struct also stores the font specification string and the
background pixmap filenames, so that the style can be reconstructed later.

Each widget has a pointer to a GbStyle in its GbWidgetData struct. There are
also two relevant flags in the GbWidgetData -
  GB_STYLE_IS_UNNAMED - if the widget is supposedly using an unnamed GbStyle.
			Note: the widget may actually be using a named GbStyle,
			but we only create new unnamed GbStyles if the widget's
			style is changed. This is done because all widgets are
			initially created with an unnamed style so users can
			edit each widgets style individually, but we don't
			want to create individual GbStyles for all widgets
			since most will not be changed.
  GB_STYLE_PROPAGATE  - if the widget's GbStyle is propagated to its
			descendants. But it won't override a descendant
			widget's GbStyle if that has been set explicitly.

Note: A GtkStyle may be shared between GbStyles. ?

This code is unfortunately quite confusing at present. Most of it is in
apply_style() in gbwidget.c and in the functions to do with the style dialog,
after show_style_dialog() in property.c.



Damon, 26 September 1998.
