29
29
\section{Hierarchy}{\preformatted{GObject
30
30
+----GtkListStore}}
31
31
\section{Interfaces}{GtkListStore implements
32
\verb{\link{GtkBuildable}}, \verb{\link{GtkTreeModel}}, \verb{\link{GtkTreeDragSource}}, \verb{\link{GtkTreeDragDest}} and \verb{\link{GtkTreeSortable}}.}
33
\section{Detailed Description}{The \verb{\link{GtkListStore}} object is a list model for use with a \verb{\link{GtkTreeView}}
34
widget. It implements the \verb{\link{GtkTreeModel}} interface, and consequentialy,
32
\code{\link{GtkTreeModel}}, \code{\link{GtkTreeDragSource}}, \code{\link{GtkTreeDragDest}}, \code{\link{GtkTreeSortable}} and \code{\link{GtkBuildable}}.}
33
\section{Detailed Description}{The \code{\link{GtkListStore}} object is a list model for use with a \code{\link{GtkTreeView}}
34
widget. It implements the \code{\link{GtkTreeModel}} interface, and consequentialy,
35
35
can use all of the methods available there. It also implements the
36
\verb{\link{GtkTreeSortable}} interface so it can be sorted by the view.
36
\code{\link{GtkTreeSortable}} interface so it can be sorted by the view.
37
37
Finally, it also implements the tree drag and
40
The \verb{\link{GtkListStore}} can accept most GObject types as a column type, though
40
The \code{\link{GtkListStore}} can accept most GObject types as a column type, though
41
41
it can't accept all custom types. Internally, it will keep a copy of
42
42
data passed in (such as a string or a boxed pointer). Columns that
43
accept \verb{\link{GObject}}s are handled a little differently. The
44
\verb{\link{GtkListStore}} will keep a reference to the object instead of copying the
43
accept \code{\link{GObject}}s are handled a little differently. The
44
\code{\link{GtkListStore}} will keep a reference to the object instead of copying the
45
45
value. As a result, if the object is modified, it is up to the
46
46
application writer to call \code{gtk.tree.model.row.changed} to emit the
47
47
"row_changed" signal. This most commonly affects lists with
48
\verb{\link{GdkPixbuf}}s stored.
48
\code{\link{GdkPixbuf}}s stored.
50
50
\emph{Creating a simple list store.}
64
64
list_store$set(iter, 2, TRUE)
67
\section{Performance Considerations}{Internally, the \verb{\link{GtkListStore}} was implemented with a linked list with a
67
\section{Performance Considerations}{Internally, the \code{\link{GtkListStore}} was implemented with a linked list with a
68
68
tail pointer prior to GTK+ 2.6. As a result, it was fast at data
69
69
insertion and deletion, and not fast at random data access. The
70
\verb{\link{GtkListStore}} sets the \verb{GTK_TREE_MODEL_ITERS_PERSIST} flag, which means
71
that \verb{\link{GtkTreeIter}}s can be cached while the row exists. Thus, if
70
\code{\link{GtkListStore}} sets the \verb{GTK_TREE_MODEL_ITERS_PERSIST} flag, which means
71
that \code{\link{GtkTreeIter}}s can be cached while the row exists. Thus, if
72
72
access to a particular row is needed often and your code is expected to
73
73
run on older versions of GTK+, it is worth keeping the iter around.
75
It is important to note that only the methods
76
\code{\link{gtkListStoreInsertWithValues}} and \code{\link{gtkListStoreInsertWithValuesv}}
77
are atomic, in the sense that the row is being appended to the store and the
78
values filled in in a single operation with regard to \verb{\link{GtkTreeModel}} signaling.
79
In contrast, using e.g. \code{\link{gtkListStoreAppend}} and then \code{\link{gtkListStoreSet}}
80
will first create a row, which triggers the \code{\link{gtkTreeModelRowInserted}} signal
81
on \verb{\link{GtkListStore}}. The row, however, is still empty, and any signal handler
75
It is important to note that only the methods
76
\code{\link{gtkListStoreInsertWithValues}} and \code{\link{gtkListStoreInsertWithValuesv}}
77
are atomic, in the sense that the row is being appended to the store and the
78
values filled in in a single operation with regard to \code{\link{GtkTreeModel}} signaling.
79
In contrast, using e.g. \code{\link{gtkListStoreAppend}} and then \code{\link{gtkListStoreSet}}
80
will first create a row, which triggers the \code{\link{gtkTreeModelRowInserted}} signal
81
on \code{\link{GtkListStore}}. The row, however, is still empty, and any signal handler
82
82
connecting to "row-inserted" on this particular store should be prepared
83
for the situation that the row might be empty. This is especially important
84
if you are wrapping the \verb{\link{GtkListStore}} inside a \verb{\link{GtkTreeModelFilter}} and are
85
using a \verb{\link{GtkTreeModelFilterVisibleFunc}}. Using any of the non-atomic operations
86
to append rows to the \verb{\link{GtkListStore}} will cause the
87
\verb{\link{GtkTreeModelFilterVisibleFunc}} to be visited with an empty row first; the
83
for the situation that the row might be empty. This is especially important
84
if you are wrapping the \code{\link{GtkListStore}} inside a \code{\link{GtkTreeModelFilter}} and are
85
using a \code{\link{GtkTreeModelFilterVisibleFunc}}. Using any of the non-atomic operations
86
to append rows to the \code{\link{GtkListStore}} will cause the
87
\code{\link{GtkTreeModelFilterVisibleFunc}} to be visited with an empty row first; the
88
88
function must be prepared for that.}
89
89
\section{GtkListStore as GtkBuildable}{The GtkListStore implementation of the GtkBuildable interface allows
90
90
to specify the model columns with a <columns> element that may
97
97
row of the list model. Inside a <row>, the <col> elements
98
98
specify the content for individual cells.
100
Note that it is probably more common to define your models
101
in the code, and one might consider it a layering violation
100
Note that it is probably more common to define your models
101
in the code, and one might consider it a layering violation
102
102
to specify the content of a list store in a UI definition,
103
\emph{data}, not \emph{presentation},
104
and common wisdom is to separate the two, as far as possible.
103
\emph{data}, not \emph{presentation},
104
and common wisdom is to separate the two, as far as possible.
107
107
\emph{A UI Definition fragment for a list store}\preformatted{<object class="GtkListStore">
132
132
\section{Convenient Construction}{\code{gtkListStore} is the result of collapsing the constructors of \code{GtkListStore} (\code{\link{gtkListStoreNew}}, \code{\link{gtkListStoreNewv}}) and accepts a subset of its arguments matching the required arguments of one of its delegate constructors.}
133
\references{\url{http://developer.gnome.org/doc/API/2.0/gtk/GtkListStore.html}}
133
\references{\url{http://library.gnome.org/devel//gtk/GtkListStore.html}}
134
134
\author{Derived by RGtkGen from GTK+ documentation}
136
\verb{\link{GtkTreeModel}}
137
\verb{\link{GtkTreeStore}}
136
\code{\link{GtkTreeModel}}
137
\code{\link{GtkTreeStore}}
139
139
\keyword{internal}
added
removed
man/GtkListStore.Rd
