gtk/auto/

list_store.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, TreeDragDest, TreeDragSource, TreeIter, TreeModel, TreeSortable};
use glib::{prelude::*, translate::*};
use std::fmt;

glib::wrapper! {
    /// The [`ListStore`][crate::ListStore] object is a list model for use with a [`TreeView`][crate::TreeView]
    /// widget. It implements the [`TreeModel`][crate::TreeModel] interface, and consequentialy,
    /// can use all of the methods available there. It also implements the
    /// [`TreeSortable`][crate::TreeSortable] interface so it can be sorted by the view.
    /// Finally, it also implements the tree
    /// [drag and drop][gtk3-GtkTreeView-drag-and-drop]
    /// interfaces.
    ///
    /// The [`ListStore`][crate::ListStore] can accept most GObject types as a column type, though
    /// it can’t accept all custom types. Internally, it will keep a copy of
    /// data passed in (such as a string or a boxed pointer). Columns that
    /// accept `GObjects` are handled a little differently. The
    /// [`ListStore`][crate::ListStore] will keep a reference to the object instead of copying the
    /// value. As a result, if the object is modified, it is up to the
    /// application writer to call [`TreeModelExt::row_changed()`][crate::prelude::TreeModelExt::row_changed()] to emit the
    /// [`row_changed`][struct@crate::TreeModel#row_changed] signal. This most commonly affects lists with
    /// `GdkPixbufs` stored.
    ///
    /// An example for creating a simple list store:
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    /// enum {
    ///   COLUMN_STRING,
    ///   COLUMN_INT,
    ///   COLUMN_BOOLEAN,
    ///   N_COLUMNS
    /// };
    ///
    /// {
    ///   GtkListStore *list_store;
    ///   GtkTreePath *path;
    ///   GtkTreeIter iter;
    ///   gint i;
    ///
    ///   list_store = gtk_list_store_new (N_COLUMNS,
    ///                                    G_TYPE_STRING,
    ///                                    G_TYPE_INT,
    ///                                    G_TYPE_BOOLEAN);
    ///
    ///   for (i = 0; i < 10; i++)
    ///     {
    ///       gchar *some_data;
    ///
    ///       some_data = get_some_data (i);
    ///
    ///       // Add a new row to the model
    ///       gtk_list_store_append (list_store, &iter);
    ///       gtk_list_store_set (list_store, &iter,
    ///                           COLUMN_STRING, some_data,
    ///                           COLUMN_INT, i,
    ///                           COLUMN_BOOLEAN,  FALSE,
    ///                           -1);
    ///
    ///       // As the store will keep a copy of the string internally,
    ///       // we free some_data.
    ///       g_free (some_data);
    ///     }
    ///
    ///   // Modify a particular row
    ///   path = gtk_tree_path_new_from_string ("4");
    ///   gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
    ///                            &iter,
    ///                            path);
    ///   gtk_tree_path_free (path);
    ///   gtk_list_store_set (list_store, &iter,
    ///                       COLUMN_BOOLEAN, TRUE,
    ///                       -1);
    /// }
    /// ```
    ///
    /// # Performance Considerations
    ///
    /// Internally, the [`ListStore`][crate::ListStore] was implemented with a linked list with
    /// a tail pointer prior to GTK+ 2.6. As a result, it was fast at data
    /// insertion and deletion, and not fast at random data access. The
    /// [`ListStore`][crate::ListStore] sets the [`TreeModelFlags::ITERS_PERSIST`][crate::TreeModelFlags::ITERS_PERSIST] flag, which means
    /// that `GtkTreeIters` can be cached while the row exists. Thus, if
    /// access to a particular row is needed often and your code is expected to
    /// run on older versions of GTK+, it is worth keeping the iter around.
    ///
    /// # Atomic Operations
    ///
    /// It is important to note that only the methods
    /// `gtk_list_store_insert_with_values()` and `gtk_list_store_insert_with_valuesv()`
    /// are atomic, in the sense that the row is being appended to the store and the
    /// values filled in in a single operation with regard to [`TreeModel`][crate::TreeModel] signaling.
    /// In contrast, using e.g. [`GtkListStoreExt::append()`][crate::prelude::GtkListStoreExt::append()] and then [`GtkListStoreExtManual::set()`][crate::prelude::GtkListStoreExtManual::set()]
    /// will first create a row, which triggers the [`row-inserted`][struct@crate::TreeModel#row-inserted] signal
    /// on [`ListStore`][crate::ListStore]. The row, however, is still empty, and any signal handler
    /// connecting to [`row-inserted`][struct@crate::TreeModel#row-inserted] on this particular store should be prepared
    /// for the situation that the row might be empty. This is especially important
    /// if you are wrapping the [`ListStore`][crate::ListStore] inside a [`TreeModelFilter`][crate::TreeModelFilter] and are
    /// using a `GtkTreeModelFilterVisibleFunc`. Using any of the non-atomic operations
    /// to append rows to the [`ListStore`][crate::ListStore] will cause the
    /// `GtkTreeModelFilterVisibleFunc` to be visited with an empty row first; the
    /// function must be prepared for that.
    ///
    /// # GtkListStore as GtkBuildable
    ///
    /// The GtkListStore implementation of the GtkBuildable interface allows
    /// to specify the model columns with a ``<columns>`` element that may contain
    /// multiple ``<column>`` elements, each specifying one model column. The “type”
    /// attribute specifies the data type for the column.
    ///
    /// Additionally, it is possible to specify content for the list store
    /// in the UI definition, with the ``<data>`` element. It can contain multiple
    /// ``<row>`` elements, each specifying to content for one row of the list model.
    /// Inside a ``<row>``, the ``<col>`` elements specify the content for individual cells.
    ///
    /// Note that it is probably more common to define your models in the code,
    /// and one might consider it a layering violation to specify the content of
    /// a list store in a UI definition, data, not presentation, and common wisdom
    /// is to separate the two, as far as possible.
    ///
    /// An example of a UI Definition fragment for a list store:
    ///
    ///
    ///
    /// **⚠️ The following code is in xml ⚠️**
    ///
    /// ```xml
    /// <object class="GtkListStore">
    ///   <columns>
    ///     <column type="gchararray"/>
    ///     <column type="gchararray"/>
    ///     <column type="gint"/>
    ///   </columns>
    ///   <data>
    ///     <row>
    ///       <col id="0">John</col>
    ///       <col id="1">Doe</col>
    ///       <col id="2">25</col>
    ///     </row>
    ///     <row>
    ///       <col id="0">Johan</col>
    ///       <col id="1">Dahlin</col>
    ///       <col id="2">50</col>
    ///     </row>
    ///   </data>
    /// </object>
    /// ```
    ///
    /// # Implements
    ///
    /// [`GtkListStoreExt`][trait@crate::prelude::GtkListStoreExt], [`trait@glib::ObjectExt`], [`BuildableExt`][trait@crate::prelude::BuildableExt], [`TreeDragDestExt`][trait@crate::prelude::TreeDragDestExt], [`TreeDragSourceExt`][trait@crate::prelude::TreeDragSourceExt], [`TreeModelExt`][trait@crate::prelude::TreeModelExt], [`TreeSortableExt`][trait@crate::prelude::TreeSortableExt], [`GtkListStoreExtManual`][trait@crate::prelude::GtkListStoreExtManual], [`BuildableExtManual`][trait@crate::prelude::BuildableExtManual], [`TreeSortableExtManual`][trait@crate::prelude::TreeSortableExtManual]
    #[doc(alias = "GtkListStore")]
    pub struct ListStore(Object<ffi::GtkListStore, ffi::GtkListStoreClass>) @implements Buildable, TreeDragDest, TreeDragSource, TreeModel, TreeSortable;

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

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

    //#[doc(alias = "gtk_list_store_new")]
    //pub fn new(n_columns: i32, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> ListStore {
    //    unsafe { TODO: call ffi:gtk_list_store_new() }
    //}

    //#[doc(alias = "gtk_list_store_newv")]
    //pub fn newv(types: /*Unimplemented*/&CArray TypeId { ns_id: 0, id: 30 }) -> ListStore {
    //    unsafe { TODO: call ffi:gtk_list_store_newv() }
    //}
}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::ListStore>> Sealed for T {}
}

