GtkBuilder status

[Johan Dahlin <jdahlin async com br>]

Hi

Over the last couple of weeks Henrique Romano and I have been working on
GtkBuilder, a UI constructor intended for inclusion in GTK+.
I'd like to discuss the API and some of the decisions before making the
code available for public review.

This work has been sponsored by Nokia.

We've made a couple of important decisions:
* GMarkup based parser which parses and creates the object tree in one step
  go instead of saprving a whole tree in memory.
* breaking xml format compatibility with libglade
* not supporting any deprecated or broken widgets
* only supporting menubar and toolbar construction through GtkUIManager
* custom/fake properties are not intended to be supported. Instead
  functionality relying on them needs to be rewritten.

We also intend to write a script which will help convert a file
saved by libglade into a file which can be loaded by GtkBuilder.

XML Format
==========
Versus libglade
<glade-interface> is renamed (to interface or builder, TBD)
<widget> becomes <object>
<object> has a new attribute, constructor
<object> can have type specific child tags after the <child> child tag.
<child> has a new attribute, type
<require> is removed
Support for atk is not implemented yet, but it will be different
from the way libglade does it.

GtkBuilder API
==============
Against the libglade api
get_widget becomes get_object
get_widget_prefix becomes get_objects and the argument is removed.
filename is no longer an attribute, instead a property is added
a domain property is added
a signal finish is added
the virtual method lookup_type is removed
set_custom_handler is removed
construct is removed

GtkBuildable
============
Is an interface which an object needs to implement if it wishes to have
a specialized behavior:
* set_name, to be able to reuse the name set by the builder
* add, for adding a child to a parent
* construct_child, for specialized construction, used by mainly by widgets
  created by a GtkUIManager
* custom_tag_start/custom_tag_finish: for custom tags, see below
* set_child_property, used to set child/packing properties in a container.

Type specific tags
==================
GtkUIManager
<ui> tag which embeds the normal GtkUIManager definition.

GtkListStore
<columns> which has a child tag called <column> with an attribute called
type which value is the type name of the column.

GtkTreeStore
<columns> identical to GtkListStore

GtkSizeGroup
<widgets> which has a child tag <widget> with an attribute called name
which is the name of the widget which is part of the sizegroup.
<widgets>
  <widget name="entry1"/>
  <widget name="entry2"/>
</widgets>

GtkTreeModel will add one or several tags to allow data to be specified in
the xml format.
GtkCellRenderer or GtkTreeViewColumn will gain an additional tag to allow
attributes to be set.

Comments, suggestions?

-- 
Johan Dahlin <jdahlin async com br>
Async Open Source

/* gtkbuilder.h
 * Copyright (C) 2006 Async Open Source
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */
#ifndef __GTK_BUILDER_H__
#define __GTK_BUILDER_H__

#include <glib-object.h>

G_BEGIN_DECLS

#define GTK_TYPE_BUILDER                 (gtk_builder_get_type ())
#define GTK_BUILDER(obj)                 (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_BUILDER, GtkBuilder))
#define GTK_BUILDER_CLASS(klass)         (G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_BUILDER, GtkBuilderClass))
#define GTK_IS_BUILDER(obj)              (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_BUILDER))
#define GTK_IS_BUILDER_CLASS(klass)      (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_BUILDER))
#define GTK_BUILDER_GET_CLASS(obj)       (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_BUILDER, GtkBuilderClass))

typedef struct _GtkBuilder        GtkBuilder;
typedef struct _GtkBuilderClass   GtkBuilderClass;

struct _GtkBuilder
{
  GObject parent;
};

struct _GtkBuilderClass
{
  GObjectClass        parent_class;
  

  void (*finish) (GtkBuilder *);
  
  /* Padding for future expansion */
  void (*_gtk_reserved1) (void);
  void (*_gtk_reserved2) (void);
  void (*_gtk_reserved3) (void);
  void (*_gtk_reserved4) (void);
};


GType          gtk_builder_get_type           (void) G_GNUC_CONST;
GtkBuilder*    gtk_builder_new                (const gchar *filename,
					       const gchar *domain);
GtkBuilder*    gtk_builder_new_from_buffer    (const gchar *buffer,
					       gsize length,
					       const gchar *domain);
GObject*       gtk_builder_get_widget         (GtkBuilder *builder,
					       const gchar *name);
GSList*        gtk_builder_get_widgets        (GtkBuilder *builder);
const gchar*   gtk_builder_get_name           (GtkBuilder *builder,
					       GObject *object);
void           gtk_builder_signal_autoconnect (GtkBuilder *builder);

G_END_DECLS

#endif /* __GTK_BUILDER_H__ */

/* gtkbuildable.h
 * Copyright (C) 2006 Async Open Source
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#ifndef __GTK_BUILDABLE_H__
#define __GTK_BUILDABLE_H__

#include <glib/gmarkup.h>
#include <gtk/gtktypeutils.h>

G_BEGIN_DECLS

#define GTK_TYPE_BUILDABLE            (gtk_buildable_get_type ())
#define GTK_BUILDABLE(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_BUILDABLE, GtkBuildable))
#define GTK_BUILDABLE_CLASS(obj)      (G_TYPE_CHECK_CLASS_CAST ((obj), GTK_TYPE_BUILDABLE, GtkBuildableIface))
#define GTK_IS_BUILDABLE(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_BUILDABLE))
#define GTK_BUILDABLE_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GTK_TYPE_BUILDABLE, GtkBuildableIface))

typedef struct _GtkBuildable      GtkBuildable; /* Dummy typedef */
typedef struct _GtkBuildableIface GtkBuildableIface;

struct _GtkBuildableIface
{
  GTypeInterface g_iface;

  /* virtual table */
  void     (* set_name)           (GtkBuildable *buildable,
				   const gchar  *name);
  void     (* add)                (GtkBuildable *buildable,
				   GObject      *child);
  gboolean (* set_property)       (GtkBuildable *buildable,
				   const gchar  *name,
				   const gchar  *value);
  void     (* set_child_property) (GtkBuildable *buildable,
				   GObject      *child,
				   const gchar  *name,
				   const gchar  *value);
  GObject *(* construct_child)    (GtkBuildable *buildable,
				   const gchar  *name);
  gboolean (* custom_tag_start)   (GtkBuildable *buildable,
				   const gchar  *tagname,
				   const GMarkupParser *parser,
				   gpointer     *data);
  void     (* custom_tag_end)     (GtkBuildable *buildable,
				   const gchar  *tagname,
				   gpointer      data);
};


GType     gtk_buildable_get_type              (void) G_GNUC_CONST;

void      gtk_buildable_set_name              (GtkBuildable        *buildable,
					       const gchar         *name);
const gchar * gtk_buildable_get_name          (GtkBuildable        *buildable);
void      gtk_buildable_add                   (GtkBuildable        *buildable,
					       GObject             *child);
gboolean  gtk_buildable_set_property          (GtkBuildable        *buildable,
					       const gchar         *name,
					       const gchar         *value);
void      gtk_buildable_set_child_property    (GtkBuildable        *buildable,
					       GObject             *child,
					       const gchar         *name,
					       const gchar         *value);
GObject * gtk_buildable_construct_child       (GtkBuildable        *buildable,
gboolean  gtk_buildable_custom_tag_start      (GtkBuildable        *buildable,
					       const gchar         *tagname,
					       const GMarkupParser *parser,
					       gpointer            *data);
void      gtk_buildable_custom_tag_end        (GtkBuildable        *buildable,
					       const gchar         *tagname,
					       gpointer             data);
						  
G_END_DECLS

#endif /* __GTK_BUILDABLE_H__ */