Builder

class Builder(scope_object_or_map=None)

Superclasses: Object

Constructors:

Builder(**properties)
new() -> Gtk.Builder
new_from_file(filename:str) -> Gtk.Builder
new_from_resource(resource_path:str) -> Gtk.Builder
new_from_string(string:str, length:int) -> Gtk.Builder

Constructors

class Builder
classmethod new() → Builder

Creates a new empty builder object.

This function is only useful if you intend to make multiple calls to add_from_file, add_from_resource or add_from_string in order to merge multiple UI descriptions into a single builder.

classmethod new_from_file(filename: str) → Builder

Parses the 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 – filename of user interface description file

classmethod new_from_resource(resource_path: str) → Builder

Parses the 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 – a GResource resource path

classmethod new_from_string(string: str, length: int) → Builder

Parses the UI definition in string.

If string is None-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 – a user interface (XML) description

  • length – the length of string, or -1

Methods

class Builder
add_from_file(filename: str) → bool

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 set_current_object) to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want 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 :func:`~gi.repository.GLib.error`.

Parameters:

filename – the name of the file to parse

add_from_resource(resource_path: str) → bool

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 set_current_object to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want 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 error().

Parameters:

resource_path – the path of the resource file to parse

add_from_string(buffer)

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 set_current_object to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want 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 error().

Parameters:

buffer – the string to parse

add_objects_from_file(filename: str, object_ids: Sequence[str]) → bool

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 – the name of the file to parse

  • object_ids – nul-terminated array of objects to build

add_objects_from_resource(resource_path: str, object_ids: Sequence[str]) → bool

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 – the path of the resource file to parse

  • object_ids – nul-terminated array of objects to build

add_objects_from_string(buffer, object_ids)

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 – the string to parse

  • object_ids – nul-terminated array of objects to build

create_closure(function_name: str, flags: BuilderClosureFlags, object: Object | None = None) → Callable[[...], Any] | None

Creates a closure to invoke the function called function_name.

This is using the create_closure() implementation of builder’s BuilderScope.

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

Parameters:

  • function_name – name of the function to look up

  • flags – closure creation flags

  • object – Object to create the closure with

define_builder_scope()
expose_object(name: str, object: Object) → None

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. :func:`~gi.repository.Gtk.Builder.get_object` may be used to determine if an object has already been added with name.

Parameters:

  • name – the name of the object exposed to the builder

  • object – the object to expose

extend_with_template(object: Object, template_type: type, buffer: str, length: int) → bool

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 – the object that is being extended

  • template_type – the type that the template is for

  • buffer – the string to parse

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

get_current_object() → Object | None

Gets the current object set via set_current_object().

get_object(name: str) → Object | None

Gets the object named name.

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

Parameters:

name – name of object to get

get_objects() → list[Object]

Gets all objects that have been constructed by builder.

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

get_scope() → BuilderScope

Gets the scope in use that was set via set_scope().

get_translation_domain() → str | None

Gets the translation domain of builder.

get_type_from_name(type_name: str) → 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 – type name to lookup

set_current_object(current_object: Object | None = None) → None

Sets the current object for the builder.

The current object can be thought of as the this object that the builder is working for and will often be used as the default object when an object is optional.

init_template for example will set the current object to the widget the template is inited for. For functions like new_from_resource, the current object will be None.

Parameters:

current_object – the new current object

set_scope(scope: BuilderScope | None = None) → None

Sets the scope the builder should operate in.

If scope is None, a new BuilderCScope will be created.

Parameters:

scope – the scope to use

set_translation_domain(domain: str | None = None) → None

Sets the translation domain of builder.

Parameters:

domain – the translation domain

value_from_string(pspec: ParamSpec, string: str) → tuple[bool, Any]

Demarshals a value from a string.

This function calls 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 – the GParamSpec for the property

  • string – the string representation of the value

value_from_string_type(type: type, string: str) → tuple[bool, Any]

Demarshals a value from a string.

Unlike value_from_string, this function takes a GType instead of GParamSpec.

Calls 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 – the GType of the value

  • string – the string representation of the value

Properties

class Builder
props.current_object: Object

The object the builder is evaluating for.

props.scope: BuilderScope

The scope the builder is operating in

props.translation_domain: str

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

If the translation domain is None, GtkBuilder uses gettext(), otherwise dgettext().