Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | None |
Language | Haskell2010 |
GI.Gtk.Objects.ListStore
Description
The ListStore
object is a list model for use with a TreeView
widget. It implements the TreeModel
interface, and consequentialy,
can use all of the methods available there. It also implements the
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
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
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 treeModelRowChanged
to emit the
TreeModel
::row_changed
signal. This most commonly affects lists with
GdkPixbufs
stored.
An example for creating a simple list store:
C code
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
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
sets the GTK_TREE_MODEL_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 listStoreInsertWithValuesv
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
signaling.
In contrast, using e.g. listStoreAppend
and then gtk_list_store_set()
will first create a row, which triggers the rowInserted signal
on ListStore
. The row, however, is still empty, and any signal handler
connecting to rowInserted 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
inside a TreeModelFilter
and are
using a TreeModelFilterVisibleFunc
. Using any of the non-atomic operations
to append rows to the ListStore
will cause the
TreeModelFilterVisibleFunc
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:
C code
<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>
Synopsis
- newtype ListStore = ListStore (ManagedPtr ListStore)
- class (GObject o, IsDescendantOf ListStore o) => IsListStore o
- toListStore :: (MonadIO m, IsListStore o) => o -> m ListStore
- listStoreAppend :: (HasCallStack, MonadIO m, IsListStore a) => a -> m TreeIter
- listStoreClear :: (HasCallStack, MonadIO m, IsListStore a) => a -> m ()
- listStoreInsert :: (HasCallStack, MonadIO m, IsListStore a) => a -> Int32 -> m TreeIter
- listStoreInsertAfter :: (HasCallStack, MonadIO m, IsListStore a) => a -> Maybe TreeIter -> m TreeIter
- listStoreInsertBefore :: (HasCallStack, MonadIO m, IsListStore a) => a -> Maybe TreeIter -> m TreeIter
- listStoreInsertWithValuesv :: (HasCallStack, MonadIO m, IsListStore a) => a -> Int32 -> [Int32] -> [GValue] -> m TreeIter
- listStoreIterIsValid :: (HasCallStack, MonadIO m, IsListStore a) => a -> TreeIter -> m Bool
- listStoreMoveAfter :: (HasCallStack, MonadIO m, IsListStore a) => a -> TreeIter -> Maybe TreeIter -> m ()
- listStoreMoveBefore :: (HasCallStack, MonadIO m, IsListStore a) => a -> TreeIter -> Maybe TreeIter -> m ()
- listStoreNew :: (HasCallStack, MonadIO m) => [GType] -> m ListStore
- listStorePrepend :: (HasCallStack, MonadIO m, IsListStore a) => a -> m TreeIter
- listStoreRemove :: (HasCallStack, MonadIO m, IsListStore a) => a -> TreeIter -> m Bool
- listStoreReorder :: (HasCallStack, MonadIO m, IsListStore a) => a -> [Int32] -> m ()
- listStoreSet :: (HasCallStack, MonadIO m, IsListStore a) => a -> TreeIter -> [Int32] -> [GValue] -> m ()
- listStoreSetColumnTypes :: (HasCallStack, MonadIO m, IsListStore a) => a -> [GType] -> m ()
- listStoreSetValue :: (HasCallStack, MonadIO m, IsListStore a) => a -> TreeIter -> Int32 -> GValue -> m ()
- listStoreSwap :: (HasCallStack, MonadIO m, IsListStore a) => a -> TreeIter -> TreeIter -> m ()
Exported types
Memory-managed wrapper type.
Instances
Eq ListStore Source # | |
GObject ListStore Source # | |
Defined in GI.Gtk.Objects.ListStore | |
ManagedPtrNewtype ListStore Source # | |
Defined in GI.Gtk.Objects.ListStore Methods toManagedPtr :: ListStore -> ManagedPtr ListStore | |
TypedObject ListStore Source # | |
Defined in GI.Gtk.Objects.ListStore Methods glibType :: IO GType | |
IsGValue ListStore Source # | Convert |
Defined in GI.Gtk.Objects.ListStore | |
HasParentTypes ListStore Source # | |
Defined in GI.Gtk.Objects.ListStore | |
type ParentTypes ListStore Source # | |
Defined in GI.Gtk.Objects.ListStore type ParentTypes ListStore = '[Object, Buildable, TreeDragDest, TreeDragSource, TreeModel, TreeSortable] |
class (GObject o, IsDescendantOf ListStore o) => IsListStore o Source #
Type class for types which can be safely cast to ListStore
, for instance with toListStore
.
Instances
(GObject o, IsDescendantOf ListStore o) => IsListStore o Source # | |
Defined in GI.Gtk.Objects.ListStore |
toListStore :: (MonadIO m, IsListStore o) => o -> m ListStore Source #
Methods
Overloaded methods
append
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> m TreeIter |
Appends a new row to listStore
. 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 gtk_list_store_set()
or listStoreSetValue
.
clear
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> m () |
Removes all rows from the list store.
insert
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> Int32 |
|
-> m TreeIter |
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
gtk_list_store_set()
or listStoreSetValue
.
insertAfter
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> Maybe TreeIter |
|
-> m TreeIter |
Inserts a new row after sibling
. If sibling
is Nothing
, 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 gtk_list_store_set()
or listStoreSetValue
.
insertBefore
listStoreInsertBefore Source #
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> Maybe TreeIter |
|
-> m TreeIter |
Inserts a new row before sibling
. If sibling
is Nothing
, 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 gtk_list_store_set()
or listStoreSetValue
.
insertWithValuesv
listStoreInsertWithValuesv Source #
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> Int32 |
|
-> [Int32] |
|
-> [GValue] |
|
-> m TreeIter |
A variant of gtk_list_store_insert_with_values()
which
takes the columns and values as two arrays, instead of
varargs. This function is mainly intended for
language-bindings.
Since: 2.6
iterIsValid
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> TreeIter |
|
-> m Bool | Returns: |
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
.
Since: 2.2
moveAfter
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> TreeIter |
|
-> Maybe TreeIter |
|
-> m () |
Moves iter
in store
to the position after position
. Note that this
function only works with unsorted stores. If position
is Nothing
, iter
will be moved to the start of the list.
Since: 2.2
moveBefore
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> TreeIter |
|
-> Maybe TreeIter |
|
-> m () |
Moves iter
in store
to the position before position
. Note that this
function only works with unsorted stores. If position
is Nothing
, iter
will be moved to the end of the list.
Since: 2.2
new
Arguments
:: (HasCallStack, MonadIO m) | |
=> [GType] |
|
-> m ListStore | Returns: a new |
Non-vararg creation function. Used primarily by language bindings.
prepend
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> m TreeIter |
Prepends a new row to listStore
. 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 gtk_list_store_set()
or listStoreSetValue
.
remove
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> TreeIter |
|
-> m Bool | Returns: |
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 listStore
.
reorder
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> [Int32] |
|
-> m () |
Reorders store
to follow the order indicated by newOrder
. Note that
this function only works with unsorted stores.
Since: 2.2
set
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> TreeIter |
|
-> [Int32] |
|
-> [GValue] |
|
-> m () |
A variant of gtk_list_store_set_valist()
which
takes the columns and values as two arrays, instead of
varargs. This function is mainly intended for
language-bindings and in case the number of columns to
change is not known until run-time.
Since: 2.12
setColumnTypes
listStoreSetColumnTypes Source #
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> [GType] |
|
-> m () |
setValue
Arguments
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> TreeIter |
|
-> Int32 |
|
-> GValue |
|
-> m () |
Sets the data in the cell specified by iter
and column
.
The type of value
must be convertible to the type of the
column.