gstreamer_editing_services/auto/

container.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// from gst-gir-files (https://gitlab.freedesktop.org/gstreamer/gir-files-rs.git)
// DO NOT EDIT
#![allow(deprecated)]

use crate::{ffi, Edge, EditMode, Extractable, Layer, MetaContainer, TimelineElement};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// A [`Container`][crate::Container] is a timeline element that controls other
    /// [`TimelineElement`][crate::TimelineElement]-s, which are its children. In particular, it is
    /// responsible for maintaining the relative [`start`][struct@crate::TimelineElement#start] and
    /// [`duration`][struct@crate::TimelineElement#duration] times of its children. Therefore, if a
    /// container is temporally adjusted or moved to a new layer, it may
    /// accordingly adjust and move its children. Similarly, a change in one of
    /// its children may prompt the parent to correspondingly change its
    /// siblings.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `height`
    ///  The span of the container's children's [`priority`][struct@crate::TimelineElement#priority]
    /// values, which is the number of integers that lie between (inclusive)
    /// the minimum and maximum priorities found amongst the container's
    /// children (maximum - minimum + 1).
    ///
    /// Readable
    /// <details><summary><h4>TimelineElement</h4></summary>
    ///
    ///
    /// #### `duration`
    ///  The duration that the element is in effect for in the timeline (a
    /// time difference in nanoseconds using the time coordinates of the
    /// timeline). For example, for a source element, this would determine
    /// for how long it should output its internal content for. For an
    /// operation element, this would determine for how long its effect
    /// should be applied to any source content.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `in-point`
    ///  The initial offset to use internally when outputting content (in
    /// nanoseconds, but in the time coordinates of the internal content).
    ///
    /// For example, for a [`VideoUriSource`][crate::VideoUriSource] that references some media
    /// file, the "internal content" is the media file data, and the
    /// in-point would correspond to some timestamp in the media file.
    /// When playing the timeline, and when the element is first reached at
    /// timeline-time [`start`][struct@crate::TimelineElement#start], it will begin outputting the
    /// data from the timestamp in-point **onwards**, until it reaches the
    /// end of its [`duration`][struct@crate::TimelineElement#duration] in the timeline.
    ///
    /// For elements that have no internal content, this should be kept
    /// as 0.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `max-duration`
    ///  The full duration of internal content that is available (a time
    /// difference in nanoseconds using the time coordinates of the internal
    /// content).
    ///
    /// This will act as a cap on the [`in-point`][struct@crate::TimelineElement#in-point] of the
    /// element (which is in the same time coordinates), and will sometimes
    /// be used to limit the [`duration`][struct@crate::TimelineElement#duration] of the element in
    /// the timeline.
    ///
    /// For example, for a [`VideoUriSource`][crate::VideoUriSource] that references some media
    /// file, this would be the length of the media file.
    ///
    /// For elements that have no internal content, or whose content is
    /// indefinite, this should be kept as `GST_CLOCK_TIME_NONE`.
    ///
    /// Readable | Writeable | Construct
    ///
    ///
    /// #### `name`
    ///  The name of the element. This should be unique within its timeline.
    ///
    /// Readable | Writeable | Construct
    ///
    ///
    /// #### `parent`
    ///  The parent container of the element.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `priority`
    ///  The priority of the element.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `serialize`
    ///  Whether the element should be serialized.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `start`
    ///  The starting position of the element in the timeline (in nanoseconds
    /// and in the time coordinates of the timeline). For example, for a
    /// source element, this would determine the time at which it should
    /// start outputting its internal content. For an operation element, this
    /// would determine the time at which it should start applying its effect
    /// to any source content.
    ///
    /// Readable | Writeable
    ///
    ///
    /// #### `timeline`
    ///  The timeline that the element lies within.
    ///
    /// Readable | Writeable
    /// </details>
    ///
    /// ## Signals
    ///
    ///
    /// #### `child-added`
    ///  Will be emitted after a child is added to the container. Usually,
    /// you should connect with `g_signal_connect_after()` since the signal
    /// may be stopped internally.
    ///
    ///
    ///
    ///
    /// #### `child-removed`
    ///  Will be emitted after a child is removed from the container.
    ///
    ///
    /// <details><summary><h4>TimelineElement</h4></summary>
    ///
    ///
    /// #### `child-property-added`
    ///  Emitted when the element has a new child property registered. See
    /// [`TimelineElementExt::add_child_property()`][crate::prelude::TimelineElementExt::add_child_property()].
    ///
    /// Note that some GES elements will be automatically created with
    /// pre-registered children properties. You can use
    /// [`TimelineElementExt::list_children_properties()`][crate::prelude::TimelineElementExt::list_children_properties()] to list these.
    ///
    ///
    ///
    ///
    /// #### `child-property-removed`
    ///  Emitted when the element has a child property unregistered. See
    /// [`TimelineElementExt::remove_child_property()`][crate::prelude::TimelineElementExt::remove_child_property()].
    ///
    ///
    ///
    ///
    /// #### `deep-notify`
    ///  Emitted when a child of the element has one of its registered
    /// properties set. See [`TimelineElementExt::add_child_property()`][crate::prelude::TimelineElementExt::add_child_property()].
    /// Note that unlike [`notify`][struct@crate::glib::Object#notify], a child property name can not be
    /// used as a signal detail.
    ///
    /// Detailed
    /// </details>
    /// <details><summary><h4>MetaContainer</h4></summary>
    ///
    ///
    /// #### `notify-meta`
    ///  This is emitted for a meta container whenever the metadata under one
    /// of its fields changes, is set for the first time, or is removed. In
    /// the latter case, `value` will be [`None`].
    ///
    /// Detailed
    /// </details>
    ///
    /// # Implements
    ///
    /// [`GESContainerExt`][trait@crate::prelude::GESContainerExt], [`TimelineElementExt`][trait@crate::prelude::TimelineElementExt], [`trait@glib::ObjectExt`], [`ExtractableExt`][trait@crate::prelude::ExtractableExt], [`MetaContainerExt`][trait@crate::prelude::MetaContainerExt], [`TimelineElementExtManual`][trait@crate::prelude::TimelineElementExtManual]
    #[doc(alias = "GESContainer")]
    pub struct Container(Object<ffi::GESContainer, ffi::GESContainerClass>) @extends TimelineElement, @implements Extractable, MetaContainer;

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

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

    /// Groups the containers into a single container by merging them. The
    /// containers must all belong to the same [`timeline`][struct@crate::TimelineElement#timeline].
    ///
    /// If the elements are all [`Clip`][crate::Clip]-s then this method will attempt to
    /// combine them all into a single [`Clip`][crate::Clip]. This should succeed if they:
    /// share the same [`start`][struct@crate::TimelineElement#start], [`duration`][struct@crate::TimelineElement#duration]
    /// and [`in-point`][struct@crate::TimelineElement#in-point]; exist in the same layer; and all of
    /// the sources share the same [`Asset`][crate::Asset]. If this fails, or one of the
    /// elements is not a [`Clip`][crate::Clip], this method will try to create a [`Group`][crate::Group]
    /// instead.
    /// ## `containers`
    ///
    /// The [`Container`][crate::Container]-s to group
    ///
    /// # Returns
    ///
    /// The container created by merging
    /// `containers`, or [`None`] if they could not be merged into a single
    /// container.
    #[doc(alias = "ges_container_group")]
    pub fn group(containers: &[Container]) -> Option<Container> {
        assert_initialized_main_thread!();
        unsafe { from_glib_none(ffi::ges_container_group(containers.to_glib_none().0)) }
    }
}

