Warning! Spelling nazism follows...
Is the misspelling of GTK_BUILDER_ERROR_MISSING_ATTRIBUTE in
GtkBuilderError below a transcription error?
There're also spelling errors in the documentation for:
GtkBuilderConnectFunc: s/intented/intended/ and s/non NULL/non-%NULL/
gtk_builder_connect_signals_full: s/interpeted/interpreted/
gtk_buildable_set_property: s/neeeded/needed/
gtk_buildable_construct_child: s/outsideof/outside of/
I can't comment on the API though.
Philip
On Tue, 2007-06-12 at 18:26 -0300, Johan Dahlin wrote:
> 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);
>
> _______________________________________________
> gtk-devel-list mailing list
> gtk-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-devel-list
Attachment:
signature.asc
Description: This is a digitally signed message part