/// Trait containing all [`struct@ListStore`] methods.
///
/// # Implementors
///
/// [`ListStore`][struct@crate::ListStore]
pub trait GtkListStoreExt: IsA<ListStore> + sealed::Sealed + 'static {
    /// Appends a new row to `self`. `iter` will be changed to point to this new
    /// row. The row will be empty after this function is called. To fill in
    /// values, you need to call [`GtkListStoreExtManual::set()`][crate::prelude::GtkListStoreExtManual::set()] or [`GtkListStoreExtManual::set_value()`][crate::prelude::GtkListStoreExtManual::set_value()].
    ///
    /// # Returns
    ///
    ///
    /// ## `iter`
    /// An unset [`TreeIter`][crate::TreeIter] to set to the appended row
    #[doc(alias = "gtk_list_store_append")]
    fn append(&self) -> TreeIter {
        unsafe {
            let mut iter = TreeIter::uninitialized();
            ffi::gtk_list_store_append(self.as_ref().to_glib_none().0, iter.to_glib_none_mut().0);
            iter
        }
    }

    /// Removes all rows from the list store.
    #[doc(alias = "gtk_list_store_clear")]
    fn clear(&self) {
        unsafe {
            ffi::gtk_list_store_clear(self.as_ref().to_glib_none().0);
        }
    }

    /// Creates a new row at `position`. `iter` will be changed to point to this new
    /// row. If `position` is -1 or is larger than the number of rows on the list,
    /// then the new row will be appended to the list. The row will be empty after
    /// this function is called. To fill in values, you need to call
    /// [`GtkListStoreExtManual::set()`][crate::prelude::GtkListStoreExtManual::set()] or [`GtkListStoreExtManual::set_value()`][crate::prelude::GtkListStoreExtManual::set_value()].
    /// ## `position`
    /// position to insert the new row, or -1 for last
    ///
    /// # Returns
    ///
    ///
    /// ## `iter`
    /// An unset [`TreeIter`][crate::TreeIter] to set to the new row
    #[doc(alias = "gtk_list_store_insert")]
    fn insert(&self, position: i32) -> TreeIter {
        unsafe {
            let mut iter = TreeIter::uninitialized();
            ffi::gtk_list_store_insert(
                self.as_ref().to_glib_none().0,
                iter.to_glib_none_mut().0,
                position,
            );
            iter
        }
    }

    /// Inserts a new row after `sibling`. If `sibling` is [`None`], then the row will be
    /// prepended to the beginning of the list. `iter` will be changed to point to
    /// this new row. The row will be empty after this function is called. To fill
    /// in values, you need to call [`GtkListStoreExtManual::set()`][crate::prelude::GtkListStoreExtManual::set()] or [`GtkListStoreExtManual::set_value()`][crate::prelude::GtkListStoreExtManual::set_value()].
    /// ## `sibling`
    /// A valid [`TreeIter`][crate::TreeIter], or [`None`]
    ///
    /// # Returns
    ///
    ///
    /// ## `iter`
    /// An unset [`TreeIter`][crate::TreeIter] to set to the new row
    #[doc(alias = "gtk_list_store_insert_after")]
    fn insert_after(&self, sibling: Option<&TreeIter>) -> TreeIter {
        unsafe {
            let mut iter = TreeIter::uninitialized();
            ffi::gtk_list_store_insert_after(
                self.as_ref().to_glib_none().0,
                iter.to_glib_none_mut().0,
                mut_override(sibling.to_glib_none().0),
            );
            iter
        }
    }

    /// Inserts a new row before `sibling`. If `sibling` is [`None`], then the row will
    /// be appended to the end of the list. `iter` will be changed to point to this
    /// new row. The row will be empty after this function is called. To fill in
    /// values, you need to call [`GtkListStoreExtManual::set()`][crate::prelude::GtkListStoreExtManual::set()] or [`GtkListStoreExtManual::set_value()`][crate::prelude::GtkListStoreExtManual::set_value()].
    /// ## `sibling`
    /// A valid [`TreeIter`][crate::TreeIter], or [`None`]
    ///
    /// # Returns
    ///
    ///
    /// ## `iter`
    /// An unset [`TreeIter`][crate::TreeIter] to set to the new row
    #[doc(alias = "gtk_list_store_insert_before")]
    fn insert_before(&self, sibling: Option<&TreeIter>) -> TreeIter {
        unsafe {
            let mut iter = TreeIter::uninitialized();
            ffi::gtk_list_store_insert_before(
                self.as_ref().to_glib_none().0,
                iter.to_glib_none_mut().0,
                mut_override(sibling.to_glib_none().0),
            );
            iter
        }
    }

    //#[doc(alias = "gtk_list_store_insert_with_values")]
    //fn insert_with_values(&self, position: i32, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> TreeIter {
    //    unsafe { TODO: call ffi:gtk_list_store_insert_with_values() }
    //}

    //#[doc(alias = "gtk_list_store_insert_with_valuesv")]
    //fn insert_with_valuesv(&self, position: i32, columns: &[i32], values: &[&glib::Value]) -> TreeIter {
    //    unsafe { TODO: call ffi:gtk_list_store_insert_with_valuesv() }
    //}

    /// > This function is slow. Only use it for debugging and/or testing
    /// > purposes.
    ///
    /// Checks if the given iter is a valid iter for this [`ListStore`][crate::ListStore].
    /// ## `iter`
    /// A [`TreeIter`][crate::TreeIter].
    ///
    /// # Returns
    ///
    /// [`true`] if the iter is valid, [`false`] if the iter is invalid.
    #[doc(alias = "gtk_list_store_iter_is_valid")]
    fn iter_is_valid(&self, iter: &TreeIter) -> bool {
        unsafe {
            from_glib(ffi::gtk_list_store_iter_is_valid(
                self.as_ref().to_glib_none().0,
                mut_override(iter.to_glib_none().0),
            ))
        }
    }

    /// Moves `iter` in `self` to the position after `position`. Note that this
    /// function only works with unsorted stores. If `position` is [`None`], `iter`
    /// will be moved to the start of the list.
    /// ## `iter`
    /// A [`TreeIter`][crate::TreeIter].
    /// ## `position`
    /// A [`TreeIter`][crate::TreeIter] or [`None`].
    #[doc(alias = "gtk_list_store_move_after")]
    fn move_after(&self, iter: &TreeIter, position: Option<&TreeIter>) {
        unsafe {
            ffi::gtk_list_store_move_after(
                self.as_ref().to_glib_none().0,
                mut_override(iter.to_glib_none().0),
                mut_override(position.to_glib_none().0),
            );
        }
    }

    /// Moves `iter` in `self` to the position before `position`. Note that this
    /// function only works with unsorted stores. If `position` is [`None`], `iter`
    /// will be moved to the end of the list.
    /// ## `iter`
    /// A [`TreeIter`][crate::TreeIter].
    /// ## `position`
    /// A [`TreeIter`][crate::TreeIter], or [`None`].
    #[doc(alias = "gtk_list_store_move_before")]
    fn move_before(&self, iter: &TreeIter, position: Option<&TreeIter>) {
        unsafe {
            ffi::gtk_list_store_move_before(
                self.as_ref().to_glib_none().0,
                mut_override(iter.to_glib_none().0),
                mut_override(position.to_glib_none().0),
            );
        }
    }

    /// Prepends a new row to `self`. `iter` will be changed to point to this new
    /// row. The row will be empty after this function is called. To fill in
    /// values, you need to call [`GtkListStoreExtManual::set()`][crate::prelude::GtkListStoreExtManual::set()] or [`GtkListStoreExtManual::set_value()`][crate::prelude::GtkListStoreExtManual::set_value()].
    ///
    /// # Returns
    ///
    ///
    /// ## `iter`
    /// An unset [`TreeIter`][crate::TreeIter] to set to the prepend row
    #[doc(alias = "gtk_list_store_prepend")]
    fn prepend(&self) -> TreeIter {
        unsafe {
            let mut iter = TreeIter::uninitialized();
            ffi::gtk_list_store_prepend(self.as_ref().to_glib_none().0, iter.to_glib_none_mut().0);
            iter
        }
    }

    /// Removes the given row from the list store. After being removed,
    /// `iter` is set to be the next valid row, or invalidated if it pointed
    /// to the last row in `self`.
    /// ## `iter`
    /// A valid [`TreeIter`][crate::TreeIter]
    ///
    /// # Returns
    ///
    /// [`true`] if `iter` is valid, [`false`] if not.
    #[doc(alias = "gtk_list_store_remove")]
    fn remove(&self, iter: &TreeIter) -> bool {
        unsafe {
            from_glib(ffi::gtk_list_store_remove(
                self.as_ref().to_glib_none().0,
                mut_override(iter.to_glib_none().0),
            ))
        }
    }

    //#[doc(alias = "gtk_list_store_set_column_types")]
    //fn set_column_types(&self, types: /*Unimplemented*/&CArray TypeId { ns_id: 0, id: 30 }) {
    //    unsafe { TODO: call ffi:gtk_list_store_set_column_types() }
    //}

    //#[doc(alias = "gtk_list_store_set_valist")]
    //fn set_valist(&self, iter: &TreeIter, var_args: /*Unknown conversion*//*Unimplemented*/Unsupported) {
    //    unsafe { TODO: call ffi:gtk_list_store_set_valist() }
    //}

    //#[doc(alias = "gtk_list_store_set_valuesv")]
    //fn set_valuesv(&self, iter: &TreeIter, columns: &[i32], values: &[&glib::Value]) {
    //    unsafe { TODO: call ffi:gtk_list_store_set_valuesv() }
    //}

    /// Swaps `a` and `b` in `self`. Note that this function only works with
    /// unsorted stores.
    /// ## `a`
    /// A [`TreeIter`][crate::TreeIter].
    /// ## `b`
    /// Another [`TreeIter`][crate::TreeIter].
    #[doc(alias = "gtk_list_store_swap")]
    fn swap(&self, a: &TreeIter, b: &TreeIter) {
        unsafe {
            ffi::gtk_list_store_swap(
                self.as_ref().to_glib_none().0,
                mut_override(a.to_glib_none().0),
                mut_override(b.to_glib_none().0),
            );
        }
    }
}

impl<O: IsA<ListStore>> GtkListStoreExt for O {}

impl fmt::Display for ListStore {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("ListStore")
    }
}