<refentry id="GtkListStore">
<refmeta>
<refentrytitle>GtkListStore</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GtkListStore</refname><refpurpose></refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gtk/gtk.h&gt;


struct      <link linkend="GtkListStore-struct">GtkListStore</link>;
<link linkend="GtkListStore">GtkListStore</link>* <link linkend="gtk-list-store-new">gtk_list_store_new</link>            (<link linkend="gint">gint</link> n_columns,
                                             ...);
<link linkend="GtkListStore">GtkListStore</link>* <link linkend="gtk-list-store-newv">gtk_list_store_newv</link>           (<link linkend="gint">gint</link> n_columns,
                                             <link linkend="GType">GType</link> *types);
void        <link linkend="gtk-list-store-set-column-types">gtk_list_store_set_column_types</link> (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="gint">gint</link> n_columns,
                                             <link linkend="GType">GType</link> *types);
void        <link linkend="gtk-list-store-set">gtk_list_store_set</link>              (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             ...);
void        <link linkend="gtk-list-store-set-valist">gtk_list_store_set_valist</link>       (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             va_list var_args);
void        <link linkend="gtk-list-store-set-value">gtk_list_store_set_value</link>        (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             <link linkend="gint">gint</link> column,
                                             <link linkend="GValue">GValue</link> *value);
void        <link linkend="gtk-list-store-remove">gtk_list_store_remove</link>           (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter);
void        <link linkend="gtk-list-store-insert">gtk_list_store_insert</link>           (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             <link linkend="gint">gint</link> position);
void        <link linkend="gtk-list-store-insert-before">gtk_list_store_insert_before</link>    (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *sibling);
void        <link linkend="gtk-list-store-insert-after">gtk_list_store_insert_after</link>     (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *sibling);
void        <link linkend="gtk-list-store-prepend">gtk_list_store_prepend</link>          (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter);
void        <link linkend="gtk-list-store-append">gtk_list_store_append</link>           (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter);
void        <link linkend="gtk-list-store-clear">gtk_list_store_clear</link>            (<link linkend="GtkListStore">GtkListStore</link> *list_store);


</synopsis>
</refsynopsisdiv>

<refsect1>
<title>Object Hierarchy</title>
<synopsis>

  <link linkend="GObject">GObject</link>
   +----GtkListStore
</synopsis>

</refsect1>




<refsect1>
<title>Description</title>
<para>
The <link linkend="GtkListStore">GtkListStore</link> object is a list model for use with a <link linkend="GtkTreeView">GtkTreeView</link>
widget.  It implements the <link linkend="GtkTreeModel">GtkTreeModel</link> interface, and consequentialy,
can use all of the methods available there.  It also implements the
<link linkend="GtkTreeSortable">GtkTreeSortable</link> interface so you can sort the list using the view.
Finally, it also implements the tree <link linkend="gtktreednd">drag and
drop</link> interfaces.
</para>

<para>
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GtkListStore-struct">struct GtkListStore</title>
<programlisting>struct GtkListStore;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-new">gtk_list_store_new ()</title>
<programlisting><link linkend="GtkListStore">GtkListStore</link>* gtk_list_store_new            (<link linkend="gint">gint</link> n_columns,
                                             ...);</programlisting>
<para>
Creates a new list store as with <parameter>n_columns</parameter> columns each of the types passed
in.  As an example, <literal>gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
GDK_TYPE_PIXBUF);</literal> will create a new <link linkend="GtkListStore">GtkListStore</link> with three columns, of type
int, string and <link linkend="GdkPixbuf">GdkPixbuf</link> respectively.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>n_columns</parameter>&nbsp;:</entry>
<entry> number of columns in the list store
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry> all <link linkend="GType">GType</link> types for the columns, from first to last
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-newv">gtk_list_store_newv ()</title>
<programlisting><link linkend="GtkListStore">GtkListStore</link>* gtk_list_store_newv           (<link linkend="gint">gint</link> n_columns,
                                             <link linkend="GType">GType</link> *types);</programlisting>
<para>
Non-vararg creation function.  Used primarily by language bindings.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>n_columns</parameter>&nbsp;:</entry>
<entry> number of columns in the list store
</entry></row>
<row><entry align="right"><parameter>types</parameter>&nbsp;:</entry>
<entry> an array of <link linkend="GType">GType</link> types for the columns, from first to last
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-set-column-types">gtk_list_store_set_column_types ()</title>
<programlisting>void        gtk_list_store_set_column_types (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="gint">gint</link> n_columns,
                                             <link linkend="GType">GType</link> *types);</programlisting>
