<?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="GtkMapListModel">
<refmeta>
<refentrytitle role="top_of_page" id="GtkMapListModel.top_of_page">GtkMapListModel</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkMapListModel</refname>
<refpurpose>A list model that transforms its items</refpurpose>
</refnamediv>

<refsect1 id="GtkMapListModel.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GtkMapListModelMapFunc">*GtkMapListModelMapFunc</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkMapListModel"><returnvalue>GtkMapListModel</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-map-list-model-new">gtk_map_list_model_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-map-list-model-set-map-func">gtk_map_list_model_set_map_func</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-map-list-model-set-model">gtk_map_list_model_set_model</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GListModel"><returnvalue>GListModel</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-map-list-model-get-model">gtk_map_list_model_get_model</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-map-list-model-has-map">gtk_map_list_model_has_map</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkMapListModel.properties" role="properties">
<title role="properties.title">Properties</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="properties_type" colwidth="150px"/>
<colspec colname="properties_name" colwidth="300px"/>
<colspec colname="properties_flags" colwidth="200px"/>
<tbody>
<row><entry role="property_type"><link linkend="gboolean"><type>gboolean</type></link></entry><entry role="property_name"><link linkend="GtkMapListModel--has-map">has-map</link></entry><entry role="property_flags">Read</entry></row>
<row><entry role="property_type"><link linkend="GType"><type>GType</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkMapListModel--item-type">item-type</link></entry><entry role="property_flags">Read / Write / Construct&#160;Only</entry></row>
<row><entry role="property_type"><link linkend="GListModel"><type>GListModel</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkMapListModel--model">model</link></entry><entry role="property_flags">Read / Write / Construct&#160;Only</entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkMapListModel.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="GtkMapListModel-struct">GtkMapListModel</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkMapListModel.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> GtkMapListModel
</screen>
</refsect1>
<refsect1 id="GtkMapListModel.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkMapListModel implements
 <link linkend="GListModel">GListModel</link>.</para>

</refsect1>

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

<refsect1 id="GtkMapListModel.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="GtkMapListModel"><type>GtkMapListModel</type></link> is a list model that takes a list model and maps the items
in that model to different items according to a <link linkend="GtkMapListModelMapFunc"><type>GtkMapListModelMapFunc</type></link>.</para>
<para>Example: Create a list of <link linkend="GtkEventControllers"><type>GtkEventControllers</type></link></para>
<informalexample><programlisting role="example"><![CDATA[
  static gpointer
  map_to_controllers (gpointer widget,
                      gpointer data)
 {
    gpointer result = gtk_widget_observe_controllers (widget);
    g_object_unref (widget);
    return result;
 }

  widgets = gtk_widget_observe_children (widget);

  controllers = gtk_map_list_model_new (G_TYPE_LIST_MODEL,
                                        widgets,
                                        map_to_controllers,
                                        NULL, NULL);

  model = gtk_flatten_list_model_new (GTK_TYPE_EVENT_CONTROLLER,
                                      controllers);
]]></programlisting></informalexample>
<para></para>
<para><link linkend="GtkMapListModel"><type>GtkMapListModel</type></link> will attempt to discard the mapped objects as soon as
they are no longer needed and recreate them if necessary.</para>

</refsect1>
<refsect1 id="GtkMapListModel.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="GtkMapListModelMapFunc" role="function">
<title>GtkMapListModelMapFunc&#160;()</title>
<indexterm zone="GtkMapListModelMapFunc"><primary>GtkMapListModelMapFunc</primary></indexterm>
<programlisting language="C"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GtkMapListModelMapFunc<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="gpointer"><type>gpointer</type></link> item</parameter>,
                           <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</programlisting>
<para>User function that is called to map an <parameter>item</parameter>
 of the original model to
