gtk4/auto/

constraint_layout.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::{ffi, Buildable, Constraint, ConstraintGuide, LayoutManager};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// Uses constraints to describe relations between widgets.
    ///
    /// [`ConstraintLayout`][crate::ConstraintLayout] is a layout manager that uses relations between
    /// widget attributes, expressed via [`Constraint`][crate::Constraint] instances, to
    /// measure and allocate widgets.
    ///
    /// ### How do constraints work
    ///
    /// Constraints are objects defining the relationship between attributes
    /// of a widget; you can read the description of the [`Constraint`][crate::Constraint]
    /// class to have a more in depth definition.
    ///
    /// By taking multiple constraints and applying them to the children of
    /// a widget using [`ConstraintLayout`][crate::ConstraintLayout], it's possible to describe
    /// complex layout policies; each constraint applied to a child or to the parent
    /// widgets contributes to the full description of the layout, in terms of
    /// parameters for resolving the value of each attribute.
    ///
    /// It is important to note that a layout is defined by the totality of
    /// constraints; removing a child, or a constraint, from an existing layout
    /// without changing the remaining constraints may result in an unstable
    /// or unsolvable layout.
    ///
    /// Constraints have an implicit "reading order"; you should start describing
    /// each edge of each child, as well as their relationship with the parent
    /// container, from the top left (or top right, in RTL languages), horizontally
    /// first, and then vertically.
    ///
    /// A constraint-based layout with too few constraints can become "unstable",
    /// that is: have more than one solution. The behavior of an unstable layout
    /// is undefined.
    ///
    /// A constraint-based layout with conflicting constraints may be unsolvable,
    /// and lead to an unstable layout. You can use the [`strength`][struct@crate::Constraint#strength]
    /// property of [`Constraint`][crate::Constraint] to "nudge" the layout towards a solution.
    ///
    /// ### GtkConstraintLayout as GtkBuildable
    ///
    /// [`ConstraintLayout`][crate::ConstraintLayout] implements the [`Buildable`][crate::Buildable] interface and
    /// has a custom "constraints" element which allows describing constraints in
    /// a [`Builder`][crate::Builder] UI file.
    ///
    /// An example of a UI definition fragment specifying a constraint:
    ///
    /// ```xml
    ///   <object class="GtkConstraintLayout">
    ///     <constraints>
    ///       <constraint target="button" target-attribute="start"
    ///                   relation="eq"
    ///                   source="super" source-attribute="start"
    ///                   constant="12"
    ///                   strength="required" />
    ///       <constraint target="button" target-attribute="width"
    ///                   relation="ge"
    ///                   constant="250"
    ///                   strength="strong" />
    ///     </constraints>
    ///   </object>
    /// ```
    ///
    /// The definition above will add two constraints to the GtkConstraintLayout:
    ///
    ///  - a required constraint between the leading edge of "button" and
    ///    the leading edge of the widget using the constraint layout, plus
    ///    12 pixels
    ///  - a strong, constant constraint making the width of "button" greater
    ///    than, or equal to 250 pixels
    ///
    /// The "target" and "target-attribute" attributes are required.
    ///
    /// The "source" and "source-attribute" attributes of the "constraint"
    /// element are optional; if they are not specified, the constraint is
    /// assumed to be a constant.
    ///
    /// The "relation" attribute is optional; if not specified, the constraint
    /// is assumed to be an equality.
    ///
    /// The "strength" attribute is optional; if not specified, the constraint
    /// is assumed to be required.
    ///
    /// The "source" and "target" attributes can be set to "super" to indicate
    /// that the constraint target is the widget using the GtkConstraintLayout.
    ///
    /// There can be "constant" and "multiplier" attributes.
    ///
    /// Additionally, the "constraints" element can also contain a description
    /// of the `GtkConstraintGuides` used by the layout:
    ///
    /// ```xml
    ///   <constraints>
    ///     <guide min-width="100" max-width="500" name="hspace"/>
    ///     <guide min-height="64" nat-height="128" name="vspace" strength="strong"/>
    ///   </constraints>
    /// ```
    ///
    /// The "guide" element has the following optional attributes:
    ///
    ///   - "min-width", "nat-width", and "max-width", describe the minimum,
    ///     natural, and maximum width of the guide, respectively
    ///   - "min-height", "nat-height", and "max-height", describe the minimum,
    ///     natural, and maximum height of the guide, respectively
    ///   - "strength" describes the strength of the constraint on the natural
    ///     size of the guide; if not specified, the constraint is assumed to
    ///     have a medium strength
    ///   - "name" describes a name for the guide, useful when debugging
    ///
    /// ### Using the Visual Format Language
    ///
    /// Complex constraints can be described using a compact syntax called VFL,
    /// or *Visual Format Language*.
    ///
    /// The Visual Format Language describes all the constraints on a row or
    /// column, typically starting from the leading edge towards the trailing
    /// one. Each element of the layout is composed by "views", which identify
    /// a [`ConstraintTarget`][crate::ConstraintTarget].
    ///
    /// For instance:
    ///
    /// ```text
    ///   [button]-[textField]
    /// ```
    ///
    /// Describes a constraint that binds the trailing edge of "button" to the
    /// leading edge of "textField", leaving a default space between the two.
    ///
    /// Using VFL is also possible to specify predicates that describe constraints
    /// on attributes like width and height:
    ///
    /// ```text
    ///   // Width must be greater than, or equal to 50
    ///   [button(>=50)]
    ///
    ///   // Width of button1 must be equal to width of button2
    ///   [button1(==button2)]
    /// ```
    ///
    /// The default orientation for a VFL description is horizontal, unless
    /// otherwise specified:
    ///
    /// ```text
    ///   // horizontal orientation, default attribute: width
    ///   H:[button(>=150)]
    ///
    ///   // vertical orientation, default attribute: height
    ///   V:[button1(==button2)]
    /// ```
    ///
    /// It's also possible to specify multiple predicates, as well as their
    /// strength:
    ///
    /// ```text
    ///   // minimum width of button must be 150
    ///   // natural width of button can be 250
    ///   [button(>=150@required, ==250@medium)]
    /// ```
    ///
    /// Finally, it's also possible to use simple arithmetic operators:
    ///
    /// ```text
    ///   // width of button1 must be equal to width of button2
    ///   // divided by 2 plus 12
    ///   [button1(button2 / 2 + 12)]
    /// ```
    ///
    /// # Implements
    ///
    /// [`LayoutManagerExt`][trait@crate::prelude::LayoutManagerExt], [`trait@glib::ObjectExt`], [`BuildableExt`][trait@crate::prelude::BuildableExt]
    #[doc(alias = "GtkConstraintLayout")]
    pub struct ConstraintLayout(Object<ffi::GtkConstraintLayout, ffi::GtkConstraintLayoutClass>) @extends LayoutManager, @implements Buildable;

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

