gtk4/auto/

string_list.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};
use glib::translate::*;

glib::wrapper! {
    /// [`StringList`][crate::StringList] is a list model that wraps an array of strings.
    ///
    /// The objects in the model are of type [`StringObject`][crate::StringObject] and have
    /// a "string" property that can be used inside expressions.
    ///
    /// [`StringList`][crate::StringList] is well-suited for any place where you would
    /// typically use a `char*[]`, but need a list model.
    ///
    /// ## GtkStringList as GtkBuildable
    ///
    /// The [`StringList`][crate::StringList] implementation of the [`Buildable`][crate::Buildable] interface
    /// supports adding items directly using the `<items>` element and
    /// specifying `<item>` elements for each item. Each `<item>` element
    /// supports the regular translation attributes “translatable”,
    /// “context” and “comments”.
    ///
    /// Here is a UI definition fragment specifying a [`StringList`][crate::StringList]
    ///
    /// ```xml
    /// <object class="GtkStringList">
    ///   <items>
    ///     <item translatable="yes">Factory</item>
    ///     <item translatable="yes">Home</item>
    ///     <item translatable="yes">Subway</item>
    ///   </items>
    /// </object>
    /// ```
    ///
    /// ## Properties
    ///
    ///
    /// #### `item-type`
    ///  The type of items. See [`ListModelExtManual::item_type()`][crate::gio::prelude::ListModelExtManual::item_type()].
    ///
    /// Readable
    ///
    ///
    /// #### `n-items`
    ///  The number of items. See [`ListModelExtManual::n_items()`][crate::gio::prelude::ListModelExtManual::n_items()].
    ///
    /// Readable
    ///
    ///
    /// #### `strings`
    ///  The strings in the model.
    ///
    /// Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`], [`trait@gio::prelude::ListModelExt`], [`BuildableExt`][trait@crate::prelude::BuildableExt]
    #[doc(alias = "GtkStringList")]
    pub struct StringList(Object<ffi::GtkStringList, ffi::GtkStringListClass>) @implements gio::ListModel, Buildable;

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

impl StringList {
    /// Creates a new [`StringList`][crate::StringList] with the given @strings.
    /// ## `strings`
    /// The strings to put in the model
    ///
    /// # Returns
    ///
    /// a new [`StringList`][crate::StringList]
    #[doc(alias = "gtk_string_list_new")]
    pub fn new(strings: &[&str]) -> StringList {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gtk_string_list_new(strings.to_glib_none().0)) }
    }

    /// Appends @string to @self.
    ///
    /// The @string will be copied. See
    /// `Gtk::StringList::take()` for a way to avoid that.
    /// ## `string`
    /// the string to insert
    #[doc(alias = "gtk_string_list_append")]
    pub fn append(&self, string: &str) {
        unsafe {
            ffi::gtk_string_list_append(self.to_glib_none().0, string.to_glib_none().0);
        }
    }

    /// Gets the position of the @string in @self.
    ///
    /// If @self does not contain @string item, `G_MAXUINT` is returned.
    /// ## `string`
    /// the string to find
    ///
    /// # Returns
    ///
    /// the position of the string
    #[cfg(feature = "v4_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_18")))]
    #[doc(alias = "gtk_string_list_find")]
    pub fn find(&self, string: &str) -> u32 {
        unsafe { ffi::gtk_string_list_find(self.to_glib_none().0, string.to_glib_none().0) }
    }

    /// Gets the string that is at @position in @self.
    ///
    /// If @self does not contain @position items, [`None`] is returned.
    ///
    /// This function returns the const char *. To get the
    /// object wrapping it, use g_list_model_get_item().
    /// ## `position`
    /// the position to get the string for
    ///
    /// # Returns
    ///
    /// the string at the given position
    #[doc(alias = "gtk_string_list_get_string")]
    #[doc(alias = "get_string")]
    pub fn string(&self, position: u32) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::gtk_string_list_get_string(
                self.to_glib_none().0,
                position,
            ))
        }
    }

    /// Removes the string at @position from @self.
    ///
    /// @position must be smaller than the current
    /// length of the list.
    /// ## `position`
    /// the position of the string that is to be removed
    #[doc(alias = "gtk_string_list_remove")]
    pub fn remove(&self, position: u32) {
        unsafe {
            ffi::gtk_string_list_remove(self.to_glib_none().0, position);
        }
    }

    /// Changes @self by removing @n_removals strings and adding @additions
    /// to it.
    ///
    /// This function is more efficient than [`append()`][Self::append()]
    /// and [`remove()`][Self::remove()], because it only emits the
    /// ::items-changed signal once for the change.
    ///
    /// This function copies the strings in @additions.
    ///
    /// The parameters @position and @n_removals must be correct (ie:
    /// @position + @n_removals must be less than or equal to the length
    /// of the list at the time this function is called).
    /// ## `position`
    /// the position at which to make the change
    /// ## `n_removals`
    /// the number of strings to remove
    /// ## `additions`
    /// The strings to add
    #[doc(alias = "gtk_string_list_splice")]
    pub fn splice(&self, position: u32, n_removals: u32, additions: &[&str]) {
        unsafe {
            ffi::gtk_string_list_splice(
                self.to_glib_none().0,
                position,
                n_removals,
                additions.to_glib_none().0,
            );
        }
    }
}