gtk4/auto/

text_mark.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, TextBuffer};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// A [`TextMark`][crate::TextMark] is a position in a `GtkTextbuffer` that is preserved
    /// across modifications.
    ///
    /// You may wish to begin by reading the
    /// [text widget conceptual overview](section-text-widget.html),
    /// which gives an overview of all the objects and data types
    /// related to the text widget and how they work together.
    ///
    /// A [`TextMark`][crate::TextMark] is like a bookmark in a text buffer; it preserves
    /// a position in the text. You can convert the mark to an iterator using
    /// [`TextBufferExt::iter_at_mark()`][crate::prelude::TextBufferExt::iter_at_mark()]. Unlike iterators, marks remain
    /// valid across buffer mutations, because their behavior is defined when
    /// text is inserted or deleted. When text containing a mark is deleted,
    /// the mark remains in the position originally occupied by the deleted
    /// text. When text is inserted at a mark, a mark with “left gravity” will
    /// be moved to the beginning of the newly-inserted text, and a mark with
    /// “right gravity” will be moved to the end.
    ///
    /// Note that “left” and “right” here refer to logical direction (left
    /// is the toward the start of the buffer); in some languages such as
    /// Hebrew the logically-leftmost text is not actually on the left when
    /// displayed.
    ///
    /// Marks are reference counted, but the reference count only controls
    /// the validity of the memory; marks can be deleted from the buffer at
    /// any time with [`TextBufferExt::delete_mark()`][crate::prelude::TextBufferExt::delete_mark()]. Once deleted from
    /// the buffer, a mark is essentially useless.
    ///
    /// Marks optionally have names; these can be convenient to avoid passing
    /// the [`TextMark`][crate::TextMark] object around.
    ///
    /// Marks are typically created using the [`TextBufferExt::create_mark()`][crate::prelude::TextBufferExt::create_mark()]
    /// function.
    ///
    /// ## Properties
    ///
    ///
    /// #### `left-gravity`
    ///  Whether the mark has left gravity.
    ///
    /// When text is inserted at the mark’s current location, if the mark
    /// has left gravity it will be moved to the left of the newly-inserted
    /// text, otherwise to the right.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `name`
    ///  The name of the mark or [`None`] if the mark is anonymous.
    ///
    /// Readable | Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`TextMarkExt`][trait@crate::prelude::TextMarkExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GtkTextMark")]
    pub struct TextMark(Object<ffi::GtkTextMark, ffi::GtkTextMarkClass>);

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

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

    /// Creates a text mark.
    ///
    /// Add it to a buffer using [`TextBufferExt::add_mark()`][crate::prelude::TextBufferExt::add_mark()].
    /// If @name is [`None`], the mark is anonymous; otherwise, the mark can be
    /// retrieved by name using [`TextBufferExt::mark()`][crate::prelude::TextBufferExt::mark()]. If a mark
    /// has left gravity, and text is inserted at the mark’s current location,
    /// the mark will be moved to the left of the newly-inserted text. If the
    /// mark has right gravity (@left_gravity = [`false`]), the mark will end up
    /// on the right of newly-inserted text. The standard left-to-right cursor
    /// is a mark with right gravity (when you type, the cursor stays on the
    /// right side of the text you’re typing).
    /// ## `name`
    /// mark name
    /// ## `left_gravity`
    /// whether the mark should have left gravity
    ///
    /// # Returns
    ///
    /// new [`TextMark`][crate::TextMark]
    #[doc(alias = "gtk_text_mark_new")]
    pub fn new(name: Option<&str>, left_gravity: bool) -> TextMark {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gtk_text_mark_new(
                name.to_glib_none().0,
                left_gravity.into_glib(),
            ))
        }
    }

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

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

// rustdoc-stripper-ignore-next
/// A [builder-pattern] type to construct [`TextMark`] 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 TextMarkBuilder {
    builder: glib::object::ObjectBuilder<'static, TextMark>,
}

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

    /// Whether the mark has left gravity.
    ///
    /// When text is inserted at the mark’s current location, if the mark
    /// has left gravity it will be moved to the left of the newly-inserted
    /// text, otherwise to the right.
    pub fn left_gravity(self, left_gravity: bool) -> Self {
        Self {
            builder: self.builder.property("left-gravity", left_gravity),
        }
    }

    /// The name of the mark or [`None`] if the mark is anonymous.
    pub fn name(self, name: impl Into<glib::GString>) -> Self {
        Self {
            builder: self.builder.property("name", name.into()),
        }
    }

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

/// Trait containing all [`struct@TextMark`] methods.
///
/// # Implementors
///
/// [`TextMark`][struct@crate::TextMark]
pub trait TextMarkExt: IsA<TextMark> + 'static {
    /// Gets the buffer this mark is located inside.
    ///
    /// Returns [`None`] if the mark is deleted.
    ///
    /// # Returns
    ///
    /// the mark’s [`TextBuffer`][crate::TextBuffer]
    #[doc(alias = "gtk_text_mark_get_buffer")]
    #[doc(alias = "get_buffer")]
    fn buffer(&self) -> Option<TextBuffer> {
        unsafe {
            from_glib_none(ffi::gtk_text_mark_get_buffer(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Returns [`true`] if the mark has been removed from its buffer.
    ///
    /// See [`TextBufferExt::add_mark()`][crate::prelude::TextBufferExt::add_mark()] for a way to add it
    /// to a buffer again.
    ///
    /// # Returns
    ///
    /// whether the mark is deleted
    #[doc(alias = "gtk_text_mark_get_deleted")]
    #[doc(alias = "get_deleted")]
    fn is_deleted(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_text_mark_get_deleted(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Determines whether the mark has left gravity.
    ///
    /// # Returns
    ///
    /// [`true`] if the mark has left gravity, [`false`] otherwise
    #[doc(alias = "gtk_text_mark_get_left_gravity")]
    #[doc(alias = "get_left_gravity")]
    #[doc(alias = "left-gravity")]
    fn is_left_gravity(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_text_mark_get_left_gravity(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Returns the mark name.
    ///
    /// Returns [`None`] for anonymous marks.
    ///
    /// # Returns
    ///
    /// mark name
    #[doc(alias = "gtk_text_mark_get_name")]
    #[doc(alias = "get_name")]
    fn name(&self) -> Option<glib::GString> {
        unsafe { from_glib_none(ffi::gtk_text_mark_get_name(self.as_ref().to_glib_none().0)) }
    }

    /// Returns [`true`] if the mark is visible.
    ///
    /// A cursor is displayed for visible marks.
    ///
    /// # Returns
    ///
    /// [`true`] if visible
    #[doc(alias = "gtk_text_mark_get_visible")]
    #[doc(alias = "get_visible")]
    fn is_visible(&self) -> bool {
        unsafe {
            from_glib(ffi::gtk_text_mark_get_visible(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Sets the visibility of @self.
    ///
    /// The insertion point is normally visible, i.e. you can see it as
    /// a vertical bar. Also, the text widget uses a visible mark to
    /// indicate where a drop will occur when dragging-and-dropping text.
    /// Most other marks are not visible.
    ///
    /// Marks are not visible by default.
    /// ## `setting`
    /// visibility of mark
    #[doc(alias = "gtk_text_mark_set_visible")]
    fn set_visible(&self, setting: bool) {
        unsafe {
            ffi::gtk_text_mark_set_visible(self.as_ref().to_glib_none().0, setting.into_glib());
        }
    }
}

impl<O: IsA<TextMark>> TextMarkExt for O {}