/// Trait containing all [`struct@Container`] methods.
///
/// # Implementors
///
/// [`Clip`][struct@crate::Clip], [`Container`][struct@crate::Container], [`Group`][struct@crate::Group]
pub trait GESContainerExt: IsA<Container> + 'static {
    /// Adds a timeline element to the container. The element will now be a
    /// child of the container (and the container will be the
    /// [`parent`][struct@crate::TimelineElement#parent] of the added element), which means that it
    /// is now controlled by the container. This may change the properties of
    /// the child or the container, depending on the subclass.
    ///
    /// Additionally, the children properties of the newly added element will
    /// be shared with the container, meaning they can also be read and set
    /// using [`TimelineElementExt::child_property()`][crate::prelude::TimelineElementExt::child_property()] and
    /// [`TimelineElementExt::set_child_property()`][crate::prelude::TimelineElementExt::set_child_property()] on the container.
    /// ## `child`
    /// The element to add as a child
    ///
    /// # Returns
    ///
    /// [`true`] if `child` was successfully added to `self`.
    #[doc(alias = "ges_container_add")]
    fn add(&self, child: &impl IsA<TimelineElement>) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::ges_container_add(
                    self.as_ref().to_glib_none().0,
                    child.as_ref().to_glib_none().0
                ),
                "Failed to add element"
            )
        }
    }

    /// Edits the container within its timeline.
    ///
    /// # Deprecated since 1.18
    ///
    /// use `ges_timeline_element_edit` instead.
    /// ## `layers`
    /// A whitelist of layers
    /// where the edit can be performed, [`None`] allows all layers in the
    /// timeline
    /// ## `new_layer_priority`
    /// The priority/index of the layer `self` should
    /// be moved to. -1 means no move
    /// ## `mode`
    /// The edit mode
    /// ## `edge`
    /// The edge of `self` where the edit should occur
    /// ## `position`
    /// The edit position: a new location for the edge of `self`
    /// (in nanoseconds)
    ///
    /// # Returns
    ///
    /// [`true`] if the edit of `self` completed, [`false`] on failure.
    #[cfg_attr(feature = "v1_18", deprecated = "Since 1.18")]
    #[allow(deprecated)]
    #[doc(alias = "ges_container_edit")]
    fn edit(
        &self,
        layers: &[Layer],
        new_layer_priority: i32,
        mode: EditMode,
        edge: Edge,
        position: u64,
    ) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::ges_container_edit(
                    self.as_ref().to_glib_none().0,
                    layers.to_glib_none().0,
                    new_layer_priority,
                    mode.into_glib(),
                    edge.into_glib(),
                    position
                ),
                "Failed to edit container"
            )
        }
    }

    /// Get the list of timeline elements contained in the container. If
    /// `recursive` is [`true`], and the container contains other containers as
    /// children, then their children will be added to the list, in addition to
    /// themselves, and so on.
    /// ## `recursive`
    /// Whether to recursively get children in `self`
    ///
    /// # Returns
    ///
    /// The list of
    /// [`TimelineElement`][crate::TimelineElement]-s contained in `self`.
    #[doc(alias = "ges_container_get_children")]
    #[doc(alias = "get_children")]
    fn children(&self, recursive: bool) -> Vec<TimelineElement> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::ges_container_get_children(
                self.as_ref().to_glib_none().0,
                recursive.into_glib(),
            ))
        }
    }

    /// Removes a timeline element from the container. The element will no
    /// longer be controlled by the container.
    /// ## `child`
    /// The child to remove
    ///
    /// # Returns
    ///
    /// [`true`] if `child` was successfully removed from `self`.
    #[doc(alias = "ges_container_remove")]
    fn remove(&self, child: &impl IsA<TimelineElement>) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::ges_container_remove(
                    self.as_ref().to_glib_none().0,
                    child.as_ref().to_glib_none().0
                ),
                "Failed to remove element"
            )
        }
    }

    /// Ungroups the container by splitting it into several containers
    /// containing various children of the original. The rules for how the
    /// container splits depends on the subclass. A [`Group`][crate::Group] will simply split
    /// into its children. A [`Clip`][crate::Clip] will split into one [`Clip`][crate::Clip] per
    /// [`TrackType`][crate::TrackType] it overlaps with (so an audio-video clip will split into
    /// an audio clip and a video clip), where each clip contains all the
    /// [`TrackElement`][crate::TrackElement]-s from the original clip with a matching
    /// [`track-type`][struct@crate::TrackElement#track-type].
    ///
    /// If `recursive` is [`true`], and the container contains other containers as
    /// children, then they will also be ungrouped, and so on.
    /// ## `recursive`
    /// Whether to recursively ungroup `self`
    ///
    /// # Returns
    ///
    /// The list of
    /// new [`Container`][crate::Container]-s created from the splitting of `self`.
    #[doc(alias = "ges_container_ungroup")]
    fn ungroup(self, recursive: bool) -> Vec<Container> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::ges_container_ungroup(
                self.upcast().into_glib_ptr(),
                recursive.into_glib(),
            ))
        }
    }

    /// The span of the container's children's [`priority`][struct@crate::TimelineElement#priority]
    /// values, which is the number of integers that lie between (inclusive)
    /// the minimum and maximum priorities found amongst the container's
    /// children (maximum - minimum + 1).
    fn height(&self) -> u32 {
        ObjectExt::property(self.as_ref(), "height")
    }

    /// Will be emitted after a child is added to the container. Usually,
    /// you should connect with `g_signal_connect_after()` since the signal
    /// may be stopped internally.
    /// ## `element`
    /// The child that was added
    #[doc(alias = "child-added")]
    fn connect_child_added<F: Fn(&Self, &TimelineElement) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn child_added_trampoline<
            P: IsA<Container>,
            F: Fn(&P, &TimelineElement) + 'static,
        >(
            this: *mut ffi::GESContainer,
            element: *mut ffi::GESTimelineElement,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                Container::from_glib_borrow(this).unsafe_cast_ref(),
                &from_glib_borrow(element),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"child-added".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    child_added_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Will be emitted after a child is removed from the container.
    /// ## `element`
    /// The child that was removed
    #[doc(alias = "child-removed")]
    fn connect_child_removed<F: Fn(&Self, &TimelineElement) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn child_removed_trampoline<
            P: IsA<Container>,
            F: Fn(&P, &TimelineElement) + 'static,
        >(
            this: *mut ffi::GESContainer,
            element: *mut ffi::GESTimelineElement,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(
                Container::from_glib_borrow(this).unsafe_cast_ref(),
                &from_glib_borrow(element),
            )
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"child-removed".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    child_removed_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

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

impl<O: IsA<Container>> GESContainerExt for O {}