Class: Gtk::Builder

Inherits:

Object

• Object
• Gtk::Builder

Defined in:

(unknown)

Instance Method Summary

• #add_from_file(filename) ⇒ Boolean

  Parses a file containing a UI definition and merges it with the current contents of builder.

• #add_from_resource(resource_path) ⇒ Boolean

  Parses a resource file containing a UI definition and merges it with the current contents of builder.

• #add_from_string(buffer, length) ⇒ Boolean

  Parses a string containing a UI definition and merges it with the current contents of builder.

• #add_objects_from_file(filename, object_ids) ⇒ Boolean

  Parses a file containing a UI definition building only the requested objects and merges them with the current contents of builder.

• #add_objects_from_resource(resource_path, object_ids) ⇒ Boolean

  Parses a resource file containing a UI definition, building only the requested objects and merges them with the current contents of builder.

• #add_objects_from_string(buffer, length, object_ids) ⇒ Boolean

  Parses a string containing a UI definition, building only the requested objects and merges them with the current contents of builder.

• #create_closure(function_name, flags, object) ⇒ GObject::Closure

  Creates a closure to invoke the function called function_name.

• #current_object ⇒ GObject::Object

  The object the builder is evaluating for.

• #current_object=(current_object) ⇒ GObject::Object

  The object the builder is evaluating for.

• #expose_object(name, object) ⇒ nil

  Add object to the builder object pool so it can be referenced just like any other object built by builder.

• #extend_with_template(object, template_type, buffer, length) ⇒ Boolean

  Main private entry point for building composite components from template XML.

• #get_object(name) ⇒ GObject::Object

  Gets the object named name.

• #get_type_from_name(type_name) ⇒ GLib::Type

  Looks up a type by name.

• #initialize(string, length) ⇒ Gtk::Builder constructor

  Parses the UI definition in string.

• #objects ⇒ GLib::SList<GObject::Object>

  Gets all objects that have been constructed by builder.

• #scope ⇒ Gtk::BuilderScope

  The scope the builder is operating in.

• #scope=(scope) ⇒ Gtk::BuilderScope

  The scope the builder is operating in.

• #translation_domain ⇒ String

  The translation domain used when translating property values that have been marked as translatable.

• #translation_domain=(translation_domain) ⇒ String

  The translation domain used when translating property values that have been marked as translatable.

• #value_from_string(pspec, string, value) ⇒ Boolean

  Demarshals a value from a string.

• #value_from_string_type(type, string, value) ⇒ Boolean

  Demarshals a value from a string.

Constructor Details

#initialize(string, length) ⇒ Gtk::Builder

Parses the UI definition in string.

If string is nil-terminated, then length should be -1. If length is not -1, then it is the length of string.

If there is an error parsing string then the program will be aborted. You should not attempt to parse user interface description from untrusted sources.

Parameters:

• string (String) —

  a user interface (XML) description

• length (Gtk::gssize) —

  the length of string, or -1

Instance Method Details

#add_from_file(filename) ⇒ Boolean

Parses a file containing a UI definition and merges it with the current contents of builder.

This function is useful if you need to call [methodGtk.Builder.set_current_object]) to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctorGtk.Builder.new_from_file] instead.

If an error occurs, 0 will be returned and error will be assigned a GError from the GTK_BUILDER_ERROR, G_MARKUP_ERROR or G_FILE_ERROR domains.

It’s not really reasonable to attempt to handle failures of this call. You should not use this function with untrusted files (ie: files that are not part of your application). Broken GtkBuilder files can easily crash your program, and it’s possible that memory was leaked leading up to the reported failure. The only reasonable thing to do when an error is detected is to call g_error().

Parameters:

• filename (Gtk::filename) —

  the name of the file to parse

Returns:

• (Boolean) —

  true on success, false if an error occurred

#add_from_resource(resource_path) ⇒ Boolean

Parses a resource file containing a UI definition and merges it with the current contents of builder.

This function is useful if you need to call [methodGtk.Builder.set_current_object] to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctorGtk.Builder.new_from_resource] instead.

If an error occurs, 0 will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_RESOURCE_ERROR domain.

It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error().

Parameters:

• resource_path (String) —

  the path of the resource file to parse

Returns:

• (Boolean) —

  true on success, false if an error occurred

#add_from_string(buffer, length) ⇒ Boolean

Parses a string containing a UI definition and merges it with the current contents of builder.

This function is useful if you need to call [methodGtk.Builder.set_current_object] to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctorGtk.Builder.new_from_string] instead.

Upon errors false will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_VARIANT_PARSE_ERROR domain.

It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error().

Parameters:

• buffer (String) —

  the string to parse

• length (Gtk::gssize) —

  the length of buffer (may be -1 if buffer is nul-terminated)

Returns:

• (Boolean) —

  true on success, false if an error occurred

#add_objects_from_file(filename, object_ids) ⇒ Boolean

Parses a file containing a UI definition building only the requested objects and merges them with the current contents of builder.

Upon errors, 0 will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_FILE_ERROR domain.

If you are adding an object that depends on an object that is not its child (for instance a GtkTreeView that depends on its GtkTreeModel), you have to explicitly list all of them in object_ids.

Parameters:

• filename (Gtk::filename) —

  the name of the file to parse

• object_ids (Array<String>) —

  nul-terminated array of objects to build

Returns:

• (Boolean) —

  true on success, false if an error occurred

#add_objects_from_resource(resource_path, object_ids) ⇒ Boolean

Parses a resource file containing a UI definition, building only the requested objects and merges them with the current contents of builder.

Upon errors, 0 will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_RESOURCE_ERROR domain.

If you are adding an object that depends on an object that is not its child (for instance a GtkTreeView that depends on its GtkTreeModel), you have to explicitly list all of them in object_ids.

