:right-sidebar: True Builder =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: Builder(scope_object_or_map=None) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.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 ------------ .. rst-class:: interim-class .. class:: Builder :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Builder Creates a new empty builder object. This function is only useful if you intend to make multiple calls to :obj:`~gi.repository.Gtk.Builder.add_from_file`, :obj:`~gi.repository.Gtk.Builder.add_from_resource` or :obj:`~gi.repository.Gtk.Builder.add_from_string` in order to merge multiple UI descriptions into a single builder. .. classmethod:: new_from_file(filename: str) -> ~gi.repository.Gtk.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. :param filename: filename of user interface description file .. classmethod:: new_from_resource(resource_path: str) -> ~gi.repository.Gtk.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. :param resource_path: a ``GResource`` resource path .. classmethod:: new_from_string(string: str, length: int) -> ~gi.repository.Gtk.Builder Parses the UI definition in ``string``. If ``string`` is :const:`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. :param string: a user interface (XML) description :param length: the length of ``string``, or -1 Methods ------- .. rst-class:: interim-class .. class:: Builder :no-index: .. method:: 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 :obj:`~gi.repository.Gtk.Builder.set_current_object`) to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want :obj:`~gi.repository.Gtk.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 ``:func:`~gi.repository.GLib.error```. :param filename: the name of the file to parse .. method:: 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 :obj:`~gi.repository.Gtk.Builder.set_current_object` to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want :obj:`~gi.repository.Gtk.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 :func:`~gi.repository.GLib.error`. :param resource_path: the path of the resource file to parse .. method:: 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 :obj:`~gi.repository.Gtk.Builder.set_current_object` to add user data to callbacks before loading ``GtkBuilder`` UI. Otherwise, you probably want :obj:`~gi.repository.Gtk.Builder.new_from_string` instead. Upon errors :const:`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 :func:`~gi.repository.GLib.error`. :param buffer: the string to parse .. method:: add_objects_from_file(filename: str, object_ids: ~typing.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``. :param filename: the name of the file to parse :param object_ids: nul-terminated array of objects to build .. method:: add_objects_from_resource(resource_path: str, object_ids: ~typing.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``. :param resource_path: the path of the resource file to parse :param object_ids: nul-terminated array of objects to build .. method:: 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 :const:`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``. :param buffer: the string to parse :param object_ids: nul-terminated array of objects to build .. method:: create_closure(function_name: str, flags: ~gi.repository.Gtk.BuilderClosureFlags, object: ~gi.repository.GObject.Object | None = None) -> ~typing.Callable[[...], ~typing.Any] | None Creates a closure to invoke the function called ``function_name``. This is using the create_closure() implementation of ``builder``'s :obj:`~gi.repository.Gtk.BuilderScope`. If no closure could be created, :const:`None` will be returned and ``error`` will be set. :param function_name: name of the function to look up :param flags: closure creation flags :param object: Object to create the closure with .. method:: define_builder_scope() .. method:: expose_object(name: str, object: ~gi.repository.GObject.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``. :param name: the name of the object exposed to the builder :param object: the object to expose .. method:: extend_with_template(object: ~gi.repository.GObject.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``. :param object: the object that is being extended :param template_type: the type that the template is for :param buffer: the string to parse :param length: the length of ``buffer`` (may be -1 if ``buffer`` is nul-terminated) .. method:: get_current_object() -> ~gi.repository.GObject.Object | None Gets the current object set via :func:`~gi.repository.Gtk.Builder.set_current_object`. .. method:: get_object(name: str) -> ~gi.repository.GObject.Object | None Gets the object named ``name``. Note that this function does not increment the reference count of the returned object. :param name: name of object to get .. method:: get_objects() -> list[~gi.repository.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. .. method:: get_scope() -> ~gi.repository.Gtk.BuilderScope Gets the scope in use that was set via :func:`~gi.repository.Gtk.Builder.set_scope`. .. method:: get_translation_domain() -> str | None Gets the translation domain of ``builder``. .. method:: 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. :param type_name: type name to lookup .. method:: set_current_object(current_object: ~gi.repository.GObject.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. :obj:`~gi.repository.Gtk.Widget.init_template` for example will set the current object to the widget the template is inited for. For functions like :obj:`~gi.repository.Gtk.Builder.new_from_resource`, the current object will be :const:`None`. :param current_object: the new current object .. method:: set_scope(scope: ~gi.repository.Gtk.BuilderScope | None = None) -> None Sets the scope the builder should operate in. If ``scope`` is :const:`None`, a new :obj:`~gi.repository.Gtk.BuilderCScope` will be created. :param scope: the scope to use .. method:: set_translation_domain(domain: str | None = None) -> None Sets the translation domain of ``builder``. :param domain: the translation domain .. method:: value_from_string(pspec: ~gi.repository.GObject.ParamSpec, string: str) -> tuple[bool, ~typing.Any] Demarshals a value from a string. This function calls :func:`~gi.repository.GObject.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 :const:`False` will be returned and ``error`` will be assigned a ``GError`` from the ``%GTK_BUILDER_ERROR`` domain. :param pspec: the ``GParamSpec`` for the property :param string: the string representation of the value .. method:: value_from_string_type(type: type, string: str) -> tuple[bool, ~typing.Any] Demarshals a value from a string. Unlike :obj:`~gi.repository.Gtk.Builder.value_from_string`, this function takes a ``GType`` instead of ``GParamSpec``. Calls :func:`~gi.repository.GObject.Value.init` on the ``value`` argument, so it need not be initialised beforehand. Upon errors :const:`False` will be returned and ``error`` will be assigned a ``GError`` from the ``%GTK_BUILDER_ERROR`` domain. :param type: the ``GType`` of the value :param string: the string representation of the value Properties ---------- .. rst-class:: interim-class .. class:: Builder :no-index: .. attribute:: props.current_object :type: ~gi.repository.GObject.Object The object the builder is evaluating for. .. attribute:: props.scope :type: ~gi.repository.Gtk.BuilderScope The scope the builder is operating in .. attribute:: props.translation_domain :type: str The translation domain used when translating property values that have been marked as translatable. If the translation domain is :const:`None`, ``GtkBuilder`` uses gettext(), otherwise :func:`~gi.repository.GLib.dgettext`.