gtk/auto/

size_group.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::{Buildable, SizeGroupMode, Widget, ffi};
use glib::{
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// [`SizeGroup`][crate::SizeGroup] provides a mechanism for grouping a number of widgets
    /// together so they all request the same amount of space. This is
    /// typically useful when you want a column of widgets to have the same
    /// size, but you can’t use a [`Grid`][crate::Grid] widget.
    ///
    /// In detail, the size requested for each widget in a [`SizeGroup`][crate::SizeGroup] is
    /// the maximum of the sizes that would have been requested for each
    /// widget in the size group if they were not in the size group. The mode
    /// of the size group (see [`SizeGroupExt::set_mode()`][crate::prelude::SizeGroupExt::set_mode()]) determines whether
    /// this applies to the horizontal size, the vertical size, or both sizes.
    ///
    /// Note that size groups only affect the amount of space requested, not
    /// the size that the widgets finally receive. If you want the widgets in
    /// a [`SizeGroup`][crate::SizeGroup] to actually be the same size, you need to pack them in
    /// such a way that they get the size they request and not more. For
    /// example, if you are packing your widgets into a table, you would not
    /// include the `GTK_FILL` flag.
    ///
    /// [`SizeGroup`][crate::SizeGroup] objects are referenced by each widget in the size group,
    /// so once you have added all widgets to a [`SizeGroup`][crate::SizeGroup], you can drop
    /// the initial reference to the size group with `g_object_unref()`. If the
    /// widgets in the size group are subsequently destroyed, then they will
    /// be removed from the size group and drop their references on the size
    /// group; when all widgets have been removed, the size group will be
    /// freed.
    ///
    /// Widgets can be part of multiple size groups; GTK+ will compute the
    /// horizontal size of a widget from the horizontal requisition of all
    /// widgets that can be reached from the widget by a chain of size groups
    /// of type [`SizeGroupMode::Horizontal`][crate::SizeGroupMode::Horizontal] or [`SizeGroupMode::Both`][crate::SizeGroupMode::Both], and the
    /// vertical size from the vertical requisition of all widgets that can be
    /// reached from the widget by a chain of size groups of type
    /// [`SizeGroupMode::Vertical`][crate::SizeGroupMode::Vertical] or [`SizeGroupMode::Both`][crate::SizeGroupMode::Both].
    ///
    /// Note that only non-contextual sizes of every widget are ever consulted
    /// by size groups (since size groups have no knowledge of what size a widget
    /// will be allocated in one dimension, it cannot derive how much height
    /// a widget will receive for a given width). When grouping widgets that
    /// trade height for width in mode [`SizeGroupMode::Vertical`][crate::SizeGroupMode::Vertical] or [`SizeGroupMode::Both`][crate::SizeGroupMode::Both]:
    /// the height for the minimum width will be the requested height for all
    /// widgets in the group. The same is of course true when horizontally grouping
    /// width for height widgets.
    ///
    /// Widgets that trade height-for-width should set a reasonably large minimum width
    /// by way of [`width-chars`][struct@crate::Label#width-chars] for instance. Widgets with static sizes as well
    /// as widgets that grow (such as ellipsizing text) need no such considerations.
    ///
    /// # GtkSizeGroup as GtkBuildable
    ///
    /// Size groups can be specified in a UI definition by placing an ``<object>``
    /// element with `class="GtkSizeGroup"` somewhere in the UI definition. The
    /// widgets that belong to the size group are specified by a ``<widgets>`` element
    /// that may contain multiple ``<widget>`` elements, one for each member of the
    /// size group. The ”name” attribute gives the id of the widget.
    ///
    /// An example of a UI definition fragment with GtkSizeGroup:
    ///
    ///
    ///
    /// **⚠️ The following code is in xml ⚠️**
    ///
    /// ```xml
    /// <object class="GtkSizeGroup">
    ///   <property name="mode">GTK_SIZE_GROUP_HORIZONTAL</property>
    ///   <widgets>
    ///     <widget name="radio1"/>
    ///     <widget name="radio2"/>
    ///   </widgets>
    /// </object>
    /// ```
    ///
    /// ## Properties
    ///
    ///
    /// #### `ignore-hidden`
    ///  If [`true`], unmapped widgets are ignored when determining
    /// the size of the group.
    ///
    /// Readable | Writable
    ///
    ///
    /// #### `mode`
    ///  Readable | Writable
    ///
    /// # Implements
    ///
    /// [`SizeGroupExt`][trait@crate::prelude::SizeGroupExt], [`trait@glib::ObjectExt`], [`BuildableExt`][trait@crate::prelude::BuildableExt], [`BuildableExtManual`][trait@crate::prelude::BuildableExtManual]
    #[doc(alias = "GtkSizeGroup")]
    pub struct SizeGroup(Object<ffi::GtkSizeGroup, ffi::GtkSizeGroupClass>) @implements Buildable;

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

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

    /// Create a new [`SizeGroup`][crate::SizeGroup].
    /// ## `mode`
    /// the mode for the new size group.
    ///
    /// # Returns
    ///
    /// a newly created [`SizeGroup`][crate::SizeGroup]
    #[doc(alias = "gtk_size_group_new")]
    pub fn new(mode: SizeGroupMode) -> SizeGroup {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gtk_size_group_new(mode.into_glib())) }
    }

    // rustdoc-stripper-ignore-next
    /// Creates a new builder-pattern struct instance to construct [`SizeGroup`] objects.
    ///
    /// This method returns an instance of [`SizeGroupBuilder`](crate::builders::SizeGroupBuilder) which can be used to create [`SizeGroup`] objects.
    pub fn builder() -> SizeGroupBuilder {
        SizeGroupBuilder::new()
    }
}

