Class: Gtk::Builder

Inherits:
Object
  • Object
show all
Defined in:
(unknown)

Instance Method Summary collapse

Instance Method Details

#add_callback_symbol(callback_name, callback_symbol) ⇒ nil

Adds the callback_symbol to the scope of builder under the given callback_name.

Using this function overrides the behavior of gtk_builder_connect_signals() for any callback symbols that are added. Using this method allows for better encapsulation as it does not require that callback symbols be declared in the global namespace.

Parameters:

  • callback_name (String)

    The name of the callback, as expected in the XML

  • callback_symbol (GObject::Callback)

    The callback pointer

Returns:

  • (nil)

#add_callback_symbols(first_callback_name, first_callback_symbol, array) ⇒ nil

A convenience function to add many callbacks instead of calling gtk_builder_add_callback_symbol() for each symbol.

Parameters:

  • first_callback_name (String)

    The name of the callback, as expected in the XML

  • first_callback_symbol (GObject::Callback)

    The callback pointer

  • array (Array)

    A list of callback name and callback symbol pairs terminated with nil

Returns:

  • (nil)

#add_from_file(filename) ⇒ Integer

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

Most users will probably want to use gtk_builder_new_from_file().

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 domain.

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 Gtk::Builder 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 (String)

    the name of the file to parse

Returns:

  • (Integer)

    A positive value on success, 0 if an error occurred

#add_from_resource(resource_path) ⇒ Integer

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

Most users will probably want to use gtk_builder_new_from_resource().

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:

  • (Integer)

    A positive value on success, 0 if an error occurred

#add_from_string(buffer, length) ⇒ Integer

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

Most users will probably want to use gtk_builder_new_from_string().

Upon errors 0 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 (Integer)

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

Returns:

  • (Integer)

    A positive value on success, 0 if an error occurred

#add_objects_from_file(filename, object_ids) ⇒ Integer

Parses a file containing a [GtkBuilder 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 Gtk::TreeView that depends on its Gtk::TreeModel), you have to explicitly list all of them in object_ids.

Parameters:

  • filename (String)

    the name of the file to parse

  • object_ids (Array<String>)

    nul-terminated array of objects to build

Returns:

  • (Integer)

    A positive value on success, 0 if an error occurred

#add_objects_from_resource(resource_path, object_ids) ⇒ Integer

Parses a resource file containing a [GtkBuilder 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 Gtk::TreeView that depends on its Gtk::TreeModel), 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:

  • (Integer)

    A positive value on success, 0 if an error occurred

#add_objects_from_string(buffer, length, object_ids) ⇒ Integer

