gtk4/auto/
page_setup.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, PageOrientation, PaperSize, Unit};
6use glib::translate::*;
7
8glib::wrapper! {
9    /// A [`PageSetup`][crate::PageSetup] object stores the page size, orientation and margins.
10    ///
11    /// The idea is that you can get one of these from the page setup dialog
12    /// and then pass it to the [`PrintOperation`][crate::PrintOperation] when printing.
13    /// The benefit of splitting this out of the [`PrintSettings`][crate::PrintSettings] is that
14    /// these affect the actual layout of the page, and thus need to be set
15    /// long before user prints.
16    ///
17    /// ## Margins
18    ///
19    /// The margins specified in this object are the “print margins”, i.e. the
20    /// parts of the page that the printer cannot print on. These are different
21    /// from the layout margins that a word processor uses; they are typically
22    /// used to determine the minimal size for the layout margins.
23    ///
24    /// To obtain a [`PageSetup`][crate::PageSetup] use [`new()`][Self::new()] to get the defaults,
25    /// or use [`print_run_page_setup_dialog()`][crate::print_run_page_setup_dialog()] to show the page setup dialog
26    /// and receive the resulting page setup.
27    ///
28    /// ## A page setup dialog
29    ///
30    /// **⚠️ The following code is in c ⚠️**
31    ///
32    /// ```c
33    /// static GtkPrintSettings *settings = NULL;
34    /// static GtkPageSetup *page_setup = NULL;
35    ///
36    /// static void
37    /// do_page_setup (void)
38    /// {
39    ///   GtkPageSetup *new_page_setup;
40    ///
41    ///   if (settings == NULL)
42    ///     settings = gtk_print_settings_new ();
43    ///
44    ///   new_page_setup = gtk_print_run_page_setup_dialog (GTK_WINDOW (main_window),
45    ///                                                     page_setup, settings);
46    ///
47    ///   if (page_setup)
48    ///     g_object_unref (page_setup);
49    ///
50    ///   page_setup = new_page_setup;
51    /// }
52    /// ```
53    ///
54    /// # Implements
55    ///
56    /// [`trait@glib::ObjectExt`]
57    #[doc(alias = "GtkPageSetup")]
58    pub struct PageSetup(Object<ffi::GtkPageSetup>);
59
60    match fn {
61        type_ => || ffi::gtk_page_setup_get_type(),
62    }
63}
64
65impl PageSetup {
66    /// Creates a new [`PageSetup`][crate::PageSetup].
67    ///
68    /// # Returns
69    ///
70    /// a new [`PageSetup`][crate::PageSetup].
71    #[doc(alias = "gtk_page_setup_new")]
72    pub fn new() -> PageSetup {
73        assert_initialized_main_thread!();
74        unsafe { from_glib_full(ffi::gtk_page_setup_new()) }
75    }
76
77    /// Reads the page setup from the file @file_name.
78    ///
79    /// Returns a new [`PageSetup`][crate::PageSetup] object with the restored
80    /// page setup, or [`None`] if an error occurred.
81    /// See [`to_file()`][Self::to_file()].
82    /// ## `file_name`
83    /// the filename to read the page setup from
84    ///
85    /// # Returns
86    ///
87    /// the restored [`PageSetup`][crate::PageSetup]
88    #[doc(alias = "gtk_page_setup_new_from_file")]
89    #[doc(alias = "new_from_file")]
90    pub fn from_file(file_name: impl AsRef<std::path::Path>) -> Result<PageSetup, glib::Error> {
91        assert_initialized_main_thread!();
92        unsafe {
93            let mut error = std::ptr::null_mut();
94            let ret =
95                ffi::gtk_page_setup_new_from_file(file_name.as_ref().to_glib_none().0, &mut error);
96            if error.is_null() {
97                Ok(from_glib_full(ret))
98            } else {
99                Err(from_glib_full(error))
100            }
101        }
102    }
103
104    /// Desrialize a page setup from an a{sv} variant.
105    ///
106    /// The variant must be in the format produced by
107    /// [`to_gvariant()`][Self::to_gvariant()].
108    /// ## `variant`
109    /// an a{sv} `GVariant`
110    ///
111    /// # Returns
112    ///
113    /// a new [`PageSetup`][crate::PageSetup] object
114    #[doc(alias = "gtk_page_setup_new_from_gvariant")]
115    #[doc(alias = "new_from_gvariant")]
116    pub fn from_gvariant(variant: &glib::Variant) -> PageSetup {
117        assert_initialized_main_thread!();
118        unsafe {
119            from_glib_full(ffi::gtk_page_setup_new_from_gvariant(
120                variant.to_glib_none().0,
121            ))
122        }
123    }
124
125    /// Reads the page setup from the group @group_name in the key file
126    /// @key_file.
127    ///
128    /// Returns a new [`PageSetup`][crate::PageSetup] object with the restored
129    /// page setup, or [`None`] if an error occurred.
130    /// ## `key_file`
131    /// the `GKeyFile` to retrieve the page_setup from
132    /// ## `group_name`
133    /// the name of the group in the key_file to read
134    ///    to use the default name “Page Setup”
135    ///
136    /// # Returns
137    ///
138    /// the restored [`PageSetup`][crate::PageSetup]
139    #[doc(alias = "gtk_page_setup_new_from_key_file")]
140    #[doc(alias = "new_from_key_file")]
141    pub fn from_key_file(
142        key_file: &glib::KeyFile,
143        group_name: Option<&str>,
144    ) -> Result<PageSetup, glib::Error> {
145        assert_initialized_main_thread!();
146        unsafe {
147            let mut error = std::ptr::null_mut();
148            let ret = ffi::gtk_page_setup_new_from_key_file(
149                key_file.to_glib_none().0,
150                group_name.to_glib_none().0,
151                &mut error,
152            );
153            if error.is_null() {
154                Ok(from_glib_full(ret))
155            } else {
156                Err(from_glib_full(error))
157            }
158        }
159    }
160
161    #[doc(alias = "gtk_page_setup_copy")]
162    #[must_use]
163    pub fn copy(&self) -> PageSetup {
164        unsafe { from_glib_full(ffi::gtk_page_setup_copy(self.to_glib_none().0)) }
165    }
166
167    /// Gets the bottom margin in units of @unit.
168    /// ## `unit`
169    /// the unit for the return value
170    ///
171    /// # Returns
172    ///
173    /// the bottom margin
174    #[doc(alias = "gtk_page_setup_get_bottom_margin")]
175    #[doc(alias = "get_bottom_margin")]
176    pub fn bottom_margin(&self, unit: Unit) -> f64 {
177        unsafe { ffi::gtk_page_setup_get_bottom_margin(self.to_glib_none().0, unit.into_glib()) }
178    }
179
180    /// Gets the left margin in units of @unit.
181    /// ## `unit`
182    /// the unit for the return value
183    ///
184    /// # Returns
185    ///
186    /// the left margin
187    #[doc(alias = "gtk_page_setup_get_left_margin")]
188    #[doc(alias = "get_left_margin")]
189    pub fn left_margin(&self, unit: Unit) -> f64 {
190        unsafe { ffi::gtk_page_setup_get_left_margin(self.to_glib_none().0, unit.into_glib()) }
191    }
192
193    /// Gets the page orientation of the [`PageSetup`][crate::PageSetup].
194    ///
195    /// # Returns
196    ///
197    /// the page orientation
198    #[doc(alias = "gtk_page_setup_get_orientation")]
199    #[doc(alias = "get_orientation")]
200    pub fn orientation(&self) -> PageOrientation {
201        unsafe { from_glib(ffi::gtk_page_setup_get_orientation(self.to_glib_none().0)) }
202    }
203
204    /// Returns the page height in units of @unit.
205    ///
206    /// Note that this function takes orientation
207    /// and margins into consideration.
208    /// See [`paper_height()`][Self::paper_height()].
209    /// ## `unit`
210    /// the unit for the return value
211    ///
212    /// # Returns
213    ///
214    /// the page height.
215    #[doc(alias = "gtk_page_setup_get_page_height")]
216    #[doc(alias = "get_page_height")]
217    pub fn page_height(&self, unit: Unit) -> f64 {
218        unsafe { ffi::gtk_page_setup_get_page_height(self.to_glib_none().0, unit.into_glib()) }
219    }
220
221    /// Returns the page width in units of @unit.
222    ///
223    /// Note that this function takes orientation
224    /// and margins into consideration.
225    /// See [`paper_width()`][Self::paper_width()].
226    /// ## `unit`
227    /// the unit for the return value
228    ///
229    /// # Returns
230    ///
231    /// the page width.
232    #[doc(alias = "gtk_page_setup_get_page_width")]
233    #[doc(alias = "get_page_width")]
234    pub fn page_width(&self, unit: Unit) -> f64 {
235        unsafe { ffi::gtk_page_setup_get_page_width(self.to_glib_none().0, unit.into_glib()) }
236    }
237
238    /// Returns the paper height in units of @unit.
239    ///
240    /// Note that this function takes orientation,
241    /// but not margins into consideration.
242    /// See [`page_height()`][Self::page_height()].
243    /// ## `unit`
244    /// the unit for the return value
245    ///
246    /// # Returns
247    ///
248    /// the paper height.
249    #[doc(alias = "gtk_page_setup_get_paper_height")]
250    #[doc(alias = "get_paper_height")]
251    pub fn paper_height(&self, unit: Unit) -> f64 {
252        unsafe { ffi::gtk_page_setup_get_paper_height(self.to_glib_none().0, unit.into_glib()) }
253    }
254
255    /// Gets the paper size of the [`PageSetup`][crate::PageSetup].
256    ///
257    /// # Returns
258    ///
259    /// the paper size
260    #[doc(alias = "gtk_page_setup_get_paper_size")]
261    #[doc(alias = "get_paper_size")]
262    pub fn paper_size(&self) -> PaperSize {
263        unsafe { from_glib_none(ffi::gtk_page_setup_get_paper_size(self.to_glib_none().0)) }
264    }
265
266    /// Returns the paper width in units of @unit.
267    ///
268    /// Note that this function takes orientation,
269    /// but not margins into consideration.
270    /// See [`page_width()`][Self::page_width()].
271    /// ## `unit`
272    /// the unit for the return value
273    ///
274    /// # Returns
275    ///
276    /// the paper width.
277    #[doc(alias = "gtk_page_setup_get_paper_width")]
278    #[doc(alias = "get_paper_width")]
279    pub fn paper_width(&self, unit: Unit) -> f64 {
280        unsafe { ffi::gtk_page_setup_get_paper_width(self.to_glib_none().0, unit.into_glib()) }
281    }
282
283    /// Gets the right margin in units of @unit.
284    /// ## `unit`
285    /// the unit for the return value
286    ///
287    /// # Returns
288    ///
289    /// the right margin
290    #[doc(alias = "gtk_page_setup_get_right_margin")]
291    #[doc(alias = "get_right_margin")]
292    pub fn right_margin(&self, unit: Unit) -> f64 {
293        unsafe { ffi::gtk_page_setup_get_right_margin(self.to_glib_none().0, unit.into_glib()) }
294    }
295
296    /// Gets the top margin in units of @unit.
297    /// ## `unit`
298    /// the unit for the return value
299    ///
300    /// # Returns
301    ///
302    /// the top margin
303    #[doc(alias = "gtk_page_setup_get_top_margin")]
304    #[doc(alias = "get_top_margin")]
305    pub fn top_margin(&self, unit: Unit) -> f64 {
306        unsafe { ffi::gtk_page_setup_get_top_margin(self.to_glib_none().0, unit.into_glib()) }
307    }
308
309    /// Reads the page setup from the file @file_name.
310    ///
311    /// See [`to_file()`][Self::to_file()].
312    /// ## `file_name`
313    /// the filename to read the page setup from
314    ///
315    /// # Returns
316    ///
317    /// [`true`] on success
318    #[doc(alias = "gtk_page_setup_load_file")]
319    pub fn load_file(&self, file_name: impl AsRef<std::path::Path>) -> Result<(), glib::Error> {
320        unsafe {
321            let mut error = std::ptr::null_mut();
322            let is_ok = ffi::gtk_page_setup_load_file(
323                self.to_glib_none().0,
324                file_name.as_ref().to_glib_none().0,
325                &mut error,
326            );
327            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
328            if error.is_null() {
329                Ok(())
330            } else {
331                Err(from_glib_full(error))
332            }
333        }
334    }
335
336    /// Reads the page setup from the group @group_name in the key file
337    /// @key_file.
338    /// ## `key_file`
339    /// the `GKeyFile` to retrieve the page_setup from
340    /// ## `group_name`
341    /// the name of the group in the key_file to read
342    ///   to use the default name “Page Setup”
343    ///
344    /// # Returns
345    ///
346    /// [`true`] on success
347    #[doc(alias = "gtk_page_setup_load_key_file")]
348    pub fn load_key_file(
349        &self,
350        key_file: &glib::KeyFile,
351        group_name: Option<&str>,
352    ) -> Result<(), glib::Error> {
353        unsafe {
354            let mut error = std::ptr::null_mut();
355            let is_ok = ffi::gtk_page_setup_load_key_file(
356                self.to_glib_none().0,
357                key_file.to_glib_none().0,
358                group_name.to_glib_none().0,
359                &mut error,
360            );
361            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
362            if error.is_null() {
363                Ok(())
364            } else {
365                Err(from_glib_full(error))
366            }
367        }
368    }
369
370    /// Sets the bottom margin of the [`PageSetup`][crate::PageSetup].
371    /// ## `margin`
372    /// the new bottom margin in units of @unit
373    /// ## `unit`
374    /// the units for @margin
375    #[doc(alias = "gtk_page_setup_set_bottom_margin")]
376    pub fn set_bottom_margin(&self, margin: f64, unit: Unit) {
377        unsafe {
378            ffi::gtk_page_setup_set_bottom_margin(self.to_glib_none().0, margin, unit.into_glib());
379        }
380    }
381
382    /// Sets the left margin of the [`PageSetup`][crate::PageSetup].
383    /// ## `margin`
384    /// the new left margin in units of @unit
385    /// ## `unit`
386    /// the units for @margin
387    #[doc(alias = "gtk_page_setup_set_left_margin")]
388    pub fn set_left_margin(&self, margin: f64, unit: Unit) {
389        unsafe {
390            ffi::gtk_page_setup_set_left_margin(self.to_glib_none().0, margin, unit.into_glib());
391        }
392    }
393
394    /// Sets the page orientation of the [`PageSetup`][crate::PageSetup].
395    /// ## `orientation`
396    /// a [`PageOrientation`][crate::PageOrientation] value
397    #[doc(alias = "gtk_page_setup_set_orientation")]
398    pub fn set_orientation(&self, orientation: PageOrientation) {
399        unsafe {
400            ffi::gtk_page_setup_set_orientation(self.to_glib_none().0, orientation.into_glib());
401        }
402    }
403
404    /// Sets the paper size of the [`PageSetup`][crate::PageSetup] without
405    /// changing the margins.
406    ///
407    /// See [`set_paper_size_and_default_margins()`][Self::set_paper_size_and_default_margins()].
408    /// ## `size`
409    /// a [`PaperSize`][crate::PaperSize]
410    #[doc(alias = "gtk_page_setup_set_paper_size")]
411    pub fn set_paper_size(&self, size: &PaperSize) {
412        unsafe {
413            ffi::gtk_page_setup_set_paper_size(
414                self.to_glib_none().0,
415                mut_override(size.to_glib_none().0),
416            );
417        }
418    }
419
420    /// Sets the paper size of the [`PageSetup`][crate::PageSetup] and modifies
421    /// the margins according to the new paper size.
422    /// ## `size`
423    /// a [`PaperSize`][crate::PaperSize]
424    #[doc(alias = "gtk_page_setup_set_paper_size_and_default_margins")]
425    pub fn set_paper_size_and_default_margins(&self, size: &PaperSize) {
426        unsafe {
427            ffi::gtk_page_setup_set_paper_size_and_default_margins(
428                self.to_glib_none().0,
429                mut_override(size.to_glib_none().0),
430            );
431        }
432    }
433
434    /// Sets the right margin of the [`PageSetup`][crate::PageSetup].
435    /// ## `margin`
436    /// the new right margin in units of @unit
437    /// ## `unit`
438    /// the units for @margin
439    #[doc(alias = "gtk_page_setup_set_right_margin")]
440    pub fn set_right_margin(&self, margin: f64, unit: Unit) {
441        unsafe {
442            ffi::gtk_page_setup_set_right_margin(self.to_glib_none().0, margin, unit.into_glib());
443        }
444    }
445
446    /// Sets the top margin of the [`PageSetup`][crate::PageSetup].
447    /// ## `margin`
448    /// the new top margin in units of @unit
449    /// ## `unit`
450    /// the units for @margin
451    #[doc(alias = "gtk_page_setup_set_top_margin")]
452    pub fn set_top_margin(&self, margin: f64, unit: Unit) {
453        unsafe {
454            ffi::gtk_page_setup_set_top_margin(self.to_glib_none().0, margin, unit.into_glib());
455        }
456    }
457
458    /// This function saves the information from @self to @file_name.
459    /// ## `file_name`
460    /// the file to save to
461    ///
462    /// # Returns
463    ///
464    /// [`true`] on success
465    #[doc(alias = "gtk_page_setup_to_file")]
466    pub fn to_file(&self, file_name: impl AsRef<std::path::Path>) -> Result<(), glib::Error> {
467        unsafe {
468            let mut error = std::ptr::null_mut();
469            let is_ok = ffi::gtk_page_setup_to_file(
470                self.to_glib_none().0,
471                file_name.as_ref().to_glib_none().0,
472                &mut error,
473            );
474            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
475            if error.is_null() {
476                Ok(())
477            } else {
478                Err(from_glib_full(error))
479            }
480        }
481    }
482
483    /// Serialize page setup to an a{sv} variant.
484    ///
485    /// # Returns
486    ///
487    /// a new, floating, `GVariant`
488    #[doc(alias = "gtk_page_setup_to_gvariant")]
489    pub fn to_gvariant(&self) -> glib::Variant {
490        unsafe { from_glib_none(ffi::gtk_page_setup_to_gvariant(self.to_glib_none().0)) }
491    }
492
493    /// This function adds the page setup from @self to @key_file.
494    /// ## `key_file`
495    /// the `GKeyFile` to save the page setup to
496    /// ## `group_name`
497    /// the group to add the settings to in @key_file,
498    ///   or [`None`] to use the default name “Page Setup”
499    #[doc(alias = "gtk_page_setup_to_key_file")]
500    pub fn to_key_file(&self, key_file: &glib::KeyFile, group_name: Option<&str>) {
501        unsafe {
502            ffi::gtk_page_setup_to_key_file(
503                self.to_glib_none().0,
504                key_file.to_glib_none().0,
505                group_name.to_glib_none().0,
506            );
507        }
508    }
509}
510
511impl Default for PageSetup {
512    fn default() -> Self {
513        Self::new()
514    }
515}