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}