Parses a string containing a [GtkBuilder 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 or #G_MARKUP_ERROR domain.

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

Parameters:

  • buffer (String)

    the string to parse

  • length (Integer)

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

  • object_ids (Array<String>)

    nul-terminated array of objects to build

Returns:

  • (Integer)

    A positive value on success, 0 if an error occurred

#applicationGtk::Application

Gets the Gtk::Application associated with the builder.

The Gtk::Application is used for creating action proxies as requested from XML that the builder is loading.

By default, the builder uses the default application: the one from g_application_get_default(). If you want to use another application for constructing proxies, use gtk_builder_set_application().

Returns:

#application=(application) ⇒ nil

Sets the application associated with builder.

You only need this function if there is more than one #GApplication in your process. application cannot be nil.

Parameters:

Returns:

  • (nil)

#connect_signals(user_data) ⇒ nil

This method is a simpler variation of gtk_builder_connect_signals_full(). It uses symbols explicitly added to builder with prior calls to gtk_builder_add_callback_symbol(). In the case that symbols are not explicitly added; it uses #GModule’s introspective features (by opening the module nil) 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 can only be called once, subsequent calls will do nothing.

Note that unless gtk_builder_add_callback_symbol() is called for all signal callbacks which are referenced by the loaded XML, this function will require that #GModule be supported on the platform.

If you rely on #GModule support to lookup callbacks in the symbol table, the following details should be noted:

When compiling applications for Windows, you must declare signal callbacks with #G_MODULE_EXPORT, or they will not be put in the symbol table. On Linux and Unices, this is not necessary; applications should instead be compiled with the -Wl,–export-dynamic CFLAGS, and linked against gmodule-export-2.0.

Parameters:

  • user_data (GObject)

    user data to pass back with all signals

Returns:

  • (nil)

#connect_signals_full(func, user_data) ⇒ nil

This function can be thought of the interpreted language binding version of gtk_builder_connect_signals(), except that it does not require GModule to function correctly.

Parameters:

  • func (Gtk::BuilderConnectFunc)

    the function used to connect the signals

  • user_data (GObject)

    arbitrary data that will be passed to the connection function

Returns:

  • (nil)

#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.

Parameters:

  • name (String)

    the name of the object exposed to the builder

  • object (GObject::Object)

    the object to expose

Returns:

  • (nil)

#extend_with_template(widget, template_type, buffer, length) ⇒ Integer

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

This is exported purely to let gtk-builder-tool validate templates, applications have no need to call this function.

Parameters:

  • widget (Gtk::Widget)

    the widget that is being extended

  • template_type (GLib::Type)

    the type that the template is for

  • buffer (String)

    the string to parse

  • length (Integer)

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

Returns:

  • (Integer)

    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 or nil if it could not be found in the object tree.

#get_type_from_name(type_name) ⇒ GLib::Type

Looks up a type by name, using the virtual function that Gtk::Builder has for that purpose. This is mainly used when implementing the Gtk::Buildable 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

#lookup_callback_symbol(callback_name) ⇒ GObject::Callback

Fetches a symbol previously added to builder with gtk_builder_add_callback_symbols()

This function is intended for possible use in language bindings or for any case that one might be cusomizing signal connections using gtk_builder_connect_signals_full()

Parameters:

  • callback_name (String)

    The name of the callback

Returns:

  • (GObject::Callback)

    The callback symbol in builder for callback_name, or nil

#newGtk::Builder

Creates a new empty builder object.

This function is only useful if you intend to make multiple calls to gtk_builder_add_from_file(), gtk_builder_add_from_resource() or gtk_builder_add_from_string() in order to merge multiple UI descriptions into a single builder.

Most users will probably want to use gtk_builder_new_from_file(), gtk_builder_new_from_resource() or gtk_builder_new_from_string().

Returns:

#new_from_file(filename) ⇒ Gtk::Builder

Builds the [GtkBuilder UI definition] in the file filename.

If there is an error opening the file or parsing the description then the program will be aborted. You should only ever attempt to parse user interface descriptions that are shipped as part of your program.

Parameters:

  • filename (String)

    filename of user interface description file

Returns:

  • (Gtk::Builder)

    a Gtk::Builder containing the described interface

#new_from_resource(resource_path) ⇒ Gtk::Builder

Builds the [GtkBuilder UI definition] at resource_path.

If there is an error locating the resource or parsing the description, then the program will be aborted.

Parameters:

  • resource_path (String)

    a #GResource resource path

Returns:

  • (Gtk::Builder)

    a Gtk::Builder containing the described interface

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

Builds the user interface described by string (in the

GtkBuilder UI definition][BUILDER-UI

format).

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

Returns:

  • (Gtk::Builder)

    a Gtk::Builder containing the interface described by string

#objectsGLib::SList

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)

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

#translation_domainString

The translation domain used when translating property values that have been marked as translatable in interface descriptions. If the translation domain is nil, Gtk::Builder 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 in interface descriptions. If the translation domain is nil, Gtk::Builder uses gettext(), otherwise g_dgettext().

Parameters:

  • translation_domain (String)

Returns:

  • (String)

    translation-domain

  • (String)

    translation-domain

#value_from_string(pspec, string, value) ⇒ TrueClass

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, Gdk::Color, #GdkRGBA and Gtk::Adjustment type values. Support for #GtkWidget type values is still to come.

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

Parameters:

  • pspec (GObject::ParamSpec)

    the GParam::Spec for the property

  • string (String)

    the string representation of the value

  • value (GObject::Value)

    the #GValue to store the result in

Returns:

  • (TrueClass)

    true on success

#value_from_string_type(type, string, value) ⇒ TrueClass

Like gtk_builder_value_from_string(), this function demarshals a value from a string, but takes a #GType instead of GParam::Spec. This function 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:

  • (TrueClass)

    true on success