<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY pi "&#960;">
<!ENTITY solidus "&#8260;">
]>
<refentry id="GtkListItemFactory">
<refmeta>
<refentrytitle role="top_of_page" id="GtkListItemFactory.top_of_page">GtkListItemFactory</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkListItemFactory</refname>
<refpurpose>Mapping list items to widgets</refpurpose>
</refnamediv>

<refsect1 id="GtkListItemFactory.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GtkListItemFactory-struct">GtkListItemFactory</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkListItemFactory.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkListItemFactory
        <phrase role="lineart">&#9500;&#9472;&#9472;</phrase> <link linkend="GtkBuilderListItemFactory">GtkBuilderListItemFactory</link>
        <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GtkSignalListItemFactory">GtkSignalListItemFactory</link>
</screen>
</refsect1>

<refsect1 id="GtkListItemFactory.includes"><title>Includes</title><synopsis>#include &lt;gtk/gtk.h&gt;
</synopsis></refsect1>

<refsect1 id="GtkListItemFactory.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="GtkListItemFactory"><type>GtkListItemFactory</type></link> is one of the core concepts of handling list widgets.
It is the object tasked with creating widgets for items taken from a
<link linkend="GListModel"><type>GListModel</type></link> when the views need them and updating them as the items
displayed by the view change.</para>
<para>A view is usually only able to display anything after both a factory
and a model have been set on the view. So it is important that you do
not skip this step when setting up your first view.</para>
<para>Because views do not display the whole list at once but only a few
items, they only need to maintain a few widgets at a time. They will
instruct the <link linkend="GtkListItemFactory"><type>GtkListItemFactory</type></link> to create these widgets and bind them
to the items that are currently displayed.
As the list model changes or the user scrolls to the list, the items will
change and the view will instruct the factory to bind the widgets to those
new items.</para>
<para>The actual widgets used for displaying those widgets is provided by you.</para>
<para>When the factory needs widgets created, it will create a <link linkend="GtkListItem"><type>GtkListItem</type></link> and
hand it to your code to set up a widget for. This list item will provide
various properties with information about what item to display and provide
you with some opportunities to configure its behavior. See the <link linkend="GtkListItem"><type>GtkListItem</type></link>
documentation for further details.</para>
<para>Various implementations of <link linkend="GtkListItemFactory"><type>GtkListItemFactory</type></link> exist to allow you different
ways to provide those widgets. The most common implementations are
<link linkend="GtkBuilderListItemFactory"><type>GtkBuilderListItemFactory</type></link> which takes a <link linkend="GtkBuilder"><type>GtkBuilder</type></link> .ui file and then creates
widgets and manages everything automatically from the information in that file
and <link linkend="GtkSignalListItemFactory"><type>GtkSignalListItemFactory</type></link> which allows you to connect to signals with your
own code and retain full control over how the widgets are setup and managed.</para>
<para>A <link linkend="GtkListItemFactory"><type>GtkListItemFactory</type></link> is supposed to be final - that means its behavior should
not change and the first widget created from it should behave the same way as
the last widget created from it.
If you intend to do changes to the behavior, it is recommended that you create
a new <link linkend="GtkListItemFactory"><type>GtkListItemFactory</type></link> which will allow the views to recreate its widgets.</para>
<para>Once you have chosen your factory and created it, you need to set it on the
view widget you want to use it with, such as via <link linkend="gtk-list-view-set-factory"><function>gtk_list_view_set_factory()</function></link>.
Reusing factories across different views is allowed, but very uncommon.</para>

</refsect1>
<refsect1 id="GtkListItemFactory.functions_details" role="details">
<title role="details.title">Functions</title>
<para />
</refsect1>
<refsect1 id="GtkListItemFactory.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkListItemFactory-struct" role="struct">
<title>GtkListItemFactory</title>
<indexterm zone="GtkListItemFactory-struct"><primary>GtkListItemFactory</primary></indexterm>
<programlisting language="C">typedef struct _GtkListItemFactory GtkListItemFactory;</programlisting>
</refsect2>

</refsect1>

</refentry>