impl Default for SizeGroup {
    fn default() -> Self {
        glib::object::Object::new::<Self>()
    }
}

// rustdoc-stripper-ignore-next
/// A [builder-pattern] type to construct [`SizeGroup`] objects.
///
/// [builder-pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
#[must_use = "The builder must be built to be used"]
pub struct SizeGroupBuilder {
    builder: glib::object::ObjectBuilder<'static, SizeGroup>,
}

impl SizeGroupBuilder {
    fn new() -> Self {
        Self {
            builder: glib::object::Object::builder(),
        }
    }

    pub fn mode(self, mode: SizeGroupMode) -> Self {
        Self {
            builder: self.builder.property("mode", mode),
        }
    }

    // rustdoc-stripper-ignore-next
    /// Build the [`SizeGroup`].
    #[must_use = "Building the object from the builder is usually expensive and is not expected to have side effects"]
    pub fn build(self) -> SizeGroup {
        assert_initialized_main_thread!();
        self.builder.build()
    }
}

/// Trait containing all [`struct@SizeGroup`] methods.
///
/// # Implementors
///
/// [`SizeGroup`][struct@crate::SizeGroup]
pub trait SizeGroupExt: IsA<SizeGroup> + 'static {
    /// Adds a widget to a [`SizeGroup`][crate::SizeGroup]. In the future, the requisition
    /// of the widget will be determined as the maximum of its requisition
    /// and the requisition of the other widgets in the size group.
    /// Whether this applies horizontally, vertically, or in both directions
    /// depends on the mode of the size group. See [`set_mode()`][Self::set_mode()].
    ///
    /// When the widget is destroyed or no longer referenced elsewhere, it will
    /// be removed from the size group.
    /// ## `widget`
    /// the [`Widget`][crate::Widget] to add
    #[doc(alias = "gtk_size_group_add_widget")]
    fn add_widget(&self, widget: &impl IsA<Widget>) {
        unsafe {
            ffi::gtk_size_group_add_widget(
                self.as_ref().to_glib_none().0,
                widget.as_ref().to_glib_none().0,
            );
        }
    }

    /// Gets the current mode of the size group. See [`set_mode()`][Self::set_mode()].
    ///
    /// # Returns
    ///
    /// the current mode of the size group.
    #[doc(alias = "gtk_size_group_get_mode")]
    #[doc(alias = "get_mode")]
    fn mode(&self) -> SizeGroupMode {
        unsafe { from_glib(ffi::gtk_size_group_get_mode(self.as_ref().to_glib_none().0)) }
    }

    /// Returns the list of widgets associated with `self`.
    ///
    /// # Returns
    ///
    /// a `GSList` of
    ///  widgets. The list is owned by GTK+ and should not be modified.
    #[doc(alias = "gtk_size_group_get_widgets")]
    #[doc(alias = "get_widgets")]
    fn widgets(&self) -> Vec<Widget> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::gtk_size_group_get_widgets(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Removes a widget from a [`SizeGroup`][crate::SizeGroup].
    /// ## `widget`
    /// the [`Widget`][crate::Widget] to remove
    #[doc(alias = "gtk_size_group_remove_widget")]
    fn remove_widget(&self, widget: &impl IsA<Widget>) {
        unsafe {
            ffi::gtk_size_group_remove_widget(
                self.as_ref().to_glib_none().0,
                widget.as_ref().to_glib_none().0,
            );
        }
    }

    /// Sets the [`SizeGroupMode`][crate::SizeGroupMode] of the size group. The mode of the size
    /// group determines whether the widgets in the size group should
    /// all have the same horizontal requisition ([`SizeGroupMode::Horizontal`][crate::SizeGroupMode::Horizontal])
    /// all have the same vertical requisition ([`SizeGroupMode::Vertical`][crate::SizeGroupMode::Vertical]),
    /// or should all have the same requisition in both directions
    /// ([`SizeGroupMode::Both`][crate::SizeGroupMode::Both]).
    /// ## `mode`
    /// the mode to set for the size group.
    #[doc(alias = "gtk_size_group_set_mode")]
    #[doc(alias = "mode")]
    fn set_mode(&self, mode: SizeGroupMode) {
        unsafe {
            ffi::gtk_size_group_set_mode(self.as_ref().to_glib_none().0, mode.into_glib());
        }
    }

    #[doc(alias = "mode")]
    fn connect_mode_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_mode_trampoline<P: IsA<SizeGroup>, F: Fn(&P) + 'static>(
            this: *mut ffi::GtkSizeGroup,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(SizeGroup::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::mode".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_mode_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<SizeGroup>> SizeGroupExt for O {}