an item expected by the map model.</para>
<para>The returned items must conform to the item type of the model they are
used with.</para>
<refsect3 id="GtkMapListModelMapFunc.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>item</para></entry>
<entry role="parameter_description"><para>The item to map. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> GObject][<acronym>transfer full</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>user data</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="GtkMapListModelMapFunc.returns" role="returns">
<title>Returns</title>
<para>The item to map to.
This function may not return <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>type</acronym> GObject][<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-map-list-model-new" role="function">
<title>gtk_map_list_model_new&#160;()</title>
<indexterm zone="gtk-map-list-model-new"><primary>gtk_map_list_model_new</primary></indexterm>
<programlisting language="C"><link linkend="GtkMapListModel"><returnvalue>GtkMapListModel</returnvalue></link>&#160;*
gtk_map_list_model_new (<parameter><link linkend="GType"><type>GType</type></link> item_type</parameter>,
                        <parameter><link linkend="GListModel"><type>GListModel</type></link> *model</parameter>,
                        <parameter><link linkend="GtkMapListModelMapFunc"><type>GtkMapListModelMapFunc</type></link> map_func</parameter>,
                        <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>,
                        <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> user_destroy</parameter>);</programlisting>
<para>Creates a new <link linkend="GtkMapListModel"><type>GtkMapListModel</type></link> for the given arguments.</para>
<refsect3 id="gtk-map-list-model-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>item_type</para></entry>
<entry role="parameter_description"><para>the <link linkend="GType"><type>GType</type></link> to use as the model's item type</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>model</para></entry>
<entry role="parameter_description"><para>The model to map or <link linkend="NULL:CAPS"><literal>NULL</literal></link> for none. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>map_func</para></entry>
<entry role="parameter_description"><para>map function or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to not map items. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>user data passed to <parameter>map_func</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>closure</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>user_destroy</para></entry>
<entry role="parameter_description"><para>destroy notifier for <parameter>user_data</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-map-list-model-new.returns" role="returns">
<title>Returns</title>
<para> a new <link linkend="GtkMapListModel"><type>GtkMapListModel</type></link></para>
</refsect3></refsect2>
<refsect2 id="gtk-map-list-model-set-map-func" role="function">
<title>gtk_map_list_model_set_map_func&#160;()</title>
<indexterm zone="gtk-map-list-model-set-map-func"><primary>gtk_map_list_model_set_map_func</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_map_list_model_set_map_func (<parameter><link linkend="GtkMapListModel"><type>GtkMapListModel</type></link> *self</parameter>,
                                 <parameter><link linkend="GtkMapListModelMapFunc"><type>GtkMapListModelMapFunc</type></link> map_func</parameter>,
                                 <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>,
                                 <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> user_destroy</parameter>);</programlisting>
<para>Sets the function used to map items. The function will be called whenever
an item needs to be mapped and must return the item to use for the given
input item.</para>
<para>Note that <link linkend="GtkMapListModel"><type>GtkMapListModel</type></link> may call this function multiple times on the
same item, because it may delete items it doesn't need anymore.</para>
<para>GTK makes no effort to ensure that <parameter>map_func</parameter>
 conforms to the item type
of <parameter>self</parameter>
. It assumes that the caller knows what they are doing and the map
function returns items of the appropriate type.</para>
<refsect3 id="gtk-map-list-model-set-map-func.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkMapListModel"><type>GtkMapListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>map_func</para></entry>
<entry role="parameter_description"><para>map function or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to not map items. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>user data passed to <parameter>map_func</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>closure</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>user_destroy</para></entry>
<entry role="parameter_description"><para>destroy notifier for <parameter>user_data</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-map-list-model-set-model" role="function">
<title>gtk_map_list_model_set_model&#160;()</title>
<indexterm zone="gtk-map-list-model-set-model"><primary>gtk_map_list_model_set_model</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_map_list_model_set_model (<parameter><link linkend="GtkMapListModel"><type>GtkMapListModel</type></link> *self</parameter>,
                              <parameter><link linkend="GListModel"><type>GListModel</type></link> *model</parameter>);</programlisting>
<para>Sets the model to be mapped.</para>
<para>GTK makes no effort to ensure that <parameter>model</parameter>
 conforms to the item type
expected by the map function. It assumes that the caller knows what
they are doing and have set up an appropriate map function.</para>
<refsect3 id="gtk-map-list-model-set-model.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkMapListModel"><type>GtkMapListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>model</para></entry>
<entry role="parameter_description"><para>The model to be mapped. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-map-list-model-get-model" role="function">
<title>gtk_map_list_model_get_model&#160;()</title>
<indexterm zone="gtk-map-list-model-get-model"><primary>gtk_map_list_model_get_model</primary></indexterm>
<programlisting language="C"><link linkend="GListModel"><returnvalue>GListModel</returnvalue></link>&#160;*
gtk_map_list_model_get_model (<parameter><link linkend="GtkMapListModel"><type>GtkMapListModel</type></link> *self</parameter>);</programlisting>
<para>Gets the model that is curently being mapped or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if none.</para>
<refsect3 id="gtk-map-list-model-get-model.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkMapListModel"><type>GtkMapListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-map-list-model-get-model.returns" role="returns">
<title>Returns</title>
<para>The model that gets mapped. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-map-list-model-has-map" role="function">
<title>gtk_map_list_model_has_map&#160;()</title>
<indexterm zone="gtk-map-list-model-has-map"><primary>gtk_map_list_model_has_map</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_map_list_model_has_map (<parameter><link linkend="GtkMapListModel"><type>GtkMapListModel</type></link> *self</parameter>);</programlisting>
<para>Checks if a map function is currently set on <parameter>self</parameter>
</para>
<refsect3 id="gtk-map-list-model-has-map.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>self</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkMapListModel"><type>GtkMapListModel</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-map-list-model-has-map.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if a map function is set</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkMapListModel.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkMapListModel-struct" role="struct">
<title>GtkMapListModel</title>
<indexterm zone="GtkMapListModel-struct"><primary>GtkMapListModel</primary></indexterm>
<programlisting language="C">typedef struct _GtkMapListModel GtkMapListModel;</programlisting>
</refsect2>

</refsect1>
<refsect1 id="GtkMapListModel.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkMapListModel--has-map" role="property"><title>The <literal>“has-map”</literal> property</title>
<indexterm zone="GtkMapListModel--has-map"><primary>GtkMapListModel:has-map</primary></indexterm>
<programlisting>  “has-map”                  <link linkend="gboolean"><type>gboolean</type></link></programlisting>
<para>If a map is set for this model</para>
<para>Owner: GtkMapListModel</para>
<para>Flags: Read</para>
<para>Default value: FALSE</para>
</refsect2>
<refsect2 id="GtkMapListModel--item-type" role="property"><title>The <literal>“item-type”</literal> property</title>
<indexterm zone="GtkMapListModel--item-type"><primary>GtkMapListModel:item-type</primary></indexterm>
<programlisting>  “item-type”                <link linkend="GType"><type>GType</type></link>&#160;*</programlisting>
<para>The <link linkend="GType"><type>GType</type></link> for elements of this object</para>
<para>Owner: GtkMapListModel</para>
<para>Flags: Read / Write / Construct&#160;Only</para>
<para>Allowed values: GObject</para>
</refsect2>
<refsect2 id="GtkMapListModel--model" role="property"><title>The <literal>“model”</literal> property</title>
<indexterm zone="GtkMapListModel--model"><primary>GtkMapListModel:model</primary></indexterm>
<programlisting>  “model”                    <link linkend="GListModel"><type>GListModel</type></link>&#160;*</programlisting>
<para>The model being mapped</para>
<para>Owner: GtkMapListModel</para>
<para>Flags: Read / Write / Construct&#160;Only</para>
</refsect2>

</refsect1>
<refsect1 id="GtkMapListModel.see-also">
<title>See Also</title>
<para><link linkend="GListModel"><type>GListModel</type></link></para>

</refsect1>

</refentry>