impl ConstraintLayout {
    /// Creates a new [`ConstraintLayout`][crate::ConstraintLayout] layout manager.
    ///
    /// # Returns
    ///
    /// the newly created [`ConstraintLayout`][crate::ConstraintLayout]
    #[doc(alias = "gtk_constraint_layout_new")]
    pub fn new() -> ConstraintLayout {
        assert_initialized_main_thread!();
        unsafe { LayoutManager::from_glib_full(ffi::gtk_constraint_layout_new()).unsafe_cast() }
    }

    /// Adds a constraint to the layout manager.
    ///
    /// The [`source`][struct@crate::Constraint#source] and [`target`][struct@crate::Constraint#target]
    /// properties of `constraint` can be:
    ///
    ///  - set to `NULL` to indicate that the constraint refers to the
    ///    widget using `layout`
    ///  - set to the [`Widget`][crate::Widget] using `layout`
    ///  - set to a child of the [`Widget`][crate::Widget] using `layout`
    ///  - set to a [`ConstraintGuide`][crate::ConstraintGuide] that is part of `layout`
    ///
    /// The @self acquires the ownership of @constraint after calling
    /// this function.
    /// ## `constraint`
    /// a [`Constraint`][crate::Constraint]
    #[doc(alias = "gtk_constraint_layout_add_constraint")]
    pub fn add_constraint(&self, constraint: Constraint) {
        unsafe {
            ffi::gtk_constraint_layout_add_constraint(
                self.to_glib_none().0,
                constraint.into_glib_ptr(),
            );
        }
    }