<para>
This function is meant primarily for <link linkend="GObjects">GObjects</link> that inherit from <link linkend="GtkListStore">GtkListStore</link>,
and should only be used when constructing a new <link linkend="GtkListStore">GtkListStore</link>.  It will not
function after a row has been added, or a method on the <link linkend="GtkTreeModel">GtkTreeModel</link>
interface is called.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> A <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
<row><entry align="right"><parameter>n_columns</parameter>&nbsp;:</entry>
<entry> Number of columns for the list store
</entry></row>
<row><entry align="right"><parameter>types</parameter>&nbsp;:</entry>
<entry> An array length n of <link linkend="GTypes">GTypes</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-set">gtk_list_store_set ()</title>
<programlisting>void        gtk_list_store_set              (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             ...);</programlisting>
<para>
Sets the value of one or more cells in the row referenced by <parameter>iter</parameter>.
The variable argument list should contain integer column numbers,
each column number followed by the value to be set.
The list is terminated by a -1. For example, to set column 0 with type
<literal>G_TYPE_STRING</literal> to "Foo", you would write <literal>gtk_list_store_set (store, iter,
0, "Foo", -1)</literal>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> row iterator
</entry></row>
<row><entry align="right"><parameter>...</parameter>&nbsp;:</entry>
<entry> pairs of column number and value, terminated with -1
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-set-valist">gtk_list_store_set_valist ()</title>
<programlisting>void        gtk_list_store_set_valist       (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             va_list var_args);</programlisting>
<para>
See <link linkend="gtk-list-store-set">gtk_list_store_set</link>(); this version takes a va_list for use by language
bindings.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> A <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> A valid <link linkend="GtkTreeIter">GtkTreeIter</link> for the row being modified
</entry></row>
<row><entry align="right"><parameter>var_args</parameter>&nbsp;:</entry>
<entry> va_list of column/value pairs
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-set-value">gtk_list_store_set_value ()</title>
<programlisting>void        gtk_list_store_set_value        (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             <link linkend="gint">gint</link> column,
                                             <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Sets the data in the cell specified by <parameter>iter</parameter> and <parameter>column</parameter>.
The type of <parameter>value</parameter> must be convertible to the type of the
column.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> A <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> A valid <link linkend="GtkTreeIter">GtkTreeIter</link> for the row being modified
</entry></row>
<row><entry align="right"><parameter>column</parameter>&nbsp;:</entry>
<entry> column number to modify
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> new value for the cell
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-remove">gtk_list_store_remove ()</title>
<programlisting>void        gtk_list_store_remove           (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter);</programlisting>
<para>
Removes the given row from the list store.  After being removed, 
<parameter>iter</parameter> is set to be the next valid row, or invalidated if it pointed 
to the last row in <parameter>list_store</parameter>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> A <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> A valid <link linkend="GtkTreeIter">GtkTreeIter</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-insert">gtk_list_store_insert ()</title>
<programlisting>void        gtk_list_store_insert           (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             <link linkend="gint">gint</link> position);</programlisting>
<para>
Creates a new row at <parameter>position</parameter>.  <parameter>iter</parameter> will be changed to point to this new
row.  If <parameter>position</parameter> 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 before this
function is called.  To fill in values, you need to call <link linkend="gtk-list-store-set">gtk_list_store_set</link>()
or <link linkend="gtk-list-store-set-value">gtk_list_store_set_value</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> A <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> An unset <link linkend="GtkTreeIter">GtkTreeIter</link> to set to the new row
</entry></row>
<row><entry align="right"><parameter>position</parameter>&nbsp;:</entry>
<entry> position to insert the new row
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-insert-before">gtk_list_store_insert_before ()</title>
<programlisting>void        gtk_list_store_insert_before    (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *sibling);</programlisting>
<para>
Inserts a new row before <parameter>sibling</parameter>. If <parameter>sibling</parameter> is <literal>NULL</literal>, then the row will be
appended to the end of the list. <parameter>iter</parameter> will be changed to point to this new 
row. The row will be empty before this function is called. To fill in values,
you need to call <link linkend="gtk-list-store-set">gtk_list_store_set</link>() or <link linkend="gtk-list-store-set-value">gtk_list_store_set_value</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> A <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> An unset <link linkend="GtkTreeIter">GtkTreeIter</link> to set to the new row
</entry></row>
<row><entry align="right"><parameter>sibling</parameter>&nbsp;:</entry>
<entry> A valid <link linkend="GtkTreeIter">GtkTreeIter</link>, or <literal>NULL</literal>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-insert-after">gtk_list_store_insert_after ()</title>
<programlisting>void        gtk_list_store_insert_after     (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *sibling);</programlisting>
<para>
Inserts a new row after <parameter>sibling</parameter>. If <parameter>sibling</parameter> is <literal>NULL</literal>, then the row will be
prepended to the beginning of the list. <parameter>iter</parameter> 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 <link linkend="gtk-list-store-set">gtk_list_store_set</link>() or <link linkend="gtk-list-store-set-value">gtk_list_store_set_value</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> A <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> An unset <link linkend="GtkTreeIter">GtkTreeIter</link> to set to the new row
</entry></row>
<row><entry align="right"><parameter>sibling</parameter>&nbsp;:</entry>
<entry> A valid <link linkend="GtkTreeIter">GtkTreeIter</link>, or <literal>NULL</literal>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-prepend">gtk_list_store_prepend ()</title>
<programlisting>void        gtk_list_store_prepend          (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter);</programlisting>
<para>
Prepends a new row to <parameter>list_store</parameter>. <parameter>iter</parameter> 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 <link linkend="gtk-list-store-set">gtk_list_store_set</link>() or <link linkend="gtk-list-store-set-value">gtk_list_store_set_value</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> A <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> An unset <link linkend="GtkTreeIter">GtkTreeIter</link> to set to the prepend row
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-append">gtk_list_store_append ()</title>
<programlisting>void        gtk_list_store_append           (<link linkend="GtkListStore">GtkListStore</link> *list_store,
                                             <link linkend="GtkTreeIter">GtkTreeIter</link> *iter);</programlisting>
<para>
Appends a new row to <parameter>list_store</parameter>.  <parameter>iter</parameter> 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 <link linkend="gtk-list-store-set">gtk_list_store_set</link>() or <link linkend="gtk-list-store-set-value">gtk_list_store_set_value</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> A <link linkend="GtkListStore">GtkListStore</link>
</entry></row>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> An unset <link linkend="GtkTreeIter">GtkTreeIter</link> to set to the appended row
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-list-store-clear">gtk_list_store_clear ()</title>
<programlisting>void        gtk_list_store_clear            (<link linkend="GtkListStore">GtkListStore</link> *list_store);</programlisting>
<para>
Removes all rows from the list store.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list_store</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkListStore">GtkListStore</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>
