gtk/auto/

builder.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::Application;
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::{boxed::Box as Box_, fmt, mem::transmute, ptr};

glib::wrapper! {
    /// A GtkBuilder is an auxiliary object that reads textual descriptions
    /// of a user interface and instantiates the described objects. To create
    /// a GtkBuilder from a user interface description, call
    /// `gtk_builder_new_from_file()`, [`from_resource()`][Self::from_resource()] or
    /// [`from_string()`][Self::from_string()].
    ///
    /// In the (unusual) case that you want to add user interface
    /// descriptions from multiple sources to the same GtkBuilder you can
    /// call [`new()`][Self::new()] to get an empty builder and populate it by
    /// (multiple) calls to `gtk_builder_add_from_file()`,
    /// [`BuilderExtManual::add_from_resource()`][crate::prelude::BuilderExtManual::add_from_resource()] or [`BuilderExtManual::add_from_string()`][crate::prelude::BuilderExtManual::add_from_string()].
    ///
    /// A GtkBuilder holds a reference to all objects that it has constructed
    /// and drops these references when it is finalized. This finalization can
    /// cause the destruction of non-widget objects or widgets which are not
    /// contained in a toplevel window. For toplevel windows constructed by a
    /// builder, it is the responsibility of the user to call `gtk_widget_destroy()`
    /// to get rid of them and all the widgets they contain.
    ///
    /// The functions `gtk_builder_get_object()` and [`BuilderExt::objects()`][crate::prelude::BuilderExt::objects()]
    /// can be used to access the widgets in the interface by the names assigned
    /// to them inside the UI description. Toplevel windows returned by these
    /// functions will stay around until the user explicitly destroys them
    /// with `gtk_widget_destroy()`. Other widgets will either be part of a
    /// larger hierarchy constructed by the builder (in which case you should
    /// not have to worry about their lifecycle), or without a parent, in which
    /// case they have to be added to some container to make use of them.
    /// Non-widget objects need to be reffed with `g_object_ref()` to keep them
    /// beyond the lifespan of the builder.
    ///
    /// The function `gtk_builder_connect_signals()` and variants thereof can be
    /// used to connect handlers to the named signals in the description.
    ///
    /// # GtkBuilder UI Definitions # {`BUILDER`-UI}
    ///
    /// GtkBuilder parses textual descriptions of user interfaces which are
    /// specified in an XML format which can be roughly described by the
    /// RELAX NG schema below. We refer to these descriptions as “GtkBuilder
    /// UI definitions” or just “UI definitions” if the context is clear.
    /// Do not confuse GtkBuilder UI Definitions with
    /// [GtkUIManager UI Definitions][XML-UI], which are more limited in scope.
    /// It is common to use `.ui` as the filename extension for files containing
    /// GtkBuilder UI definitions.
    ///
    /// [RELAX NG Compact Syntax](https://gitlab.gnome.org/GNOME/gtk/-/blob/gtk-3-24/gtk/gtkbuilder.rnc)
    ///
    /// The toplevel element is ``<interface>``. It optionally takes a “domain”
    /// attribute, which will make the builder look for translated strings
    /// using `dgettext()` in the domain specified. This can also be done by
    /// calling [`BuilderExt::set_translation_domain()`][crate::prelude::BuilderExt::set_translation_domain()] on the builder.
    /// Objects are described by ``<object>`` elements, which can contain
    /// ``<property>`` elements to set properties, ``<signal>`` elements which
    /// connect signals to handlers, and ``<child>`` elements, which describe
    /// child objects (most often widgets inside a container, but also e.g.
    /// actions in an action group, or columns in a tree model). A ``<child>``
    /// element contains an ``<object>`` element which describes the child object.
    /// The target toolkit version(s) are described by ``<requires>`` elements,
    /// the “lib” attribute specifies the widget library in question (currently
    /// the only supported value is “gtk+”) and the “version” attribute specifies
    /// the target version in the form ``<major>`.`<minor>``. The builder will error
    /// out if the version requirements are not met.
    ///
    /// Typically, the specific kind of object represented by an ``<object>``
    /// element is specified by the “class” attribute. If the type has not
    /// been loaded yet, GTK+ tries to find the ``get_type()`` function from the
    /// class name by applying heuristics. This works in most cases, but if
    /// necessary, it is possible to specify the name of the `get_type()` function
    /// explictly with the "type-func" attribute. As a special case, GtkBuilder
    /// allows to use an object that has been constructed by a `GtkUIManager` in
    /// another part of the UI definition by specifying the id of the `GtkUIManager`
    /// in the “constructor” attribute and the name of the object in the “id”
    /// attribute.
    ///
    /// Objects may be given a name with the “id” attribute, which allows the
    /// application to retrieve them from the builder with `gtk_builder_get_object()`.
    /// An id is also necessary to use the object as property value in other
    /// parts of the UI definition. GTK+ reserves ids starting and ending
    /// with `___` (3 underscores) for its own purposes.
    ///
    /// Setting properties of objects is pretty straightforward with the
    /// ``<property>`` element: the “name” attribute specifies the name of the
    /// property, and the content of the element specifies the value.
    /// If the “translatable” attribute is set to a true value, GTK+ uses
    /// `gettext()` (or `dgettext()` if the builder has a translation domain set)
    /// to find a translation for the value. This happens before the value
    /// is parsed, so it can be used for properties of any type, but it is
    /// probably most useful for string properties. It is also possible to
    /// specify a context to disambiguate short strings, and comments which
    /// may help the translators.
    ///
    /// GtkBuilder can parse textual representations for the most common
    /// property types: characters, strings, integers, floating-point numbers,
    /// booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted
    /// as [`true`], strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted
    /// as [`false`]), enumerations (can be specified by their name, nick or
    /// integer value), flags (can be specified by their name, nick, integer
    /// value, optionally combined with “|”, e.g. “GTK_VISIBLE|GTK_REALIZED”)
    /// and colors (in a format understood by [`gdk::RGBA::parse()`][crate::gdk::RGBA::parse()]).
    ///
    /// GVariants can be specified in the format understood by `g_variant_parse()`,
    /// and pixbufs can be specified as a filename of an image file to load.
    ///
    /// Objects can be referred to by their name and by default refer to
    /// objects declared in the local xml fragment and objects exposed via
    /// [`BuilderExt::expose_object()`][crate::prelude::BuilderExt::expose_object()]. In general, GtkBuilder allows forward
    /// references to objects — declared in the local xml; an object doesn’t
    /// have to be constructed before it can be referred to. The exception
    /// to this rule is that an object has to be constructed before it can
    /// be used as the value of a construct-only property.
    ///
    /// It is also possible to bind a property value to another object's
    /// property value using the attributes
    /// "bind-source" to specify the source object of the binding,
    /// "bind-property" to specify the source property and optionally
    /// "bind-flags" to specify the binding flags.
    /// Internally builder implements this using GBinding objects.
    /// For more information see [`ObjectExt::bind_property()`][crate::glib::prelude::ObjectExt::bind_property()]
    ///
    /// Signal handlers are set up with the ``<signal>`` element. The “name”
    /// attribute specifies the name of the signal, and the “handler” attribute
    /// specifies the function to connect to the signal. By default, GTK+ tries
    /// to find the handler using `g_module_symbol()`, but this can be changed by
    /// passing a custom `GtkBuilderConnectFunc` to
    /// [`BuilderExtManual::connect_signals_full()`][crate::prelude::BuilderExtManual::connect_signals_full()]. The remaining attributes, “after”,
    /// “swapped” and “object”, have the same meaning as the corresponding
    /// parameters of the `g_signal_connect_object()` or
    /// `g_signal_connect_data()` functions. A “last_modification_time”
    /// attribute is also allowed, but it does not have a meaning to the
    /// builder.
    ///
    /// Sometimes it is necessary to refer to widgets which have implicitly
    /// been constructed by GTK+ as part of a composite widget, to set
    /// properties on them or to add further children (e.g. the `vbox` of
    /// a [`Dialog`][crate::Dialog]). This can be achieved by setting the “internal-child”
    /// property of the ``<child>`` element to a true value. Note that GtkBuilder
    /// still requires an ``<object>`` element for the internal child, even if it
    /// has already been constructed.
    ///
    /// A number of widgets have different places where a child can be added
    /// (e.g. tabs vs. page content in notebooks). This can be reflected in
    /// a UI definition by specifying the “type” attribute on a ``<child>``
    /// The possible values for the “type” attribute are described in the
    /// sections describing the widget-specific portions of UI definitions.
    ///
    /// # A GtkBuilder UI Definition
    ///
    ///
    ///
    /// **⚠️ The following code is in xml ⚠️**
    ///
    /// ```xml
    /// <interface>
    ///   <object class="GtkDialog" id="dialog1">
    ///     <child internal-child="vbox">
    ///       <object class="GtkBox" id="vbox1">
    ///         <property name="border-width">10</property>
    ///         <child internal-child="action_area">
    ///           <object class="GtkButtonBox" id="hbuttonbox1">
    ///             <property name="border-width">20</property>
    ///             <child>
    ///               <object class="GtkButton" id="ok_button">
    ///                 <property name="label">gtk-ok</property>
    ///                 <property name="use-stock">TRUE</property>
    ///                 <signal name="clicked" handler="ok_button_clicked"/>
    ///               </object>
    ///             </child>
    ///           </object>
    ///         </child>
    ///       </object>
    ///     </child>
    ///   </object>
    /// </interface>
    /// ```
    ///
    /// Beyond this general structure, several object classes define their
    /// own XML DTD fragments for filling in the ANY placeholders in the DTD
    /// above. Note that a custom element in a ``<child>`` element gets parsed by
    /// the custom tag handler of the parent object, while a custom element in
    /// an ``<object>`` element gets parsed by the custom tag handler of the object.
    ///
    /// These XML fragments are explained in the documentation of the
    /// respective objects.
    ///
    /// Additionally, since 3.10 a special ``<template>`` tag has been added
    /// to the format allowing one to define a widget class’s components.
    /// See the [GtkWidget documentation][composite-templates] for details.
    ///
    /// ## Properties
    ///
    ///
    /// #### `translation-domain`
    ///  The translation domain used when translating property values that
    /// have been marked as translatable in interface descriptions.
    /// If the translation domain is [`None`], [`Builder`][crate::Builder] uses `gettext()`,
    /// otherwise `g_dgettext()`.
    ///
    /// Readable | Writeable
    ///
    /// # Implements
    ///
    /// [`BuilderExt`][trait@crate::prelude::BuilderExt], [`trait@glib::ObjectExt`], [`BuilderExtManual`][trait@crate::prelude::BuilderExtManual]
    #[doc(alias = "GtkBuilder")]
    pub struct Builder(Object<ffi::GtkBuilder, ffi::GtkBuilderClass>);

    match fn {
        type_ => || ffi::gtk_builder_get_type(),
    }
}