    /// Adds a guide to `layout`.
    ///
    /// A guide can be used as the source or target of constraints,
    /// like a widget, but it is not visible.
    ///
    /// The `layout` acquires the ownership of `guide` after calling
    /// this function.
    /// ## `guide`
    /// a [`ConstraintGuide`][crate::ConstraintGuide] object
    #[doc(alias = "gtk_constraint_layout_add_guide")]
    pub fn add_guide(&self, guide: ConstraintGuide) {
        unsafe {
            ffi::gtk_constraint_layout_add_guide(self.to_glib_none().0, guide.into_glib_ptr());
        }
    }

    /// Returns a `GListModel` to track the constraints that are
    /// part of the layout.
    ///
    /// Calling this function will enable extra internal bookkeeping
    /// to track constraints and emit signals on the returned listmodel.
    /// It may slow down operations a lot.
    ///
    /// Applications should try hard to avoid calling this function
    /// because of the slowdowns.
    ///
    /// # Returns
    ///
    /// a
    ///   `GListModel` tracking the layout's constraints
    #[doc(alias = "gtk_constraint_layout_observe_constraints")]
    pub fn observe_constraints(&self) -> gio::ListModel {
        unsafe {
            from_glib_full(ffi::gtk_constraint_layout_observe_constraints(
                self.to_glib_none().0,
            ))
        }
    }

    /// Returns a `GListModel` to track the guides that are
    /// part of the layout.
    ///
    /// Calling this function will enable extra internal bookkeeping
    /// to track guides and emit signals on the returned listmodel.
    /// It may slow down operations a lot.
    ///
    /// Applications should try hard to avoid calling this function
    /// because of the slowdowns.
    ///
    /// # Returns
    ///
    /// a
    ///   `GListModel` tracking the layout's guides
    #[doc(alias = "gtk_constraint_layout_observe_guides")]
    pub fn observe_guides(&self) -> gio::ListModel {
        unsafe {
            from_glib_full(ffi::gtk_constraint_layout_observe_guides(
                self.to_glib_none().0,
            ))
        }
    }

    /// Removes all constraints from the layout manager.
    #[doc(alias = "gtk_constraint_layout_remove_all_constraints")]
    pub fn remove_all_constraints(&self) {
        unsafe {
            ffi::gtk_constraint_layout_remove_all_constraints(self.to_glib_none().0);
        }
    }

    /// Removes `constraint` from the layout manager,
    /// so that it no longer influences the layout.
    /// ## `constraint`
    /// a [`Constraint`][crate::Constraint]
    #[doc(alias = "gtk_constraint_layout_remove_constraint")]
    pub fn remove_constraint(&self, constraint: &Constraint) {
        unsafe {
            ffi::gtk_constraint_layout_remove_constraint(
                self.to_glib_none().0,
                constraint.to_glib_none().0,
            );
        }
    }

    /// Removes `guide` from the layout manager,
    /// so that it no longer influences the layout.
    /// ## `guide`
    /// a [`ConstraintGuide`][crate::ConstraintGuide] object
    #[doc(alias = "gtk_constraint_layout_remove_guide")]
    pub fn remove_guide(&self, guide: &ConstraintGuide) {
        unsafe {
            ffi::gtk_constraint_layout_remove_guide(self.to_glib_none().0, guide.to_glib_none().0);
        }
    }
}

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