diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 3250e6dcc9..509d3eeabc 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -1,5 +1,6 @@ gtkbbox.sgml gtkbox.sgml +gtkbuilder.sgml gtkhbox.sgml gtkmessagedialog.sgml gtktesting.sgml diff --git a/docs/reference/gtk/tmpl/gtkbuilder.sgml b/docs/reference/gtk/tmpl/gtkbuilder.sgml deleted file mode 100644 index f5545eba57..0000000000 --- a/docs/reference/gtk/tmpl/gtkbuilder.sgml +++ /dev/null @@ -1,462 +0,0 @@ - -GtkBuilder - - -Build an interface from an XML UI definition - - - -A GtkBuilder is an auxiliary object that reads textual descriptions -of a user interface and instantiates the described objects. To pass a -description to a GtkBuilder, call gtk_builder_add_from_file() or -gtk_builder_add_from_string(). These functions can be called multiple -times; the builder merges the content of all descriptions. - - -A GtkBuilder holds a reference to all objects that it has constructed -and drops these references when it is finalized. This finalization can -cause the destruction of non-widget objects or widgets which are not -contained in a toplevel window. For toplevel windows constructed by a -builder, it is the responsibility of the user to call gtk_widget_destroy() -to get rid of them and all the widgets they contain. - - -The functions gtk_builder_get_object() and gtk_builder_get_objects() -can be used to access the widgets in the interface by the names assigned -to them inside the UI description. Toplevel windows returned by these -functions will stay around until the user explicitly destroys them -with gtk_widget_destroy(). Other widgets will either be part of a -larger hierarchy constructed by the builder (in which case you should -not have to worry about their lifecycle), or without a parent, in which -case they have to be added to some container to make use of them. -Non-widget objects need to be reffed with g_object_ref() to keep them -beyond the lifespan of the builder. - - -The function gtk_builder_connect_signals() and variants thereof can be -used to connect handlers to the named signals in the description. - - -GtkBuilder UI Definitions - -GtkBuilder parses textual descriptions of user interfaces which -are specified in an XML format which can be roughly described -by the DTD below. We refer to these descriptions as -GtkBuilder UI definitions or just -UI definitions if the context is clear. -Do not confuse GtkBuilder UI Definitions with -GtkUIManager UI Definitions, -which are more limited in scope. - - - - - - - - - - - - - - - -]]> - - -The toplevel element is <interface>. -It optionally takes a "domain" attribute, which will make -the builder look for translated strings using dgettext() in the -domain specified. This can also be done by calling -gtk_builder_set_translation_domain() on the builder. -Objects are described by <object> elements, which can -contain <property> elements to set properties, <signal> -elements which connect signals to handlers, and <child> -elements, which describe child objects (most often widgets -inside a container, but also e.g. actions in an action group, -or columns in a tree model). A <child> element contains -an <object> element which describes the child object. -The target toolkit version(s) are described by <requires> -elements, the "lib" attribute specifies the widget library in -question (currently the only supported value is "gtk+") and the "version" -attribute specifies the target version in the form "<major>.<minor>". -The builder will error out if the version requirements are not met. - - -Typically, the specific kind of object represented by an -<object> element is specified by the "class" attribute. -If the type has not been loaded yet, GTK+ tries to find the -_get_type() from the class name by applying -heuristics. This works in most cases, but if necessary, it is -possible to specify the name of the _get_type() -explictly with the "type-func" attribute. As a special case, -GtkBuilder allows to use an object that has been constructed -by a #GtkUIManager in another part of the UI definition by -specifying the id of the #GtkUIManager in the "constructor" -attribute and the name of the object in the "id" attribute. - - -Objects must be given a name with the "id" attribute, which -allows the application to retrieve them from the builder with -gtk_builder_get_object(). An id is also necessary to use the -object as property value in other parts of the UI definition. - -Prior to 2.20, GtkBuilder was setting the "name" -property of constructed widgets to the "id" attribute. In GTK+ -2.20 or newer, you have to use gtk_buildable_get_name() instead -of gtk_widget_get_name() to obtain the "id", or set the "name" -property in your UI definition. - - -Setting properties of objects is pretty straightforward with -the <property> element: the "name" attribute specifies -the name of the property, and the content of the element -specifies the value. If the "translatable" attribute is -set to a true value, GTK+ uses gettext() (or dgettext() if -the builder has a translation domain set) to find a translation -for the value. This happens before the value is parsed, so -it can be used for properties of any type, but it is probably -most useful for string properties. It is also possible to -specify a context to disambiguate short strings, and comments -which may help the translators. - - -GtkBuilder can parse textual representations for the most -common property types: characters, strings, integers, floating-point -numbers, booleans (strings like "TRUE", "t", "yes", "y", "1" are -interpreted as %TRUE, strings like "FALSE, "f", "no", "n", "0" are -interpreted as %FALSE), enumerations (can be specified by their -name, nick or integer value), flags (can be specified by their name, -nick, integer value, optionally combined with "|", e.g. -"GTK_VISIBLE|GTK_REALIZED") and colors (in a format understood by -gdk_color_parse()). Objects can be referred to by their name. -Pixbufs can be specified as a filename of an image file to load. -In general, GtkBuilder allows forward references to objects — -an object doesn't have to constructed before it can be referred to. -The exception to this rule is that an object has to be constructed -before it can be used as the value of a construct-only property. - - -Signal handlers are set up with the <signal> element. -The "name" attribute specifies the name of the signal, and the -"handler" attribute specifies the function to connect to the signal. -By default, GTK+ tries to find the handler using g_module_symbol(), -but this can be changed by passing a custom #GtkBuilderConnectFunc -to gtk_builder_connect_signals_full(). The remaining attributes, -"after", "swapped" and "object", have the same meaning as the -corresponding parameters of the g_signal_connect_object() or -g_signal_connect_data() functions. A "last_modification_time" attribute -is also allowed, but it does not have a meaning to the builder. - - -Sometimes it is necessary to refer to widgets which have implicitly -been constructed by GTK+ as part of a composite widget, to set -properties on them or to add further children (e.g. the @vbox -of a #GtkDialog). This can be achieved by setting the "internal-child" -propery of the <child> element to a true value. Note that -GtkBuilder still requires an <object> element for the internal -child, even if it has already been constructed. - - -A number of widgets have different places where a child can be -added (e.g. tabs vs. page content in notebooks). This can be reflected -in a UI definition by specifying the "type" attribute on a <child> -The possible values for the "type" attribute are described in -the sections describing the widget-specific portions of UI definitions. - - -A GtkBuilder UI Definition - - - - - 10 - - - 20 - - - gtk-ok - TRUE - - - - - - - - - -]]> - - -Beyond this general structure, several object classes define -their own XML DTD fragments for filling in the ANY placeholders -in the DTD above. Note that a custom element in a <child> -element gets parsed by the custom tag handler of the parent -object, while a custom element in an <object> element -gets parsed by the custom tag handler of the object. - - -These XML fragments are explained in the documentation of the -respective objects, see -GtkWidget, -GtkLabel, -GtkWindow, -GtkContainer, -GtkDialog, -GtkCellLayout, -GtkColorSelectionDialog, -GtkFontSelectionDialog, -GtkComboBoxEntry, -GtkExpander, -GtkFrame, -GtkListStore, -GtkTreeStore, -GtkNotebook, -GtkSizeGroup, -GtkTreeView, -GtkUIManager, -GtkActionGroup. -GtkMenuItem, -GtkAssistant, -GtkScale. - - - - - - - - - - - - - - - - - - - - - - - - - -@builder: -@object: -@signal_name: -@handler_name: -@connect_object: -@flags: -@user_data: - - - - -Error codes that identify various errors that can occur while -using #GtkBuilder. - - -@GTK_BUILDER_ERROR_INVALID_TYPE_FUNCTION: A type-func attribute didn't name - a function that returns a #GType. -@GTK_BUILDER_ERROR_UNHANDLED_TAG: The input contained a tag that #GtkBuilder - can't handle. -@GTK_BUILDER_ERROR_MISSING_ATTRIBUTE: An attribute that is required by - #GtkBuilder was missing. -@GTK_BUILDER_ERROR_INVALID_ATTRIBUTE: #GtkBuilder found an attribute that - it doesn't understand. -@GTK_BUILDER_ERROR_INVALID_TAG: #GtkBuilder found a tag that - it doesn't understand. -@GTK_BUILDER_ERROR_MISSING_PROPERTY_VALUE: A required property value was - missing. -@GTK_BUILDER_ERROR_INVALID_VALUE: #GtkBuilder couldn't parse - some attribute value. -@GTK_BUILDER_ERROR_VERSION_MISMATCH: The input file requires a newer version - of GTK+. -@GTK_BUILDER_ERROR_DUPLICATE_ID: An object id occurred twice. - - - - - - -@Returns: - - - - - - - -@builder: -@filename: -@error: -@Returns: - - - - - - - -@builder: -@buffer: -@length: -@error: -@Returns: - - - - - - - -@builder: -@filename: -@object_ids: -@error: -@Returns: - - - - - - - -@builder: -@buffer: -@length: -@object_ids: -@error: -@Returns: - - - - - - - -@builder: -@name: -@Returns: - - - - - - - -@builder: -@Returns: - - - - - - - -@builder: -@user_data: - - - - - - - -@builder: -@func: -@user_data: - - - - - - - -@builder: -@domain: - - - - - - - -@builder: -@Returns: - - - - - - - -@builder: -@type_name: -@Returns: - - - - - - - -@builder: -@pspec: -@string: -@value: -@error: -@Returns: - - - - - - - -@builder: -@type: -@string: -@value: -@error: -@Returns: - - - - -This macro should be used to emit a warning about and unexpected -@type value in a #GtkBuildable add_child implementation. - - -@object: the #GtkBuildable on which the warning ocurred -@type: the unexpected type value - - - - -The #GError quark for #GtkBuilder errors - - - - diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index 35f0271ccd..c6d3b0814f 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -20,6 +20,224 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gtkbuilder + * @Short_description: Build an interface from an XML UI definition + * @Title: GtkBuilder + * + * A GtkBuilder is an auxiliary object that reads textual descriptions + * of a user interface and instantiates the described objects. To pass a + * description to a GtkBuilder, call gtk_builder_add_from_file() or + * gtk_builder_add_from_string(). These functions can be called multiple + * times; the builder merges the content of all descriptions. + * + * A GtkBuilder holds a reference to all objects that it has constructed + * and drops these references when it is finalized. This finalization can + * cause the destruction of non-widget objects or widgets which are not + * contained in a toplevel window. For toplevel windows constructed by a + * builder, it is the responsibility of the user to call gtk_widget_destroy() + * to get rid of them and all the widgets they contain. + * + * The functions gtk_builder_get_object() and gtk_builder_get_objects() + * can be used to access the widgets in the interface by the names assigned + * to them inside the UI description. Toplevel windows returned by these + * functions will stay around until the user explicitly destroys them + * with gtk_widget_destroy(). Other widgets will either be part of a + * larger hierarchy constructed by the builder (in which case you should + * not have to worry about their lifecycle), or without a parent, in which + * case they have to be added to some container to make use of them. + * Non-widget objects need to be reffed with g_object_ref() to keep them + * beyond the lifespan of the builder. + * + * The function gtk_builder_connect_signals() and variants thereof can be + * used to connect handlers to the named signals in the description. + * + * + * GtkBuilder UI Definitions + * + * GtkBuilder parses textual descriptions of user interfaces which are specified + * in an XML format which can be roughly described by the DTD below. We refer to + * these descriptions as GtkBuilder UI definitions or + * just UI definitions if the context is clear. Do not + * confuse GtkBuilder UI Definitions with + * GtkUIManager UI Definitions, which are more + * limited in scope. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * ]]> + * + * The toplevel element is <interface>. It optionally takes a "domain" + * attribute, which will make the builder look for translated strings using + * dgettext() in the domain specified. This can also be done by calling + * gtk_builder_set_translation_domain() on the builder. Objects are described by + * <object> elements, which can contain <property> elements to set + * properties, <signal> elements which connect signals to handlers, and + * <child> elements, which describe child objects (most often widgets + * inside a container, but also e.g. actions in an action group, or columns in a + * tree model). A <child> element contains an <object> element which + * describes the child object. The target toolkit version(s) are described by + * <requires> elements, the "lib" attribute specifies the widget library + * in question (currently the only supported value is "gtk+") and the "version" + * attribute specifies the target version in the form + * "<major>.<minor>". The builder will error out if the version + * requirements are not met. + * + * Typically, the specific kind of object represented by an <object> + * element is specified by the "class" attribute. If the type has not been + * loaded yet, GTK+ tries to find the _get_type() from the + * class name by applying heuristics. This works in most cases, but if + * necessary, it is possible to specify the name of the + * _get_type() explictly with the "type-func" attribute. + * As a special case, GtkBuilder allows to use an object that has been + * constructed by a #GtkUIManager in another part of the UI definition by + * specifying the id of the #GtkUIManager in the "constructor" attribute and the + * name of the object in the "id" attribute. + * + * Objects must be given a name with the "id" attribute, which allows the + * application to retrieve them from the builder with gtk_builder_get_object(). + * An id is also necessary to use the object as property value in other parts of + * the UI definition. + * + * + * Prior to 2.20, GtkBuilder was setting the "name" property of constructed widgets to the + * "id" attribute. In GTK+ 2.20 or newer, you have to use gtk_buildable_get_name() instead + * of gtk_widget_get_name() to obtain the "id", or set the "name" property in your UI + * definition. + * + * + * Setting properties of objects is pretty straightforward with the + * <property> element: the "name" attribute specifies the name of the + * property, and the content of the element specifies the value. If the + * "translatable" attribute is set to a true value, GTK+ uses gettext() (or + * dgettext() if the builder has a translation domain set) to find a translation + * for the value. This happens before the value is parsed, so it can be used for + * properties of any type, but it is probably most useful for string properties. + * It is also possible to specify a context to disambiguate short strings, and + * comments which may help the translators. + * + * GtkBuilder can parse textual representations for the most common property + * types: characters, strings, integers, floating-point numbers, booleans + * (strings like "TRUE", "t", "yes", "y", "1" are interpreted as %TRUE, strings + * like "FALSE, "f", "no", "n", "0" are interpreted as %FALSE), enumerations + * (can be specified by their name, nick or integer value), flags (can be + * specified by their name, nick, integer value, optionally combined with "|", + * e.g. "GTK_VISIBLE|GTK_REALIZED") and colors (in a format understood by + * gdk_color_parse()). Objects can be referred to by their name. Pixbufs can be + * specified as a filename of an image file to load. In general, GtkBuilder + * allows forward references to objects — an object doesn't have to be + * constructed before it can be referred to. The exception to this rule is that + * an object has to be constructed before it can be used as the value of a + * construct-only property. + * + * Signal handlers are set up with the <signal> element. The "name" + * attribute specifies the name of the signal, and the "handler" attribute + * specifies the function to connect to the signal. By default, GTK+ tries to + * find the handler using g_module_symbol(), but this can be changed by passing + * a custom #GtkBuilderConnectFunc to gtk_builder_connect_signals_full(). The + * remaining attributes, "after", "swapped" and "object", have the same meaning + * as the corresponding parameters of the g_signal_connect_object() or + * g_signal_connect_data() functions. A "last_modification_time" attribute + * is also allowed, but it does not have a meaning to the builder. + * + * Sometimes it is necessary to refer to widgets which have implicitly been + * constructed by GTK+ as part of a composite widget, to set properties on them + * or to add further children (e.g. the @vbox of a #GtkDialog). This can be + * achieved by setting the "internal-child" propery of the <child> element + * to a true value. Note that GtkBuilder still requires an <object> + * element for the internal child, even if it has already been constructed. + * + * A number of widgets have different places where a child can be added (e.g. + * tabs vs. page content in notebooks). This can be reflected in a UI definition + * by specifying the "type" attribute on a <child>. The possible values + * for the "type" attribute are described in the sections describing the + * widget-specific portions of UI definitions. + * + * + * A GtkBuilder UI Definition + * + * + * + * + * 10 + * + * + * 20 + * + * + * gtk-ok + * TRUE + * + * + * + * + * + * + * + * + * + * ]]> + * + * + * Beyond this general structure, several object classes define their own XML + * DTD fragments for filling in the ANY placeholders in the DTD above. Note that + * a custom element in a <child> element gets parsed by the custom tag + * handler of the parent object, while a custom element in an <object> + * element gets parsed by the custom tag handler of the object. + * + * These XML fragments are explained in the documentation of the respective + * objects, see + * GtkWidget, + * GtkLabel, + * GtkWindow, + * GtkContainer, + * GtkDialog, + * GtkCellLayout, + * GtkColorSelectionDialog, + * GtkFontSelectionDialog, + * GtkComboBoxEntry, + * GtkExpander, + * GtkFrame, + * GtkListStore, + * GtkTreeStore, + * GtkNotebook, + * GtkSizeGroup, + * GtkTreeView, + * GtkUIManager, + * GtkActionGroup. + * GtkMenuItem, + * GtkAssistant, + * GtkScale. + * + * + */ + #include "config.h" #include /* errno */ #include /* strtol, strtoul */ diff --git a/gtk/gtkbuilder.h b/gtk/gtkbuilder.h index 0f9224e0e7..8a2a8290a3 100644 --- a/gtk/gtkbuilder.h +++ b/gtk/gtkbuilder.h @@ -43,6 +43,29 @@ typedef struct _GtkBuilder GtkBuilder; typedef struct _GtkBuilderClass GtkBuilderClass; typedef struct _GtkBuilderPrivate GtkBuilderPrivate; +/** + * GtkBuilderError: + * @GTK_BUILDER_ERROR_INVALID_TYPE_FUNCTION: A type-func attribute didn't name + * a function that returns a #GType. + * @GTK_BUILDER_ERROR_UNHANDLED_TAG: The input contained a tag that #GtkBuilder + * can't handle. + * @GTK_BUILDER_ERROR_MISSING_ATTRIBUTE: An attribute that is required by + * #GtkBuilder was missing. + * @GTK_BUILDER_ERROR_INVALID_ATTRIBUTE: #GtkBuilder found an attribute that + * it doesn't understand. + * @GTK_BUILDER_ERROR_INVALID_TAG: #GtkBuilder found a tag that + * it doesn't understand. + * @GTK_BUILDER_ERROR_MISSING_PROPERTY_VALUE: A required property value was + * missing. + * @GTK_BUILDER_ERROR_INVALID_VALUE: #GtkBuilder couldn't parse + * some attribute value. + * @GTK_BUILDER_ERROR_VERSION_MISMATCH: The input file requires a newer version + * of GTK+. + * @GTK_BUILDER_ERROR_DUPLICATE_ID: An object id occurred twice. + * + * Error codes that identify various errors that can occur while using + * #GtkBuilder. + */ typedef enum { GTK_BUILDER_ERROR_INVALID_TYPE_FUNCTION, @@ -135,6 +158,14 @@ gboolean gtk_builder_value_from_string_type (GtkBuilder *builder, GValue *value, GError **error); +/** + * GTK_BUILDER_WARN_INVALID_CHILD_TYPE: + * @object: the #GtkBuildable on which the warning ocurred + * @type: the unexpected type value + * + * This macro should be used to emit a warning about and unexpected @type value + * in a #GtkBuildable add_child implementation. + */ #define GTK_BUILDER_WARN_INVALID_CHILD_TYPE(object, type) \ g_warning ("'%s' is not a valid child type of '%s'", type, g_type_name (G_OBJECT_TYPE (object)))