gtk4/auto/
builder.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, BuilderClosureFlags, BuilderScope};
6use glib::{
7    prelude::*,
8    signal::{connect_raw, SignalHandlerId},
9    translate::*,
10};
11use std::boxed::Box as Box_;
12
13glib::wrapper! {
14    /// A [`Builder`][crate::Builder] reads XML descriptions of a user interface and
15    /// instantiates the described objects.
16    ///
17    /// To create a [`Builder`][crate::Builder] from a user interface description, call
18    /// [`from_file()`][Self::from_file()], [`from_resource()`][Self::from_resource()]
19    /// or [`from_string()`][Self::from_string()].
20    ///
21    /// In the (unusual) case that you want to add user interface
22    /// descriptions from multiple sources to the same [`Builder`][crate::Builder] you can
23    /// call [`new()`][Self::new()] to get an empty builder and populate it by
24    /// (multiple) calls to [`add_from_file()`][Self::add_from_file()],
25    /// [`add_from_resource()`][Self::add_from_resource()] or
26    /// [`add_from_string()`][Self::add_from_string()].
27    ///
28    /// A [`Builder`][crate::Builder] holds a reference to all objects that it has constructed
29    /// and drops these references when it is finalized. This finalization can
30    /// cause the destruction of non-widget objects or widgets which are not
31    /// contained in a toplevel window. For toplevel windows constructed by a
32    /// builder, it is the responsibility of the user to call
33    /// `Gtk::Window::destroy()` to get rid of them and all the widgets
34    /// they contain.
35    ///
36    /// The functions [`object()`][Self::object()] and
37    /// [`objects()`][Self::objects()] can be used to access the widgets in
38    /// the interface by the names assigned to them inside the UI description.
39    /// Toplevel windows returned by these functions will stay around until the
40    /// user explicitly destroys them with `Gtk::Window::destroy()`. Other
41    /// widgets will either be part of a larger hierarchy constructed by the
42    /// builder (in which case you should not have to worry about their lifecycle),
43    /// or without a parent, in which case they have to be added to some container
44    /// to make use of them. Non-widget objects need to be reffed with
45    /// g_object_ref() to keep them beyond the lifespan of the builder.
46    ///
47    /// ## GtkBuilder UI Definitions
48    ///
49    /// [`Builder`][crate::Builder] parses textual descriptions of user interfaces which are
50    /// specified in XML format. We refer to these descriptions as “GtkBuilder
51    /// UI definitions” or just “UI definitions” if the context is clear.
52    ///
53    /// ### Structure of UI definitions
54    ///
55    /// UI definition files are always encoded in UTF-8.
56    ///
57    /// The toplevel element is `<interface>`. It optionally takes a “domain”
58    /// attribute, which will make the builder look for translated strings
59    /// using `dgettext()` in the domain specified. This can also be done by
60    /// calling [`set_translation_domain()`][Self::set_translation_domain()] on the builder.
61    /// For example:
62    ///
63    /// ```xml
64    /// <?xml version="1.0" encoding="UTF-8">
65    /// <interface domain="your-app">
66    ///   ...
67    /// </interface>
68    /// ```
69    ///
70    /// ### Requirements
71    ///
72    /// The target toolkit version(s) are described by `<requires>` elements,
73    /// the “lib” attribute specifies the widget library in question (currently
74    /// the only supported value is “gtk”) and the “version” attribute specifies
75    /// the target version in the form “`<major>`.`<minor>`”. [`Builder`][crate::Builder] will
76    /// error out if the version requirements are not met. For example:
77    ///
78    /// ```xml
79    /// <?xml version="1.0" encoding="UTF-8">
80    /// <interface domain="your-app">
81    ///   <requires lib="gtk" version="4.0" />
82    /// </interface>
83    /// ```
84    ///
85    /// ### Objects
86    ///
87    /// Objects are defined as children of the `<interface>` element.
88    ///
89    /// Objects are described by `<object>` elements, which can contain
90    /// `<property>` elements to set properties, `<signal>` elements which
91    /// connect signals to handlers, and `<child>` elements, which describe
92    /// child objects.
93    ///
94    /// Typically, the specific kind of object represented by an `<object>`
95    /// element is specified by the “class” attribute. If the type has not
96    /// been loaded yet, GTK tries to find the `get_type()` function from the
97    /// class name by applying heuristics. This works in most cases, but if
98    /// necessary, it is possible to specify the name of the `get_type()`
99    /// function explicitly with the "type-func" attribute. If your UI definition
100    /// is referencing internal types, you should make sure to call
101    /// `g_type_ensure()` for each object type before parsing the UI definition.
102    ///
103    /// Objects may be given a name with the “id” attribute, which allows the
104    /// application to retrieve them from the builder with
105    /// [`object()`][Self::object()]. An id is also necessary to use the
106    /// object as property value in other parts of the UI definition. GTK
107    /// reserves ids starting and ending with `___` (three consecutive
108    /// underscores) for its own purposes.
109    ///
110    /// ### Properties
111    ///
112    /// Setting properties of objects is pretty straightforward with the
113    /// `<property>` element: the “name” attribute specifies the name of the
114    /// property, and the content of the element specifies the value:
115    ///
116    /// ```xml
117    /// <object class="GtkButton">
118    ///   <property name="label">Hello, world</property>
119    /// </object>
120    /// ```
121    ///
122    /// If the “translatable” attribute is set to a true value, GTK uses
123    /// `gettext()` (or `dgettext()` if the builder has a translation domain set)
124    /// to find a translation for the value. This happens before the value
125    /// is parsed, so it can be used for properties of any type, but it is
126    /// probably most useful for string properties. It is also possible to
127    /// specify a context to disambiguate short strings, and comments which
128    /// may help the translators:
129    ///
130    /// ```xml
131    /// <object class="GtkButton">
132    ///   <property name="label" translatable="yes" context="button">Hello, world</property>
133    /// </object>
134    /// ```
135    ///
136    /// [`Builder`][crate::Builder] can parse textual representations for the most common
137    /// property types:
138    ///
139    /// - characters
140    /// - strings
141    /// - integers
142    /// - floating-point numbers
143    /// - booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted
144    ///   as true values, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted
145    ///   as false values)
146    /// - string lists (separated by newlines)
147    /// - enumeration types (can be specified by their full C identifier their short
148    ///   name used when registering the enumeration type, or their integer value)
149    /// - flag types (can be specified by their C identifier or short name,
150    ///   optionally combined with “|” for bitwise OR, or a single integer value
151    ///   e.g., “GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”, or “emoji|lowercase” or 520).
152    /// - colors (in the format understood by [`gdk::RGBA::parse()`][crate::gdk::RGBA::parse()])
153    /// - transforms (in the format understood by [`gsk::Transform::parse()`][crate::gsk::Transform::parse()])
154    /// - Pango attribute lists (in the format understood by [`pango::AttrList::to_str()`][crate::pango::AttrList::to_str()])
155    /// - Pango tab arrays (in the format understood by [`pango::TabArray::to_str()`][crate::pango::TabArray::to_str()])
156    /// - Pango font descriptions (in the format understood by [`pango::FontDescription::from_string()`][crate::pango::FontDescription::from_string()])
157    /// - `GVariant` (in the format understood by `GLib::Variant::parse()`)
158    /// - textures (can be specified as an object id, a resource path or a filename of an image file to load relative to the Builder file or the CWD if [`add_from_string()`][Self::add_from_string()] was used)
159    /// - GFile (like textures, can be specified as an object id, a URI or a filename of a file to load relative to the Builder file or the CWD if [`add_from_string()`][Self::add_from_string()] was used)
160    ///
161    /// Objects can be referred to by their name and by default refer to
162    /// objects declared in the local XML fragment and objects exposed via
163    /// [`expose_object()`][Self::expose_object()]. In general, [`Builder`][crate::Builder] allows
164    /// forward references to objects declared in the local XML; an object
165    /// doesn’t have to be constructed before it can be referred to. The
166    /// exception to this rule is that an object has to be constructed before
167    /// it can be used as the value of a construct-only property.
168    ///
169    /// ### Child objects
170    ///
171    /// Many widgets have properties for child widgets, such as
172    /// [`child`][struct@crate::Expander#child]. In this case, the preferred way to
173    /// specify the child widget in a ui file is to simply set the property:
174    ///
175    /// ```xml
176    /// <object class="GtkExpander">
177    ///   <property name="child">
178    ///     <object class="GtkLabel">
179    ///     ...
180    ///     </object>
181    ///   </property>
182    /// </object>
183    /// ```
184    ///
185    /// Generic containers that can contain an arbitrary number of children,
186    /// such as [`Box`][crate::Box] instead use the `<child>` element. A `<child>`
187    /// element contains an `<object>` element which describes the child object.
188    /// Most often, child objects are widgets inside a container, but they can
189    /// also be, e.g., actions in an action group, or columns in a tree model.
190    ///
191    /// Any object type that implements the [`Buildable`][crate::Buildable] interface can
192    /// specify how children may be added to it. Since many objects and widgets that
193    /// are included with GTK already implement the [`Buildable`][crate::Buildable] interface,
194    /// typically child objects can be added using the `<child>` element without
195    /// having to be concerned about the underlying implementation.
196    ///
197    /// See the [[`Widget`][crate::Widget] documentation](class.Widget.html#gtkwidget-as-gtkbuildable)
198    /// for many examples of using [`Builder`][crate::Builder] with widgets, including setting
199    /// child objects using the `<child>` element.
200    ///
201    /// A noteworthy special case to the general rule that only objects implementing
202    /// [`Buildable`][crate::Buildable] may specify how to handle the `<child>` element is that
203    /// [`Builder`][crate::Builder] provides special support for adding objects to a
204    /// `Gio::ListStore` by using the `<child>` element. For instance:
205    ///
206    /// ```xml
207    /// <object class="GListStore">
208    ///   <property name="item-type">MyObject</property>
209    ///   <child>
210    ///     <object class="MyObject" />
211    ///   </child>
212    ///   ...
213    /// </object>
214    /// ```
215    ///
216    /// ### Property bindings
217    ///
218    /// It is also possible to bind a property value to another object's
219    /// property value using the attributes "bind-source" to specify the
220    /// source object of the binding, and optionally, "bind-property" and
221    /// "bind-flags" to specify the source property and source binding flags
222    /// respectively. Internally, [`Builder`][crate::Builder] implements this using
223    /// `GObject::Binding` objects.
224    ///
225    /// For instance, in the example below the “label” property of the
226    /// `bottom_label` widget is bound to the “label” property of the
227    /// `top_button` widget:
228    ///
229    /// ```xml
230    /// <object class="GtkBox">
231    ///   <property name="orientation">vertical</property>
232    ///   <child>
233    ///     <object class="GtkButton" id="top_button">
234    ///       <property name="label">Hello, world</property>
235    ///     </object>
236    ///   </child>
237    ///   <child>
238    ///     <object class="GtkLabel" id="bottom_label">
239    ///       <property name="label"
240    ///                 bind-source="top_button"
241    ///                 bind-property="label"
242    ///                 bind-flags="sync-create" />
243    ///     </object>
244    ///   </child>
245    /// </object>
246    /// ```
247    ///
248    /// For more information, see the documentation of the
249    /// [`ObjectExt::bind_property()`][crate::glib::prelude::ObjectExt::bind_property()] method.
250    ///
251    /// Please note that another way to set up bindings between objects in .ui files
252    /// is to use the [`Expression`][crate::Expression] methodology. See the
253    /// [[`Expression`][crate::Expression] documentation](class.Expression.html#gtkexpression-in-ui-files)
254    /// for more information.
255    ///
256    /// ### Internal children
257    ///
258    /// Sometimes it is necessary to refer to widgets which have implicitly
259    /// been constructed by GTK as part of a composite widget, to set
260    /// properties on them or to add further children (e.g. the content area
261    /// of a [`Dialog`][crate::Dialog]). This can be achieved by setting the “internal-child”
262    /// property of the `<child>` element to a true value. Note that [`Builder`][crate::Builder]
263    /// still requires an `<object>` element for the internal child, even if it
264    /// has already been constructed.
265    ///
266    /// ### Specialized children
267    ///
268    /// A number of widgets have different places where a child can be added
269    /// (e.g. tabs vs. page content in notebooks). This can be reflected in
270    /// a UI definition by specifying the “type” attribute on a `<child>`
271    /// The possible values for the “type” attribute are described in the
272    /// sections describing the widget-specific portions of UI definitions.
273    ///
274    /// ### Signal handlers and function pointers
275    ///
276    /// Signal handlers are set up with the `<signal>` element. The “name”
277    /// attribute specifies the name of the signal, and the “handler” attribute
278    /// specifies the function to connect to the signal.
279    ///
280    /// ```xml
281    /// <object class="GtkButton" id="hello_button">
282    ///   <signal name="clicked" handler="hello_button__clicked" />
283    /// </object>
284    /// ```
285    ///
286    /// The remaining attributes, “after”, “swapped” and “object”, have the
287    /// same meaning as the corresponding parameters of the
288    /// `signal_connect_object()` or `signal_connect_data()`
289    /// functions:
290    ///
291    /// - “after” matches the `G_CONNECT_AFTER` flag, and will ensure that the
292    ///   handler is called after the default class closure for the signal
293    /// - “swapped” matches the `G_CONNECT_SWAPPED` flag, and will swap the
294    ///   instance and closure arguments when invoking the signal handler
295    /// - “object” will bind the signal handler to the lifetime of the object
296    ///   referenced by the attribute
297    ///
298    /// By default "swapped" will be set to "yes" if not specified otherwise, in
299    /// the case where "object" is set, for convenience. A “last_modification_time”
300    /// attribute is also allowed, but it does not have a meaning to the builder.
301    ///
302    /// When compiling applications for Windows, you must declare signal callbacks
303    /// with the `G_MODULE_EXPORT` decorator, or they will not be put in the symbol
304    /// table:
305    ///
306    /// **⚠️ The following code is in c ⚠️**
307    ///
308    /// ```c
309    /// G_MODULE_EXPORT void
310    /// hello_button__clicked (GtkButton *button,
311    ///                        gpointer data)
312    /// {
313    ///   // ...
314    /// }
315    /// ```
316    ///
317    /// On Linux and Unix, this is not necessary; applications should instead
318    /// be compiled with the `-Wl,--export-dynamic` argument inside their compiler
319    /// flags, and linked against `gmodule-export-2.0`.
320    ///
321    /// ## Example UI Definition
322    ///
323    /// ```xml
324    /// <interface>
325    ///   <object class="GtkDialog" id="dialog1">
326    ///     <child internal-child="content_area">
327    ///       <object class="GtkBox">
328    ///         <child internal-child="action_area">
329    ///           <object class="GtkBox">
330    ///             <child>
331    ///               <object class="GtkButton" id="ok_button">
332    ///                 <property name="label" translatable="yes">_Ok</property>
333    ///                 <property name="use-underline">True</property>
334    ///                 <signal name="clicked" handler="ok_button_clicked"/>
335    ///               </object>
336    ///             </child>
337    ///           </object>
338    ///         </child>
339    ///       </object>
340    ///     </child>
341    ///   </object>
342    /// </interface>
343    /// ```
344    ///
345    /// ## Using GtkBuildable for extending UI definitions
346    ///
347    /// Objects can implement the [`Buildable`][crate::Buildable] interface to add custom
348    /// elements and attributes to the XML. Typically, any extension will be
349    /// documented in each type that implements the interface.
350    ///
351    /// ## Templates
352    ///
353    /// When describing a [`Widget`][crate::Widget], you can use the `<template>` tag to
354    /// describe a UI bound to a specific widget type. GTK will automatically load
355    /// the UI definition when instantiating the type, and bind children and
356    /// signal handlers to instance fields and function symbols.
357    ///
358    /// For more information, see the [[`Widget`][crate::Widget] documentation](class.Widget.html#building-composite-widgets-from-template-xml)
359    /// for details.
360    ///
361    /// ## Properties
362    ///
363    ///
364    /// #### `current-object`
365    ///  The object the builder is evaluating for.
366    ///
367    /// Readable | Writeable
368    ///
369    ///
370    /// #### `scope`
371    ///  The scope the builder is operating in
372    ///
373    /// Readable | Writeable | Construct
374    ///
375    ///
376    /// #### `translation-domain`
377    ///  The translation domain used when translating property values that
378    /// have been marked as translatable.
379    ///
380    /// If the translation domain is [`None`], [`Builder`][crate::Builder] uses gettext(),
381    /// otherwise g_dgettext().
382    ///
383    /// Readable | Writeable
384    ///
385    /// # Implements
386    ///
387    /// [`trait@glib::ObjectExt`]
388    #[doc(alias = "GtkBuilder")]
389    pub struct Builder(Object<ffi::GtkBuilder, ffi::GtkBuilderClass>);
390
391    match fn {
392        type_ => || ffi::gtk_builder_get_type(),
393    }
394}
395
396impl Builder {
397    /// Creates a new empty builder object.
398    ///
399    /// This function is only useful if you intend to make multiple calls
400    /// to [`add_from_file()`][Self::add_from_file()], [`add_from_resource()`][Self::add_from_resource()]
401    /// or [`add_from_string()`][Self::add_from_string()] in order to merge multiple UI
402    /// descriptions into a single builder.
403    ///
404    /// # Returns
405    ///
406    /// a new (empty) [`Builder`][crate::Builder] object
407    #[doc(alias = "gtk_builder_new")]
408    pub fn new() -> Builder {
409        assert_initialized_main_thread!();
410        unsafe { from_glib_full(ffi::gtk_builder_new()) }
411    }
412
413    /// Parses the UI definition at @resource_path.
414    ///
415    /// If there is an error locating the resource or parsing the
416    /// description, then the program will be aborted.
417    /// ## `resource_path`
418    /// a `GResource` resource path
419    ///
420    /// # Returns
421    ///
422    /// a [`Builder`][crate::Builder] containing the described interface
423    #[doc(alias = "gtk_builder_new_from_resource")]
424    #[doc(alias = "new_from_resource")]
425    pub fn from_resource(resource_path: &str) -> Builder {
426        assert_initialized_main_thread!();
427        unsafe {
428            from_glib_full(ffi::gtk_builder_new_from_resource(
429                resource_path.to_glib_none().0,
430            ))
431        }
432    }
433
434    /// Parses the UI definition in @string.
435    ///
436    /// If @string is [`None`]-terminated, then @length should be -1.
437    /// If @length is not -1, then it is the length of @string.
438    ///
439    /// If there is an error parsing @string then the program will be
440    /// aborted. You should not attempt to parse user interface description
441    /// from untrusted sources.
442    /// ## `string`
443    /// a user interface (XML) description
444    /// ## `length`
445    /// the length of @string, or -1
446    ///
447    /// # Returns
448    ///
449    /// a [`Builder`][crate::Builder] containing the interface described by @string
450    #[doc(alias = "gtk_builder_new_from_string")]
451    #[doc(alias = "new_from_string")]
452    pub fn from_string(string: &str) -> Builder {
453        assert_initialized_main_thread!();
454        let length = string.len() as _;
455        unsafe {
456            from_glib_full(ffi::gtk_builder_new_from_string(
457                string.to_glib_none().0,
458                length,
459            ))
460        }
461    }
462
463    /// Parses a resource file containing a UI definition
464    /// and merges it with the current contents of @self.
465    ///
466    /// This function is useful if you need to call
467    /// [`set_current_object()`][Self::set_current_object()] to add user data to
468    /// callbacks before loading GtkBuilder UI. Otherwise, you probably
469    /// want [`from_resource()`][Self::from_resource()] instead.
470    ///
471    /// If an error occurs, 0 will be returned and @error will be assigned a
472    /// `GError` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or `G_RESOURCE_ERROR`
473    /// domain.
474    ///
475    /// It’s not really reasonable to attempt to handle failures of this
476    /// call.  The only reasonable thing to do when an error is detected is
477    /// to call g_error().
478    /// ## `resource_path`
479    /// the path of the resource file to parse
480    ///
481    /// # Returns
482    ///
483    /// [`true`] on success, [`false`] if an error occurred
484    #[doc(alias = "gtk_builder_add_from_resource")]
485    pub fn add_from_resource(&self, resource_path: &str) -> Result<(), glib::Error> {
486        unsafe {
487            let mut error = std::ptr::null_mut();
488            let is_ok = ffi::gtk_builder_add_from_resource(
489                self.to_glib_none().0,
490                resource_path.to_glib_none().0,
491                &mut error,
492            );
493            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
494            if error.is_null() {
495                Ok(())
496            } else {
497                Err(from_glib_full(error))
498            }
499        }
500    }
501
502    /// Parses a string containing a UI definition and merges it
503    /// with the current contents of @self.
504    ///
505    /// This function is useful if you need to call
506    /// [`set_current_object()`][Self::set_current_object()] to add user data to
507    /// callbacks before loading [`Builder`][crate::Builder] UI. Otherwise, you probably
508    /// want [`from_string()`][Self::from_string()] instead.
509    ///
510    /// Upon errors [`false`] will be returned and @error will be assigned a
511    /// `GError` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or
512    /// `G_VARIANT_PARSE_ERROR` domain.
513    ///
514    /// It’s not really reasonable to attempt to handle failures of this
515    /// call.  The only reasonable thing to do when an error is detected is
516    /// to call g_error().
517    /// ## `buffer`
518    /// the string to parse
519    /// ## `length`
520    /// the length of @buffer (may be -1 if @buffer is nul-terminated)
521    ///
522    /// # Returns
523    ///
524    /// [`true`] on success, [`false`] if an error occurred
525    #[doc(alias = "gtk_builder_add_from_string")]
526    pub fn add_from_string(&self, buffer: &str) -> Result<(), glib::Error> {
527        let length = buffer.len() as _;
528        unsafe {
529            let mut error = std::ptr::null_mut();
530            let is_ok = ffi::gtk_builder_add_from_string(
531                self.to_glib_none().0,
532                buffer.to_glib_none().0,
533                length,
534                &mut error,
535            );
536            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
537            if error.is_null() {
538                Ok(())
539            } else {
540                Err(from_glib_full(error))
541            }
542        }
543    }
544
545    /// Parses a file containing a UI definition building only the
546    /// requested objects and merges them with the current contents
547    /// of @self.
548    ///
549    /// Upon errors, 0 will be returned and @error will be assigned a
550    /// `GError` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or `G_FILE_ERROR`
551    /// domain.
552    ///
553    /// If you are adding an object that depends on an object that is not
554    /// its child (for instance a [`TreeView`][crate::TreeView] that depends on its
555    /// [`TreeModel`][crate::TreeModel]), you have to explicitly list all of them in @object_ids.
556    /// ## `filename`
557    /// the name of the file to parse
558    /// ## `object_ids`
559    /// nul-terminated array of objects to build
560    ///
561    /// # Returns
562    ///
563    /// [`true`] on success, [`false`] if an error occurred
564    #[doc(alias = "gtk_builder_add_objects_from_file")]
565    pub fn add_objects_from_file(
566        &self,
567        filename: impl AsRef<std::path::Path>,
568        object_ids: &[&str],
569    ) -> Result<(), glib::Error> {
570        unsafe {
571            let mut error = std::ptr::null_mut();
572            let is_ok = ffi::gtk_builder_add_objects_from_file(
573                self.to_glib_none().0,
574                filename.as_ref().to_glib_none().0,
575                object_ids.to_glib_none().0,
576                &mut error,
577            );
578            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
579            if error.is_null() {
580                Ok(())
581            } else {
582                Err(from_glib_full(error))
583            }
584        }
585    }
586
587    /// Parses a resource file containing a UI definition, building
588    /// only the requested objects and merges them with the current
589    /// contents of @self.
590    ///
591    /// Upon errors, 0 will be returned and @error will be assigned a
592    /// `GError` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or `G_RESOURCE_ERROR`
593    /// domain.
594    ///
595    /// If you are adding an object that depends on an object that is not
596    /// its child (for instance a [`TreeView`][crate::TreeView] that depends on its
597    /// [`TreeModel`][crate::TreeModel]), you have to explicitly list all of them in @object_ids.
598    /// ## `resource_path`
599    /// the path of the resource file to parse
600    /// ## `object_ids`
601    /// nul-terminated array of objects to build
602    ///
603    /// # Returns
604    ///
605    /// [`true`] on success, [`false`] if an error occurred
606    #[doc(alias = "gtk_builder_add_objects_from_resource")]
607    pub fn add_objects_from_resource(
608        &self,
609        resource_path: &str,
610        object_ids: &[&str],
611    ) -> Result<(), glib::Error> {
612        unsafe {
613            let mut error = std::ptr::null_mut();
614            let is_ok = ffi::gtk_builder_add_objects_from_resource(
615                self.to_glib_none().0,
616                resource_path.to_glib_none().0,
617                object_ids.to_glib_none().0,
618                &mut error,
619            );
620            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
621            if error.is_null() {
622                Ok(())
623            } else {
624                Err(from_glib_full(error))
625            }
626        }
627    }
628
629    /// Parses a string containing a UI definition, building only the
630    /// requested objects and merges them with the current contents of
631    /// @self.
632    ///
633    /// Upon errors [`false`] will be returned and @error will be assigned a
634    /// `GError` from the `GTK_BUILDER_ERROR` or `G_MARKUP_ERROR` domain.
635    ///
636    /// If you are adding an object that depends on an object that is not
637    /// its child (for instance a [`TreeView`][crate::TreeView] that depends on its
638    /// [`TreeModel`][crate::TreeModel]), you have to explicitly list all of them in @object_ids.
639    /// ## `buffer`
640    /// the string to parse
641    /// ## `length`
642    /// the length of @buffer (may be -1 if @buffer is nul-terminated)
643    /// ## `object_ids`
644    /// nul-terminated array of objects to build
645    ///
646    /// # Returns
647    ///
648    /// [`true`] on success, [`false`] if an error occurred
649    #[doc(alias = "gtk_builder_add_objects_from_string")]
650    pub fn add_objects_from_string(
651        &self,
652        buffer: &str,
653        object_ids: &[&str],
654    ) -> Result<(), glib::Error> {
655        let length = buffer.len() as _;
656        unsafe {
657            let mut error = std::ptr::null_mut();
658            let is_ok = ffi::gtk_builder_add_objects_from_string(
659                self.to_glib_none().0,
660                buffer.to_glib_none().0,
661                length,
662                object_ids.to_glib_none().0,
663                &mut error,
664            );
665            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
666            if error.is_null() {
667                Ok(())
668            } else {
669                Err(from_glib_full(error))
670            }
671        }
672    }
673
674    /// Creates a closure to invoke the function called @function_name.
675    ///
676    /// This is using the create_closure() implementation of @self's
677    /// [`BuilderScope`][crate::BuilderScope].
678    ///
679    /// If no closure could be created, [`None`] will be returned and @error
680    /// will be set.
681    /// ## `function_name`
682    /// name of the function to look up
683    /// ## `flags`
684    /// closure creation flags
685    /// ## `object`
686    /// Object to create the closure with
687    ///
688    /// # Returns
689    ///
690    /// A new closure for invoking @function_name
691    #[doc(alias = "gtk_builder_create_closure")]
692    pub fn create_closure(
693        &self,
694        function_name: &str,
695        flags: BuilderClosureFlags,
696        object: Option<&impl IsA<glib::Object>>,
697    ) -> Result<Option<glib::Closure>, glib::Error> {
698        unsafe {
699            let mut error = std::ptr::null_mut();
700            let ret = ffi::gtk_builder_create_closure(
701                self.to_glib_none().0,
702                function_name.to_glib_none().0,
703                flags.into_glib(),
704                object.map(|p| p.as_ref()).to_glib_none().0,
705                &mut error,
706            );
707            if error.is_null() {
708                Ok(from_glib_full(ret))
709            } else {
710                Err(from_glib_full(error))
711            }
712        }
713    }
714
715    /// Add @object to the @self object pool so it can be
716    /// referenced just like any other object built by builder.
717    ///
718    /// Only a single object may be added using @name. However,
719    /// it is not an error to expose the same object under multiple
720    /// names. `gtk_builder_get_object()` may be used to determine
721    /// if an object has already been added with @name.
722    /// ## `name`
723    /// the name of the object exposed to the builder
724    /// ## `object`
725    /// the object to expose
726    #[doc(alias = "gtk_builder_expose_object")]
727    pub fn expose_object(&self, name: &str, object: &impl IsA<glib::Object>) {
728        unsafe {
729            ffi::gtk_builder_expose_object(
730                self.to_glib_none().0,
731                name.to_glib_none().0,
732                object.as_ref().to_glib_none().0,
733            );
734        }
735    }
736
737    /// Main private entry point for building composite components
738    /// from template XML.
739    ///
740    /// Most likely you do not need to call this function in applications as
741    /// templates are handled by [`Widget`][crate::Widget].
742    /// ## `object`
743    /// the object that is being extended
744    /// ## `template_type`
745    /// the type that the template is for
746    /// ## `buffer`
747    /// the string to parse
748    /// ## `length`
749    /// the length of @buffer (may be -1 if @buffer is nul-terminated)
750    ///
751    /// # Returns
752    ///
753    /// A positive value on success, 0 if an error occurred
754    #[doc(alias = "gtk_builder_extend_with_template")]
755    pub fn extend_with_template(
756        &self,
757        object: &impl IsA<glib::Object>,
758        template_type: glib::types::Type,
759        buffer: &str,
760    ) -> Result<(), glib::Error> {
761        let length = buffer.len() as _;
762        unsafe {
763            let mut error = std::ptr::null_mut();
764            let is_ok = ffi::gtk_builder_extend_with_template(
765                self.to_glib_none().0,
766                object.as_ref().to_glib_none().0,
767                template_type.into_glib(),
768                buffer.to_glib_none().0,
769                length,
770                &mut error,
771            );
772            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
773            if error.is_null() {
774                Ok(())
775            } else {
776                Err(from_glib_full(error))
777            }
778        }
779    }
780
781    /// Gets all objects that have been constructed by @self.
782    ///
783    /// Note that this function does not increment the reference
784    /// counts of the returned objects.
785    ///
786    /// # Returns
787    ///
788    /// a
789    ///   newly-allocated `GSList` containing all the objects
790    ///   constructed by the `GtkBuilder instance`. It should be
791    ///   freed by g_slist_free()
792    #[doc(alias = "gtk_builder_get_objects")]
793    #[doc(alias = "get_objects")]
794    pub fn objects(&self) -> Vec<glib::Object> {
795        unsafe {
796            FromGlibPtrContainer::from_glib_container(ffi::gtk_builder_get_objects(
797                self.to_glib_none().0,
798            ))
799        }
800    }
801
802    /// Gets the scope in use that was set via gtk_builder_set_scope().
803    ///
804    /// # Returns
805    ///
806    /// the current scope
807    #[doc(alias = "gtk_builder_get_scope")]
808    #[doc(alias = "get_scope")]
809    pub fn scope(&self) -> BuilderScope {
810        unsafe { from_glib_none(ffi::gtk_builder_get_scope(self.to_glib_none().0)) }
811    }
812
813    /// Gets the translation domain of @self.
814    ///
815    /// # Returns
816    ///
817    /// the translation domain
818    #[doc(alias = "gtk_builder_get_translation_domain")]
819    #[doc(alias = "get_translation_domain")]
820    #[doc(alias = "translation-domain")]
821    pub fn translation_domain(&self) -> Option<glib::GString> {
822        unsafe {
823            from_glib_none(ffi::gtk_builder_get_translation_domain(
824                self.to_glib_none().0,
825            ))
826        }
827    }
828
829    /// Looks up a type by name.
830    ///
831    /// This is using the virtual function that [`Builder`][crate::Builder] has
832    /// for that purpose. This is mainly used when implementing
833    /// the [`Buildable`][crate::Buildable] interface on a type.
834    /// ## `type_name`
835    /// type name to lookup
836    ///
837    /// # Returns
838    ///
839    /// the `GType` found for @type_name or `G_TYPE_INVALID`
840    ///   if no type was found
841    #[doc(alias = "gtk_builder_get_type_from_name")]
842    #[doc(alias = "get_type_from_name")]
843    pub fn type_from_name(&self, type_name: &str) -> glib::types::Type {
844        unsafe {
845            from_glib(ffi::gtk_builder_get_type_from_name(
846                self.to_glib_none().0,
847                type_name.to_glib_none().0,
848            ))
849        }
850    }
851
852    /// Sets the current object for the @self.
853    ///
854    /// The current object can be thought of as the `this` object that the
855    /// builder is working for and will often be used as the default object
856    /// when an object is optional.
857    ///
858    /// `Gtk::Widget::init_template()` for example will set the current
859    /// object to the widget the template is inited for. For functions like
860    /// [`from_resource()`][Self::from_resource()], the current object will be [`None`].
861    /// ## `current_object`
862    /// the new current object
863    #[doc(alias = "gtk_builder_set_current_object")]
864    #[doc(alias = "current-object")]
865    pub fn set_current_object(&self, current_object: Option<&impl IsA<glib::Object>>) {
866        unsafe {
867            ffi::gtk_builder_set_current_object(
868                self.to_glib_none().0,
869                current_object.map(|p| p.as_ref()).to_glib_none().0,
870            );
871        }
872    }
873
874    /// Sets the scope the builder should operate in.
875    ///
876    /// If @scope is [`None`], a new `Gtk::BuilderCScope` will be created.
877    /// ## `scope`
878    /// the scope to use
879    #[doc(alias = "gtk_builder_set_scope")]
880    #[doc(alias = "scope")]
881    pub fn set_scope(&self, scope: Option<&impl IsA<BuilderScope>>) {
882        unsafe {
883            ffi::gtk_builder_set_scope(
884                self.to_glib_none().0,
885                scope.map(|p| p.as_ref()).to_glib_none().0,
886            );
887        }
888    }
889
890    /// Sets the translation domain of @self.
891    /// ## `domain`
892    /// the translation domain
893    #[doc(alias = "gtk_builder_set_translation_domain")]
894    #[doc(alias = "translation-domain")]
895    pub fn set_translation_domain(&self, domain: Option<&str>) {
896        unsafe {
897            ffi::gtk_builder_set_translation_domain(self.to_glib_none().0, domain.to_glib_none().0);
898        }
899    }
900
901    /// Demarshals a value from a string.
902    ///
903    /// This function calls g_value_init() on the @value argument,
904    /// so it need not be initialised beforehand.
905    ///
906    /// Can handle char, uchar, boolean, int, uint, long,
907    /// ulong, enum, flags, float, double, string, [`gdk::RGBA`][crate::gdk::RGBA] and
908    /// [`Adjustment`][crate::Adjustment] type values.
909    ///
910    /// Upon errors [`false`] will be returned and @error will be
911    /// assigned a `GError` from the `GTK_BUILDER_ERROR` domain.
912    /// ## `pspec`
913    /// the `GParamSpec` for the property
914    /// ## `string`
915    /// the string representation of the value
916    ///
917    /// # Returns
918    ///
919    /// [`true`] on success
920    ///
921    /// ## `value`
922    /// the `GValue` to store the result in
923    #[doc(alias = "gtk_builder_value_from_string")]
924    pub fn value_from_string(
925        &self,
926        pspec: impl AsRef<glib::ParamSpec>,
927        string: &str,
928    ) -> Result<glib::Value, glib::Error> {
929        unsafe {
930            let mut value = glib::Value::uninitialized();
931            let mut error = std::ptr::null_mut();
932            let is_ok = ffi::gtk_builder_value_from_string(
933                self.to_glib_none().0,
934                pspec.as_ref().to_glib_none().0,
935                string.to_glib_none().0,
936                value.to_glib_none_mut().0,
937                &mut error,
938            );
939            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
940            if error.is_null() {
941                Ok(value)
942            } else {
943                Err(from_glib_full(error))
944            }
945        }
946    }
947
948    /// Demarshals a value from a string.
949    ///
950    /// Unlike [`value_from_string()`][Self::value_from_string()], this function
951    /// takes a `GType` instead of `GParamSpec`.
952    ///
953    /// Calls g_value_init() on the @value argument, so it
954    /// need not be initialised beforehand.
955    ///
956    /// Upon errors [`false`] will be returned and @error will be
957    /// assigned a `GError` from the `GTK_BUILDER_ERROR` domain.
958    /// ## `type_`
959    /// the `GType` of the value
960    /// ## `string`
961    /// the string representation of the value
962    ///
963    /// # Returns
964    ///
965    /// [`true`] on success
966    ///
967    /// ## `value`
968    /// the `GValue` to store the result in
969    #[doc(alias = "gtk_builder_value_from_string_type")]
970    pub fn value_from_string_type(
971        &self,
972        type_: glib::types::Type,
973        string: &str,
974    ) -> Result<glib::Value, glib::Error> {
975        unsafe {
976            let mut value = glib::Value::uninitialized();
977            let mut error = std::ptr::null_mut();
978            let is_ok = ffi::gtk_builder_value_from_string_type(
979                self.to_glib_none().0,
980                type_.into_glib(),
981                string.to_glib_none().0,
982                value.to_glib_none_mut().0,
983                &mut error,
984            );
985            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
986            if error.is_null() {
987                Ok(value)
988            } else {
989                Err(from_glib_full(error))
990            }
991        }
992    }
993
994    #[doc(alias = "current-object")]
995    pub fn connect_current_object_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
996        unsafe extern "C" fn notify_current_object_trampoline<F: Fn(&Builder) + 'static>(
997            this: *mut ffi::GtkBuilder,
998            _param_spec: glib::ffi::gpointer,
999            f: glib::ffi::gpointer,
1000        ) {
1001            let f: &F = &*(f as *const F);
1002            f(&from_glib_borrow(this))
1003        }
1004        unsafe {
1005            let f: Box_<F> = Box_::new(f);
1006            connect_raw(
1007                self.as_ptr() as *mut _,
1008                b"notify::current-object\0".as_ptr() as *const _,
1009                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1010                    notify_current_object_trampoline::<F> as *const (),
1011                )),
1012                Box_::into_raw(f),
1013            )
1014        }
1015    }
1016
1017    #[doc(alias = "scope")]
1018    pub fn connect_scope_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
1019        unsafe extern "C" fn notify_scope_trampoline<F: Fn(&Builder) + 'static>(
1020            this: *mut ffi::GtkBuilder,
1021            _param_spec: glib::ffi::gpointer,
1022            f: glib::ffi::gpointer,
1023        ) {
1024            let f: &F = &*(f as *const F);
1025            f(&from_glib_borrow(this))
1026        }
1027        unsafe {
1028            let f: Box_<F> = Box_::new(f);
1029            connect_raw(
1030                self.as_ptr() as *mut _,
1031                b"notify::scope\0".as_ptr() as *const _,
1032                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1033                    notify_scope_trampoline::<F> as *const (),
1034                )),
1035                Box_::into_raw(f),
1036            )
1037        }
1038    }
1039
1040    #[doc(alias = "translation-domain")]
1041    pub fn connect_translation_domain_notify<F: Fn(&Self) + 'static>(
1042        &self,
1043        f: F,
1044    ) -> SignalHandlerId {
1045        unsafe extern "C" fn notify_translation_domain_trampoline<F: Fn(&Builder) + 'static>(
1046            this: *mut ffi::GtkBuilder,
1047            _param_spec: glib::ffi::gpointer,
1048            f: glib::ffi::gpointer,
1049        ) {
1050            let f: &F = &*(f as *const F);
1051            f(&from_glib_borrow(this))
1052        }
1053        unsafe {
1054            let f: Box_<F> = Box_::new(f);
1055            connect_raw(
1056                self.as_ptr() as *mut _,
1057                b"notify::translation-domain\0".as_ptr() as *const _,
1058                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
1059                    notify_translation_domain_trampoline::<F> as *const (),
1060                )),
1061                Box_::into_raw(f),
1062            )
1063        }
1064    }
1065}
1066
1067impl Default for Builder {
1068    fn default() -> Self {
1069        Self::new()
1070    }
1071}