Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
A list-like data structure that can be used with the TreeView
.
The GtkListStore
object is a list model for use with a GtkTreeView
widget. It implements the GtkTreeModel
interface, and consequentialy,
can use all of the methods available there. It also implements the
GtkTreeSortable
interface so it can be sorted by the view.
Finally, it also implements the tree
drag and drop
interfaces.
The GtkListStore
can accept most GType
s 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 GObject
s are handled a little differently. The
GtkListStore
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
signalgtk
.TreeModel[row_changed] signal. This most commonly affects lists
with Texture
s 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; int i; list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT, G_TYPE_BOOLEAN); for (i = 0; i < 10; i++) { char *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 GtkListStore
was originally implemented with a linked list
with a tail pointer. As a result, it was fast at data insertion and deletion,
and not fast at random data access. The GtkListStore
sets the
GTK_TREE_MODEL_ITERS_PERSIST
flag, which means that GtkTreeIter
s 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 listStoreInsertWithValues
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 GtkTreeModel
signaling.
In contrast, using e.g. listStoreAppend
and then gtk_list_store_set()
will first create a row, which triggers the GtkTreeModel::row-inserted
signal
on GtkListStore
. The row, however, is still empty, and any signal handler
connecting to GtkTreeModel::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 GtkListStore
inside a GtkTreeModel
Filter and are
using a GtkTreeModel
FilterVisibleFunc. Using any of the non-atomic operations
to append rows to the GtkListStore
will cause the
GtkTreeModel
FilterVisibleFunc to be visited with an empty row first; the
function must be prepared for that.
GtkListStore as GtkBuildable
The GtkListStore implementation of the Buildable
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:
xml 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
- listStoreInsertWithValues :: (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 toManagedPtr :: ListStore -> ManagedPtr ListStore | |
TypedObject ListStore Source # | |
Defined in GI.Gtk.Objects.ListStore | |
HasParentTypes ListStore Source # | |
Defined in GI.Gtk.Objects.ListStore | |
IsGValue (Maybe ListStore) Source # | Convert |
Defined in GI.Gtk.Objects.ListStore gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe ListStore -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe 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
Click to display all available methods, including inherited ones
Methods
append, bindProperty, bindPropertyFull, clear, dragDataDelete, dragDataGet, dragDataReceived, filterNew, forceFloating, foreach, freezeNotify, getv, hasDefaultSortFunc, insert, insertAfter, insertBefore, insertWithValues, isFloating, iterChildren, iterHasChild, iterIsValid, iterNChildren, iterNext, iterNthChild, iterParent, iterPrevious, moveAfter, moveBefore, notify, notifyByPspec, prepend, ref, refNode, refSink, remove, reorder, rowChanged, rowDeleted, rowDraggable, rowDropPossible, rowHasChildToggled, rowInserted, rowsReordered, runDispose, set, sortColumnChanged, stealData, stealQdata, swap, thawNotify, unref, unrefNode, watchClosure.
Getters
getBuildableId, getColumnType, getData, getFlags, getIter, getIterFirst, getIterFromString, getNColumns, getPath, getProperty, getQdata, getSortColumnId, getStringFromIter, getValue.
Setters
setColumnTypes, setData, setDataFull, setDefaultSortFunc, setProperty, setSortColumnId, setSortFunc, setValue.
append
:: (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
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> m () |
Removes all rows from the list store.
insert
:: (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
:: (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 #
:: (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
.
insertWithValues
listStoreInsertWithValues Source #
:: (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.
iterIsValid
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> TreeIter |
|
-> m Bool | Returns: |
Checks if the given iter is a valid iter for this GtkListStore
.
This function is slow. Only use it for debugging and/or testing purposes.
moveAfter
:: (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.
moveBefore
:: (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.
new
:: (HasCallStack, MonadIO m) | |
=> [GType] |
|
-> m ListStore | Returns: a new |
Non-vararg creation function. Used primarily by language bindings.
prepend
:: (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
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> TreeIter |
|
-> m Bool |
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
:: (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.
set
:: (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.
setColumnTypes
listStoreSetColumnTypes Source #
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> [GType] |
|
-> m () |
This function is meant primarily for GObject
s that inherit from GtkListStore
,
and should only be used when constructing a new GtkListStore
. It will not
function after a row has been added, or a method on the GtkTreeModel
interface is called.
setValue
:: (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.
swap
:: (HasCallStack, MonadIO m, IsListStore a) | |
=> a |
|
-> TreeIter |
|
-> TreeIter |
|
-> m () |
Swaps a
and b
in store
. Note that this function only works with
unsorted stores.