impl Builder {
    pub const NONE: Option<&'static Builder> = None;

    /// Creates a new empty builder object.
    ///
    /// This function is only useful if you intend to make multiple calls
    /// to `gtk_builder_add_from_file()`, [`BuilderExtManual::add_from_resource()`][crate::prelude::BuilderExtManual::add_from_resource()]
    /// or [`BuilderExtManual::add_from_string()`][crate::prelude::BuilderExtManual::add_from_string()] in order to merge multiple UI
    /// descriptions into a single builder.
    ///
    /// Most users will probably want to use `gtk_builder_new_from_file()`,
    /// [`from_resource()`][Self::from_resource()] or [`from_string()`][Self::from_string()].
    ///
    /// # Returns
    ///
    /// a new (empty) [`Builder`][crate::Builder] object
    #[doc(alias = "gtk_builder_new")]
    pub fn new() -> Builder {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gtk_builder_new()) }
    }

    /// Builds the [GtkBuilder UI definition][BUILDER-UI]
    /// 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`][crate::Builder] containing the described interface
    #[doc(alias = "gtk_builder_new_from_resource")]
    #[doc(alias = "new_from_resource")]
    pub fn from_resource(resource_path: &str) -> Builder {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gtk_builder_new_from_resource(
                resource_path.to_glib_none().0,
            ))
        }
    }

    /// Builds the user interface described by `string` (in the
    /// [GtkBuilder UI definition][BUILDER-UI] format).
    ///
    /// 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`][crate::Builder] containing the interface described by `string`
    #[doc(alias = "gtk_builder_new_from_string")]
    #[doc(alias = "new_from_string")]
    pub fn from_string(string: &str) -> Builder {
        assert_initialized_main_thread!();
        let length = string.len() as _;
        unsafe {
            from_glib_full(ffi::gtk_builder_new_from_string(
                string.to_glib_none().0,
                length,
            ))
        }
    }
}

