Struct Builder 

pub struct Builder { /* private fields */ }

` tag to describe a UI bound to a specific widget type. GTK will automatically load the UI definition when instantiating the type, and bind children and signal handlers to instance fields and function symbols.

For more information, see the [Widget documentation](class.Widget.html#building-composite-widgets-from-template-xml) for details.

Properties

current-object

The object the builder is evaluating for.

Readable | Writable

scope

The scope the builder is operating in

Readable | Writable | Construct

translation-domain

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

If the translation domain is None, Builder uses gettext(), otherwise g_dgettext().

Readable | Writable

Implements

[trait@glib::ObjectExt]

GLib type: GObject with reference counted clone semantics.

Implementations

impl Builder

pub fn 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.

Returns

a new (empty) Builder object

pub fn 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.

resource_path

a GResource resource path

Returns

a Builder containing the described interface

pub fn from_string(string: &str) -> 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.

string

a user interface (XML) description

length

the length of @string, or -1

Returns

a Builder containing the interface described by @string

pub fn add_from_resource(&self, resource_path: &str) -> Result<(), Error>

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().

resource_path

the path of the resource file to parse

Returns

true on success, false if an error occurred

pub fn add_from_string(&self, buffer: &str) -> Result<(), Error>

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().

buffer

the string to parse

length

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

Returns

true on success, false if an error occurred

pub fn add_objects_from_file( &self, filename: impl AsRef<Path>, object_ids: &[&str], ) -> Result<(), Error>

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

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 TreeView that depends on its TreeModel), you have to explicitly list all of them in @object_ids.

filename

the name of the file to parse

object_ids

nul-terminated array of objects to build

Returns

true on success, false if an error occurred

pub fn add_objects_from_resource( &self, resource_path: &str, object_ids: &[&str], ) -> Result<(), Error>

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

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 TreeView that depends on its TreeModel), you have to explicitly list all of them in @object_ids.

resource_path

the path of the resource file to parse

object_ids

nul-terminated array of objects to build

Returns

true on success, false if an error occurred

pub fn add_objects_from_string( &self, buffer: &str, object_ids: &[&str], ) -> Result<(), Error>

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

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 TreeView that depends on its TreeModel), you have to explicitly list all of them in @object_ids.

buffer

the string to parse

length

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

object_ids

nul-terminated array of objects to build

Returns

true on success, false if an error occurred

pub fn create_closure( &self, function_name: &str, flags: BuilderClosureFlags, object: Option<&impl IsA<Object>>, ) -> Result<Option<Closure>, Error>

Creates a closure to invoke the function called @function_name.

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

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

function_name

name of the function to look up

flags

closure creation flags

object

Object to create the closure with

Returns

A new closure for invoking @function_name

pub fn expose_object(&self, name: &str, object: &impl IsA<Object>)

Add @object to the @self 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.

name

the name of the object exposed to the builder

object

the object to expose

pub fn extend_with_template( &self, object: &impl IsA<Object>, template_type: Type, buffer: &str, ) -> Result<(), Error>

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

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)

Returns

A positive value on success, 0 if an error occurred

pub fn objects(&self) -> Vec<Object>

Gets all objects that have been constructed by @self.

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

Returns

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

pub fn scope(&self) -> BuilderScope

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

Returns

the current scope

pub fn translation_domain(&self) -> Option<GString>

Gets the translation domain of @self.

Returns

the translation domain

pub fn type_from_name(&self, type_name: &str) -> Type

Looks up a type by name.

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

type_name

type name to lookup

Returns

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

pub fn set_current_object(&self, current_object: Option<&impl IsA<Object>>)

Sets the current object for the @self.

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.

Gtk::Widget::init_template() for example will set the current object to the widget the template is inited for. For functions like from_resource(), the current object will be None.

current_object

the new current object

pub fn set_scope(&self, scope: Option<&impl IsA<BuilderScope>>)

Sets the scope the builder should operate in.

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

scope

the scope to use

pub fn set_translation_domain(&self, domain: Option<&str>)

Sets the translation domain of @self.

domain

the translation domain

pub fn value_from_string( &self, pspec: impl AsRef<ParamSpec>, string: &str, ) -> Result<Value, Error>

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, gdk::RGBA and Adjustment type values.

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

pspec

the GParamSpec for the property

string

the string representation of the value

Returns

true on success

value

the GValue to store the result in

pub fn value_from_string_type( &self, type_: Type, string: &str, ) -> Result<Value, Error>

Demarshals a value from a string.

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

type_

the GType of the value

string

the string representation of the value

Returns

true on success

value

the GValue to store the result in

pub fn connect_current_object_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

pub fn connect_scope_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

pub fn connect_translation_domain_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

impl Builder

pub fn from_file(file_path: impl AsRef<Path>) -> Self

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.

filename

filename of user interface description file

Returns

a Builder containing the described interface

pub fn current_object(&self) -> Option<Object>

Gets the current object set via gtk_builder_set_current_object().

Returns

the current object

pub fn object<T: IsA<Object>>(&self, name: impl IntoGStr) -> Option<T>

Gets the object named @name.

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

name

name of object to get

Returns

the object named @name

pub fn add_from_file(&self, file_path: impl AsRef<Path>) -> Result<(), Error>

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().

filename

the name of the file to parse

Returns

true on success, false if an error occurred

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Self

Returns the “default value” for a type.

impl Eq for Builder

impl HasParamSpec for Builder

type ParamSpec = ParamSpecObject

type SetValue = Builder

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(&str) -> ParamSpecObjectBuilder<'_, Builder>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Builder

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the memory address of this object.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Builder

fn cmp(&self, other: &Self) -> Ordering

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl ParentClassIs for Builder

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for Builder

fn eq(&self, other: &OT) -> bool

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for Builder

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Builder

fn static_type() -> Type

Returns the type identifier of Self.