Parameters:

• resource_path (String) —

  the path of the resource file to parse

• object_ids (Array<String>) —

  nul-terminated array of objects to build

Returns:

• (Boolean) —

  true on success, false if an error occurred

#add_objects_from_string(buffer, length, object_ids) ⇒ Boolean

Parses a string containing a UI definition, building only the requested objects and merges them with the current contents of builder.

Upon errors false will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR or %G_MARKUP_ERROR domain.

If you are adding an object that depends on an object that is not its child (for instance a GtkTreeView that depends on its GtkTreeModel), you have to explicitly list all of them in object_ids.

Parameters:

• buffer (String) —

  the string to parse

• length (Gtk::gssize) —

  the length of buffer (may be -1 if buffer is nul-terminated)

• object_ids (Array<String>) —

  nul-terminated array of objects to build

Returns:

• (Boolean) —

  true on success, false if an error occurred

#create_closure(function_name, flags, object) ⇒ GObject::Closure

Creates a closure to invoke the function called function_name.

This is using the create_closure() implementation of builder's [ifaceGtk.BuilderScope].

If no closure could be created, nil will be returned and error will be set.

Parameters:

• function_name (String) —

  name of the function to look up

• flags (Gtk::BuilderClosureFlags) —

  closure creation flags

• object (GObject::Object) —

  Object to create the closure with

Returns:

• (GObject::Closure) —

  A new closure for invoking function_name

#current_object ⇒ GObject::Object

The object the builder is evaluating for.

Returns:

• (GObject::Object) —

  current-object

#current_object=(current_object) ⇒ GObject::Object

The object the builder is evaluating for.

Parameters:

• current_object (GObject::Object)

Returns:

• (GObject::Object) —

  current-object

• (GObject::Object) —

  current-object

#expose_object(name, object) ⇒ nil

Add object to the builder object pool so it can be referenced just like any other object built by builder.

Only a single object may be added using name. However, it is not an error to expose the same object under multiple names. gtk_builder_get_object() may be used to determine if an object has already been added with name.

Parameters:

• name (String) —

  the name of the object exposed to the builder

• object (GObject::Object) —

  the object to expose

Returns:

• (nil)

#extend_with_template(object, template_type, buffer, length) ⇒ Boolean

Main private entry point for building composite components from template XML.

Most likely you do not need to call this function in applications as templates are handled by GtkWidget.

Parameters:

• object (GObject::Object) —

  the object that is being extended

• template_type (GLib::Type) —

  the type that the template is for

• buffer (String) —

  the string to parse

• length (Gtk::gssize) —

  the length of buffer (may be -1 if buffer is nul-terminated)

Returns:

• (Boolean) —

  A positive value on success, 0 if an error occurred

#get_object(name) ⇒ GObject::Object

Gets the object named name.

Note that this function does not increment the reference count of the returned object.

Parameters:

• name (String) —

  name of object to get

Returns:

• (GObject::Object) —

  the object named name

#get_type_from_name(type_name) ⇒ GLib::Type

Looks up a type by name.

This is using the virtual function that GtkBuilder has for that purpose. This is mainly used when implementing the GtkBuildable interface on a type.

Parameters:

• type_name (String) —

  type name to lookup

Returns:

• (GLib::Type) —

  the GType found for type_name or %G_TYPE_INVALID if no type was found

#objects ⇒ GLib::SList<GObject::Object>

Gets all objects that have been constructed by builder.

Note that this function does not increment the reference counts of the returned objects.

Returns:

• (GLib::SList<GObject::Object>) —

  a newly-allocated GSList containing all the objects constructed by the GtkBuilder instance. It should be freed by g_slist_free()

#scope ⇒ Gtk::BuilderScope

The scope the builder is operating in

Returns:

• (Gtk::BuilderScope) —

  scope

#scope=(scope) ⇒ Gtk::BuilderScope

The scope the builder is operating in

Parameters:

• scope (Gtk::BuilderScope)

Returns:

• (Gtk::BuilderScope) —

  scope

• (Gtk::BuilderScope) —

  scope

#translation_domain ⇒ String

The translation domain used when translating property values that have been marked as translatable.

If the translation domain is nil, GtkBuilder uses gettext(), otherwise g_dgettext().

Returns:

• (String) —

  translation-domain

#translation_domain=(translation_domain) ⇒ String

The translation domain used when translating property values that have been marked as translatable.

If the translation domain is nil, GtkBuilder uses gettext(), otherwise g_dgettext().

Parameters:

• translation_domain (String)

Returns:

• (String) —

  translation-domain

• (String) —

  translation-domain

#value_from_string(pspec, string, value) ⇒ Boolean

Demarshals a value from a string.

This function calls g_value_init() on the value argument, so it need not be initialised beforehand.

Can handle char, uchar, boolean, int, uint, long, ulong, enum, flags, float, double, string, GdkRGBA and GtkAdjustment type values.

Upon errors false will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR domain.

Parameters:

• pspec (GObject::ParamSpec) —

  the GParamSpec for the property

• string (String) —

  the string representation of the value

• value (GObject::Value) —

  the GValue to store the result in

Returns:

• (Boolean) —

  true on success

#value_from_string_type(type, string, value) ⇒ Boolean

Demarshals a value from a string.

Unlike [methodGtk.Builder.value_from_string], this function takes a GType instead of GParamSpec.

Calls g_value_init() on the value argument, so it need not be initialised beforehand.

Upon errors false will be returned and error will be assigned a GError from the %GTK_BUILDER_ERROR domain.

Parameters:

• type (GLib::Type) —

  the GType of the value

• string (String) —

  the string representation of the value

• value (GObject::Value) —

  the GValue to store the result in

Returns:

• (Boolean) —

  true on success