impl Default for Builder {
    fn default() -> Self {
        Self::new()
    }
}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::Builder>> Sealed for T {}
}

/// Trait containing all [`struct@Builder`] methods.
///
/// # Implementors
///
/// [`Builder`][struct@crate::Builder]
pub trait BuilderExt: IsA<Builder> + sealed::Sealed + 'static {
    //#[doc(alias = "gtk_builder_add_callback_symbol")]
    //fn add_callback_symbol<P: FnOnce() + 'static>(&self, callback_name: &str, callback_symbol: P) {
    //    unsafe { TODO: call ffi:gtk_builder_add_callback_symbol() }
    //}

    //#[doc(alias = "gtk_builder_add_callback_symbols")]
    //fn add_callback_symbols<P: FnOnce() + 'static>(&self, first_callback_name: &str, first_callback_symbol: P, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
    //    unsafe { TODO: call ffi:gtk_builder_add_callback_symbols() }
    //}

    //#[doc(alias = "gtk_builder_connect_signals")]
    //fn connect_signals(&self, user_data: /*Unimplemented*/Option<Basic: Pointer>) {
    //    unsafe { TODO: call ffi:gtk_builder_connect_signals() }
    //}

    /// Add `object` to the `self` object pool so it can be referenced just like any
    /// other object built by builder.
    /// ## `name`
    /// the name of the object exposed to the builder
    /// ## `object`
    /// the object to expose
    #[doc(alias = "gtk_builder_expose_object")]
    fn expose_object(&self, name: &str, object: &impl IsA<glib::Object>) {
        unsafe {
            ffi::gtk_builder_expose_object(
                self.as_ref().to_glib_none().0,
                name.to_glib_none().0,
                object.as_ref().to_glib_none().0,
            );
        }
    }

    /// Gets the [`Application`][crate::Application] associated with the builder.
    ///
    /// The [`Application`][crate::Application] is used for creating action proxies as requested
    /// from XML that the builder is loading.
    ///
    /// By default, the builder uses the default application: the one from
    /// [`gio::Application::default()`][crate::gio::Application::default()]. If you want to use another application
    /// for constructing proxies, use [`set_application()`][Self::set_application()].
    ///
    /// # Returns
    ///
    /// the application being used by the builder,
    ///  or [`None`]
    #[doc(alias = "gtk_builder_get_application")]
    #[doc(alias = "get_application")]
    fn application(&self) -> Option<Application> {
        unsafe {
            from_glib_none(ffi::gtk_builder_get_application(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// 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 [`Builder`][crate::Builder] instance. It should be freed by
    ///  `g_slist_free()`
    #[doc(alias = "gtk_builder_get_objects")]
    #[doc(alias = "get_objects")]
    fn objects(&self) -> Vec<glib::Object> {
        unsafe {
            FromGlibPtrContainer::from_glib_container(ffi::gtk_builder_get_objects(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the translation domain of `self`.
    ///
    /// # Returns
    ///
    /// the translation domain. This string is owned
    /// by the builder object and must not be modified or freed.
    #[doc(alias = "gtk_builder_get_translation_domain")]
    #[doc(alias = "get_translation_domain")]
    fn translation_domain(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::gtk_builder_get_translation_domain(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Looks up a type by name, using the virtual function that
    /// [`Builder`][crate::Builder] has for that purpose. This is mainly used when
    /// implementing the [`Buildable`][crate::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
    #[doc(alias = "gtk_builder_get_type_from_name")]
    #[doc(alias = "get_type_from_name")]
    fn type_from_name(&self, type_name: &str) -> glib::types::Type {
        unsafe {
            from_glib(ffi::gtk_builder_get_type_from_name(
                self.as_ref().to_glib_none().0,
                type_name.to_glib_none().0,
            ))
        }
    }

    //#[doc(alias = "gtk_builder_lookup_callback_symbol")]
    //fn lookup_callback_symbol(&self, callback_name: &str) -> Option<Box_<dyn Fn() + 'static>> {
    //    unsafe { TODO: call ffi:gtk_builder_lookup_callback_symbol() }
    //}

    /// Sets the application associated with `self`.
    ///
    /// You only need this function if there is more than one [`gio::Application`][crate::gio::Application]
    /// in your process. `application` cannot be [`None`].
    /// ## `application`
    /// a [`Application`][crate::Application]
    #[doc(alias = "gtk_builder_set_application")]
    fn set_application(&self, application: &impl IsA<Application>) {
        unsafe {
            ffi::gtk_builder_set_application(
                self.as_ref().to_glib_none().0,
                application.as_ref().to_glib_none().0,
            );
        }
    }

    /// Sets the translation domain of `self`.
    /// See [`translation-domain`][struct@crate::Builder#translation-domain].
    /// ## `domain`
    /// the translation domain or [`None`]
    #[doc(alias = "gtk_builder_set_translation_domain")]
    fn set_translation_domain(&self, domain: Option<&str>) {
        unsafe {
            ffi::gtk_builder_set_translation_domain(
                self.as_ref().to_glib_none().0,
                domain.to_glib_none().0,
            );
        }
    }

    /// This function demarshals a value from a string. This function
    /// calls [`glib::Value::init()`][crate::glib::Value::init()] on the `value` argument, so it need not be
    /// initialised beforehand.
    ///
    /// This function can handle char, uchar, boolean, int, uint, long,
    /// ulong, enum, flags, float, double, string, `GdkColor`, [`gdk::RGBA`][crate::gdk::RGBA] and
    /// [`Adjustment`][crate::Adjustment] type values. Support for [`Widget`][crate::Widget] type values is
    /// still to come.
    ///
    /// Upon errors [`false`] will be returned and `error` will be assigned a
    /// [`glib::Error`][crate::glib::Error] from the `GTK_BUILDER_ERROR` domain.
    /// ## `pspec`
    /// the [`glib::ParamSpec`][crate::glib::ParamSpec] for the property
    /// ## `string`
    /// the string representation of the value
    ///
    /// # Returns
    ///
    /// [`true`] on success
    ///
    /// ## `value`
    /// the [`glib::Value`][crate::glib::Value] to store the result in
    #[doc(alias = "gtk_builder_value_from_string")]
    fn value_from_string(
        &self,
        pspec: impl AsRef<glib::ParamSpec>,
        string: &str,
    ) -> Result<glib::Value, glib::Error> {
        unsafe {
            let mut value = glib::Value::uninitialized();
            let mut error = ptr::null_mut();
            let is_ok = ffi::gtk_builder_value_from_string(
                self.as_ref().to_glib_none().0,
                pspec.as_ref().to_glib_none().0,
                string.to_glib_none().0,
                value.to_glib_none_mut().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(value)
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Like [`value_from_string()`][Self::value_from_string()], this function demarshals
    /// a value from a string, but takes a `GType` instead of [`glib::ParamSpec`][crate::glib::ParamSpec].
    /// This function calls [`glib::Value::init()`][crate::glib::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
    /// [`glib::Error`][crate::glib::Error] 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 [`glib::Value`][crate::glib::Value] to store the result in
    #[doc(alias = "gtk_builder_value_from_string_type")]
    fn value_from_string_type(
        &self,
        type_: glib::types::Type,
        string: &str,
    ) -> Result<glib::Value, glib::Error> {
        unsafe {
            let mut value = glib::Value::uninitialized();
            let mut error = ptr::null_mut();
            let is_ok = ffi::gtk_builder_value_from_string_type(
                self.as_ref().to_glib_none().0,
                type_.into_glib(),
                string.to_glib_none().0,
                value.to_glib_none_mut().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(value)
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    #[doc(alias = "translation-domain")]
    fn connect_translation_domain_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_translation_domain_trampoline<
            P: IsA<Builder>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GtkBuilder,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Builder::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::translation-domain\0".as_ptr() as *const _,
                Some(transmute::<_, unsafe extern "C" fn()>(
                    notify_translation_domain_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Builder>> BuilderExt for O {}

impl fmt::Display for Builder {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("Builder")
    }
}