Hi,
During the Gtk+ developer meeting today it was decided that there will be a
final GtkBuilder discussion before it gets committed to trunk.
The current plan is that there will be a new developer release in the end of
the week, most likely on friday and that GtkBuilder is going to be included
in that release.
I'd like this discussion to be focus on the Public API. I've included the
two new public headers (gtkbuilder.h and gtkbuildable.h) with the API
documentation embedded.
Suggestions and questions about the documentation are also welcome, but
remember that the documentation is still very much open for changes during
the next couple of weeks, before the final release of 2.12.
I've also attached a .glade file which demonstrates some of the new
capabilities.
gtkbuilder.h
============
GtkBuilder is a replacement for the GladeXML found in the libglade library.
It is responsible for parsing a GtkBuilder UI definition and constructing
the object tree from that definition, usually a user interface.
This is the API which applications are going to use.
typedef enum
{
GTK_BUILDER_ERROR_INVALID_TYPE_FUNCTION,
GTK_BUILDER_ERROR_UNHANDLED_TAG,
GTK_BUILDER_ERROR_MISSING_ATTRIUTE,
GTK_BUILDER_ERROR_INVALID_ATTRIBUTE,
GTK_BUILDER_ERROR_INVALID_TAG
} GtkBuilderError;
struct _GtkBuilder
{
GObject parent;
GtkBuilderPrivate *priv;
};
struct _GtkBuilderClass
{
GObjectClass parent_class;
GType (* get_type_from_name) (GtkBuilder *builder,
const char *typename);
/* 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;
/**
* gtk_builder_new:
*
* Creates a new builder object.
*
* Return value: a new builder object.
*
* Since: 2.12
**/
GtkBuilder* gtk_builder_new (void);
/**
* gtk_builder_add_from_file:
* @buildable: a #GtkBuilder
* @filename: the name of the file to parse
* @error: return location for an error
*
* Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder UI
definition</link> and
* merges it with the current contents of @builder.
*
* Returns: A positive value on success, 0 if an error occurred
*
* Since: 2.12
**/
guint gtk_builder_add_from_file (GtkBuilder *builder,
const gchar *filename,
GError **error);
/**
* gtk_builder_add_from_string:
* @builder: a #GtkBuilder
* @buffer: the string to parse
* @length: the length of @buffer (may be -1 if @buffer is nul-terminated)
* @error: return location for an error
*
* Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder UI
definition</link> and
* merges it with the current contents of @builder.
*
* Returns: A positive value on success, 0 if an error occurred
*
* Since: 2.12
**/
guint gtk_builder_add_from_string (GtkBuilder *builder,
const gchar *buffer,
gsize length,
GError **error);
/**
* gtk_builder_get_object:
* @builder: a #GtkBuilder
* @name: name of object to get
*
* Return value: GObject or %NULL if it could not be found in the object tree.
*
* Since: 2.12
**/
GObject* gtk_builder_get_object (GtkBuilder *builder,
const gchar *name);
/**
* gtk_builder_get_objects:
* @builder: a #GtkBuilder
*
* Return value: a newly-allocated #GSList containing all the objects
* constructed by GtkBuilder instance.
*
* Since: 2.12
**/
GSList* gtk_builder_get_objects (GtkBuilder *builder);
/**
* gtk_builder_set_translation_domain:
* @builder: a #GtkBuilder
* @domain: the translation domain or %NULL
*
* Sets the translation domain and uses dgettext() for translating the
* property values marked as translatable from an interface description.
* You can also pass in %NULL to this method to use gettext() instead of
* dgettext().
*
* Since: 2.12
**/
void gtk_builder_set_translation_domain (GtkBuilder *builder,
const gchar *domain);
/**
* gtk_builder_get_translation_domain:
* @builder: a #GtkBuilder
*
* Return value : the translation domain. This string is owned
* by the builder object and must not be modified or freed.
*
* Since: 2.12
**/
const gchar* gtk_builder_get_translation_domain (GtkBuilder *builder);
/**
* GtkBuilderConnectFunc:
* @builder: a #GtkBuilder
* @object: a GObject subclass to connect a signal to
* @handler: name of the handler
* @object: GObject, if non NULL, use g_signal_connect_object.
* @after: if %TRUE use with g_signal_connect_after.
* @data: user data
*
* This is the signature of a function used to connect signals. It is used
* by the gtk_builder_connect_signals() and gtk_builder_connect_signals_full()
* methods. It is mainly intented for interpreted language bindings, but
* could be useful where the programmer wants more control over the signal
* connection process.
*
* Since: 2.12
*/
typedef void (*GtkBuilderConnectFunc) (GtkBuilder *builder,
const gchar *handler_name,
GObject *object,
const gchar *signal_name,
GObject *connect_object,
gboolean after,
gpointer user_data);
/**
* gtk_builder_connect_signals:
* @builder: a #GtkBuilder
*
* This method is a simpler variation of gtk_builder_connect_signals_full().
* It uses #GModule's introspective features (by opening the module %NULL) to
* look at the application's symbol table. From here it tries to match
* the signal handler names given in the interface description with
* symbols in the application and connects the signals.
*
* Note that this function will not work correctly if #GModule is not
* supported on the platform.
*
* Since: 2.12
**/
void gtk_builder_connect_signals (GtkBuilder *builder);
/**
* gtk_builder_connect_signals_full:
* @builder: a #GtkBuilder
* @func: the function used to connect the signals.
* @user_data: arbitrary data that will be passed to the connection function.
*
* This function can be thought of the interpeted language binding
* version of gtk_builder_signal_autoconnect(), except that it does not
* require gmodule to function correctly.
*
* Since: 2.12
*/
void gtk_builder_connect_signals_full (GtkBuilder *builder,
GtkBuilderConnectFunc func,
gpointer user_data);
/**
* gtk_builder_get_type_from_name:
* @builder: a #GtkBuilder
* @typename: Type name to lookup.
*
* This method is used to lookup a type. It can be implemented in a subclass to
* override the #GType of an object created by the builder.
*
* Since 2.12
*/
GType gtk_builder_get_type_from_name (GtkBuilder *builder,
const char *typename);
/**
* gtk_builder_value_from_string
* @pspec: the GParamSpec for the property
* @string: the string representation of the value.
* @value: the GValue to store the result in.
*
* This function demarshals a value from a string. This function
* calls g_value_init() on the @value argument, so it need not be
* initialised beforehand.
*
* This function can handle char, uchar, boolean, int, uint, long,
* ulong, enum, flags, float, double, string, GdkColor and
* GtkAdjustment type values. Support for GtkWidget type values is
* still to come.
*
* Returns: %TRUE on success.
*
* Since: 2.12
*/
gboolean gtk_builder_value_from_string (GParamSpec *pspec,
const gchar *string,
GValue *value);
/**
* gtk_builder_value_from_string_type
* @type: the GType of the value
* @string: the string representation of the value.
* @value: the GValue to store the result in.
*
* Like gtk_builder_value_from_string(), but takes a #GType instead of
#GParamSpec.
*
* Returns: %TRUE on success.
*
* Since: 2.12
*/
gboolean gtk_builder_value_from_string_type (GType type,
const gchar *string,
GValue *value);
/**
* gtk_builder_flags_from_string:
* @type: a #GType
* @string: string containing a flag
*
* This function is used to convert a string to a flags value. You can use the
* flags' nick or blurb representations to convert from. Multiple values must be
* separated by a pipe character (|), space(s) are allowed before and after.
*
* Return value: converted flags value
*
* Since: 2.12
*/
guint gtk_builder_flags_from_string (GType type,
const char *string);
/**
* gtk_builder_enum_from_string:
* @type: a #GType
* @string: string containing an enum
*
* This function is used to convert a string to a enum value. You can use the
* enums nick or blurb representations to convert from.
*
* Return value: converted enum value
*
* Since: 2.12
*/
gint gtk_builder_enum_from_string (GType type,
const char *string);
/**
* gtk_builder_error_quark:
*
* Registers an error quark for #GtkBuilder if necessary.
*
* Return value: The error quark used for #GtkBuilder errors.
*
* Since: 2.12
**/
GQuark gtk_builder_error_quark (void);
gtkbuildable.h
==============
GtkBuildable is an interface which is implementable to allow a GObject
subclass to customize the behavior of how it is going to be built.
The following widgets implements the interface:
GtkWidget (set_property: has-focus, has-default,
custom tag: accelerator, set_name, get_name)
GtkWindow (set_property: visible)
GtkAction (set_name, get_name)
GtkActionGroup (add: action)
GtkUIManager (custom parser: uim defintion)
GtkContainer (add: widget, custom tag: packing)
GtkExpander (add: custom child type "label")
GtkFrame (add: custom child type "label")
GtkNotebook (add: custom child type "tab")
GtkTreeView (add: columns)
GtkCellLayout (add: renderers, custom parser: attributes)
GtkComboBox (add, custom: delegate to cell layout)
GtkEntryCompletion (add, custom: delegate to cell layout)
GtkIconview (add, custom: delegate to cell layout)
GtkTreeViewColumn (add, custom: delegate to cell layout)
GtkCellView (add, custom: delegate to cell layout)
GtkSizeGroup (custom tag: widgets)
GtkListStore (custom tag: data storage)
GtkTreeStore (custom tag: data storage)
GtkDialog (get internal child, custom parser: response)
GtkColorselDialog (get internal child)
GtkComboBoxEntry (get internal child)
GtkFontsel (get internal child)
struct _GtkBuildableIface
{
GTypeInterface g_iface;
/* virtual table */
void (* set_name) (GtkBuildable *buildable,
const gchar *name);
const gchar * (* get_name) (GtkBuildable *buildable);
void (* add) (GtkBuildable *buildable,
GtkBuilder *builder,
GObject *child,
const gchar *type);
void (* set_property) (GtkBuildable *buildable,
GtkBuilder *builder,
const gchar *name,
const GValue *value);
GObject * (* construct_child) (GtkBuildable *buildable,
GtkBuilder *builder,
const gchar *name);
gboolean (* custom_tag_start) (GtkBuildable *buildable,
GtkBuilder *builder,
GObject *child,
const gchar *tagname,
GMarkupParser *parser,
gpointer *data);
void (* custom_tag_end) (GtkBuildable *buildable,
GtkBuilder *builder,
GObject *child,
const gchar *tagname,
gpointer *data);
void (* custom_finished) (GtkBuildable *buildable,
GtkBuilder *builder,
GObject *child,
const gchar *tagname,
gpointer data);
void (* parser_finished) (GtkBuildable *buildable,
GtkBuilder *builder);
GObject * (* get_internal_child) (GtkBuildable *buildable,
GtkBuilder *builder,
const gchar *childname);
};
GType gtk_buildable_get_type (void) G_GNUC_CONST;
/**
* gtk_buildable_set_name:
* @buildable: a #GtkBuildable
* @name: name to set
*
* Sets the name of the buildable object, it's used to synchronize the name
* if the object already has it's own concept of name.
*
* #GtkWidget implements this to map the buildable name to the widget name
*
* Since: 2.12
**/
void gtk_buildable_set_name (GtkBuildable *buildable,
const gchar *name);
/**
* gtk_buildable_get_name:
* @buildable: a #GtkBuildable
*
* Returns: the buildable name, the name which was set in
* the <link linkend="BUILDER-UI">GtkBuilder UI definition</link> used to
* construct the @buildable.
*
* #GtkWidget implements this to map the buildable name to the widget name
*
* Since: 2.12
**/
const gchar * gtk_buildable_get_name (GtkBuildable *buildable);
/**
* gtk_buildable_add:
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder
* @child: child to add
* @type: kind of child or %NULL
*
* Add a child to a buildable. type is an optional string
* describing how the child should be added.
*
* #GtkContainer implements this to be able to add a child widget
* to the container. #GtkNotebook uses the @type to distinguish between
* page labels (@type = "page-label") and normal children.
*
* Since: 2.12
**/
void gtk_buildable_add (GtkBuildable *buildable,
GtkBuilder *builder,
GObject *child,
const gchar *type);
/**
* gtk_buildable_set_property:
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder
* @name: name of property
* @value: value of property
*
* Sets the property name @name to @value on the buildable object @buildable
* which is created by the @builder.
*
* This is optional to implement and is normally not neeeded.
* g_object_set_property() is used as a fallback.
*
* #GtkWindow implements this to delay showing (::visible) itself until
* the whole interface is fully created.
*
* Since: 2.12
**/
void gtk_buildable_set_property (GtkBuildable *buildable,
GtkBuilder *builder,
const gchar *name,
const GValue *value);
/**
* gtk_buildable_construct_child
* @buildable: A #GtkBuildable
* @builder: #GtkBuilder used to construct this object
* @name: name of child to construct
*
* Construct a child of @buildable with the name @name.
*
* #GtkUIManager implements this to reference to a widget created in a <ui> tag
* which is outsideof the normal <link linkend="BUILDER-UI">GtkBuilder UI
definition</link>
* object hierarchy.
*
* Since: 2.12
**/
GObject * gtk_buildable_construct_child (GtkBuildable *buildable,
GtkBuilder *builder,
const gchar *name);
/**
* gtk_buildable_custom_tag_start
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder used to construct this object
* @child: child object or %NULL for non-child tags
* @tagname: name of tag
* @parser: a #GMarkupParser structure
* @data: user data that will be passed in to parser functions
*
* This is called when an unknown tag under <child> tag is found.
*
* Called when an unknown tag is present under a a <child> tag.
* If the buildable implementation wishes to handle the tag it should
* return %TRUE and fill in the @parser structure. Remember to either
* implement custom_tag_end or custom_tag_finish to free
* the user data allocated here.
*
* #GtkWidget implements this and parsers all <accelerator> tags to
* keyboard accelerators.
* #GtkContainer implements this to map properties defined under <packing>
* tag to child properties.
*
* Returns: %TRUE if a object has a custom implementation, %FALSE
* if it doesn't.
*
* Since: 2.12
**/
gboolean gtk_buildable_custom_tag_start (GtkBuildable *buildable,
GtkBuilder *builder,
GObject *child,
const gchar *tagname,
GMarkupParser *parser,
gpointer *data);
/**
* gtk_buildable_custom_tag_end
* @buildable: A #GtkBuildable
* @builder: #GtkBuilder used to construct this object
* @child: child object or %NULL for non-child tags
* @tagname: name of tag
* @data: user data that will be passed in to parser functions
*
* This is called for each custom tag handled by the buildable.
* It will be called when the end of the tag is reached.
*
* Since: 2.12
**/
void gtk_buildable_custom_tag_end (GtkBuildable *buildable,
GtkBuilder *builder,
GObject *child,
const gchar *tagname,
gpointer *data);
/**
* gtk_buildable_custom_finished:
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder
* @child: child object or %NULL for non-child tags
* @tagname: the name of the tag
* @data: user data created in custom_tag_start
*
* This is similar to gtk_buildable_parser_finished() but is
* called once for each custom tag handled by the @buildable.
*
* Since: 2.12
**/
void gtk_buildable_custom_finished (GtkBuildable *buildable,
GtkBuilder *builder,
GObject *child,
const gchar *tagname,
gpointer data);
/**
* gtk_buildable_parser_finished:
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder
*
* Finish the parsing of a <link linkend="BUILDER-UI">GtkBuilder UI
definition</link>
* snippet. Note that this will be called once for each time
gtk_builder_add_from_file or
* gtk_builder_add_from_string is called on a builder.
*
* #GtkWindow implements this to delay showing (::visible) itself until
* the whole interface is fully created.
*
* Since: 2.12
**/
void gtk_buildable_parser_finished (GtkBuildable *buildable,
GtkBuilder *builder);
/**
* gtk_buildable_get_internal_child
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder
* @childname: name of child
*
* Get the internal child called @child of the @buildable object.
*
* Return: the internal child of the buildable object
*
* Since: 2.12
**/
GObject * gtk_buildable_get_internal_child (GtkBuildable *buildable,
GtkBuilder *builder,
const gchar *childname);
--
Johan Dahlin <jdahlin async com br>
Async Open Source
Attachment:
demo.glade
Description: application/glade