gtk4/
builder.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
// Take a look at the license at the top of the repository in the LICENSE file.

use std::path::Path;

use glib::{translate::*, Object};

use crate::{ffi, prelude::*, Builder};

impl Builder {
    /// Parses the UI definition in the file @filename.
    ///
    /// If there is an error opening the file or parsing the description then
    /// the program will be aborted. You should only ever attempt to parse
    /// user interface descriptions that are shipped as part of your program.
    /// ## `filename`
    /// filename of user interface description file
    ///
    /// # Returns
    ///
    /// a [`Builder`][crate::Builder] containing the described interface
    #[doc(alias = "gtk_builder_new_from_file")]
    #[doc(alias = "new_from_file")]
    pub fn from_file(file_path: impl AsRef<Path>) -> Self {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gtk_builder_new_from_file(
                file_path.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the current object set via gtk_builder_set_current_object().
    ///
    /// # Returns
    ///
    /// the current object
    #[doc(alias = "gtk_builder_get_current_object")]
    #[doc(alias = "get_current_object")]
    pub fn current_object(&self) -> Option<Object> {
        unsafe {
            let ptr = ffi::gtk_builder_get_current_object(self.to_glib_none().0);
            if ptr.is_null() {
                None
            } else {
                glib::gobject_ffi::g_object_ref(ptr);
                Some(from_glib_full(ptr))
            }
        }
    }

    /// Gets the object named @name.
    ///
    /// Note that this function does not increment the reference count
    /// of the returned object.
    /// ## `name`
    /// name of object to get
    ///
    /// # Returns
    ///
    /// the object named @name
    #[doc(alias = "gtk_builder_get_object")]
    #[doc(alias = "get_object")]
    pub fn object<T: IsA<Object>>(&self, name: impl IntoGStr) -> Option<T> {
        unsafe {
            T::ensure_type();
            name.run_with_gstr(|name| {
                Option::<Object>::from_glib_none(ffi::gtk_builder_get_object(
                    self.to_glib_none().0,
                    name.as_ptr(),
                ))
                .and_then(|obj| obj.dynamic_cast::<T>().ok())
            })
        }
    }

    /// Parses a file containing a UI definition and merges it with
    /// the current contents of @self.
    ///
    /// This function is useful if you need to call
    /// [`set_current_object()`][Self::set_current_object()]) to add user data to
    /// callbacks before loading GtkBuilder UI. Otherwise, you probably
    /// want [`from_file()`][Self::from_file()] instead.
    ///
    /// If an error occurs, 0 will be returned and @error will be assigned a
    /// `GError` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or `G_FILE_ERROR`
    /// domains.
    ///
    /// It’s not really reasonable to attempt to handle failures of this
    /// call. You should not use this function with untrusted files (ie:
    /// files that are not part of your application). Broken [`Builder`][crate::Builder]
    /// files can easily crash your program, and it’s possible that memory
    /// was leaked leading up to the reported failure. The only reasonable
    /// thing to do when an error is detected is to call `g_error()`.
    /// ## `filename`
    /// the name of the file to parse
    ///
    /// # Returns
    ///
    /// [`true`] on success, [`false`] if an error occurred
    #[doc(alias = "gtk_builder_add_from_file")]
    pub fn add_from_file(&self, file_path: impl AsRef<Path>) -> Result<(), glib::Error> {
        unsafe {
            let mut error = ::std::ptr::null_mut();
            ffi::gtk_builder_add_from_file(
                self.to_glib_none().0,
                file_path.as_ref().to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}