<?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">
]>
<refentry id="GdkPaintable">
<refmeta>
<refentrytitle role="top_of_page" id="GdkPaintable.top_of_page">GdkPaintable</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GdkPaintable</refname>
<refpurpose>An interface for a paintable region</refpurpose>
</refnamediv>

<refsect1 id="GdkPaintable.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="GdkPaintable"><returnvalue>GdkPaintable</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-paintable-get-current-image">gdk_paintable_get_current_image</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="gdk-paintable-snapshot">gdk_paintable_snapshot</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GdkPaintableFlags"><returnvalue>GdkPaintableFlags</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-paintable-get-flags">gdk_paintable_get_flags</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="int"><returnvalue>int</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-paintable-get-intrinsic-width">gdk_paintable_get_intrinsic_width</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="int"><returnvalue>int</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-paintable-get-intrinsic-height">gdk_paintable_get_intrinsic_height</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="double"><returnvalue>double</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-paintable-get-intrinsic-aspect-ratio">gdk_paintable_get_intrinsic_aspect_ratio</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="gdk-paintable-compute-concrete-size">gdk_paintable_compute_concrete_size</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="gdk-paintable-invalidate-contents">gdk_paintable_invalidate_contents</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="gdk-paintable-invalidate-size">gdk_paintable_invalidate_size</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GdkPaintable"><returnvalue>GdkPaintable</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-paintable-new-empty">gdk_paintable_new_empty</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GdkPaintable.signals" role="signal_proto">
<title role="signal_proto.title">Signals</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="signal_proto_type" colwidth="150px"/>
<colspec colname="signal_proto_name" colwidth="300px"/>
<colspec colname="signal_proto_flags" colwidth="200px"/>
<tbody>
<row><entry role="signal_type"><link linkend="void"><returnvalue>void</returnvalue></link></entry><entry role="signal_name"><link linkend="GdkPaintable-invalidate-contents">invalidate-contents</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></entry></row>
<row><entry role="signal_type"><link linkend="void"><returnvalue>void</returnvalue></link></entry><entry role="signal_name"><link linkend="GdkPaintable-invalidate-size">invalidate-size</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<anchor id="GdkSnapshot"/><refsect1 id="GdkPaintable.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="GdkPaintable-struct">GdkPaintable</link></entry></row>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GdkPaintableInterface">GdkPaintableInterface</link></entry></row>
<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="GdkPaintableFlags">GdkPaintableFlags</link></entry></row>


<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GdkSnapshot-struct">GdkSnapshot</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GdkPaintable.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GInterface">GInterface</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GdkPaintable
    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GdkSnapshot
</screen>
</refsect1>
<refsect1 id="GdkPaintable.prerequisites" role="prerequisites">
<title role="prerequisites.title">Prerequisites</title>
<para>
GdkPaintable requires
 <link linkend="GObject">GObject</link>.</para>

</refsect1>
<refsect1 id="GdkPaintable.implementations" role="implementations">
<title role="implementations.title">Known Implementations</title>
<para>
GdkPaintable is implemented by
 <link linkend="GdkGLTexture">GdkGLTexture</link>,  <link linkend="GdkMemoryTexture">GdkMemoryTexture</link> and  <link linkend="GdkTexture">GdkTexture</link>.</para>

</refsect1>

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

<refsect1 id="GdkPaintable.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="GdkPaintable"><type>GdkPaintable</type></link> is a simple interface used by GDK and GDK to represent
objects that can be painted anywhere at any size without requiring any
sort of layout. The interface is inspired by similar concepts elsewhere,
such as <ulink url="https://developer.gnome.org/clutter/stable/ClutterContent.html">ClutterContent</ulink>,
<ulink url="https://www.w3.org/TR/css-images-4/#paint-source">HTML/CSS Paint Sources</ulink>,
or <ulink url="https://www.w3.org/TR/SVG2/pservers.html">SVG Paint Servers</ulink>.</para>
<para>A <link linkend="GdkPaintable"><type>GdkPaintable</type></link> can be snapshot at any time and size using
<link linkend="gdk-paintable-snapshot"><function>gdk_paintable_snapshot()</function></link>. How the paintable interprets that size and if it
scales or centers itself into the given rectangle is implementation defined,
though if you are implementing a <link linkend="GdkPaintable"><type>GdkPaintable</type></link> and don't know what to do, it
is suggested that you scale your paintable ignoring any potential aspect ratio.</para>
<para>The contents that a <link linkend="GdkPaintable"><type>GdkPaintable</type></link> produces may depend on the <link linkend="GdkSnapshot"><type>GdkSnapshot</type></link> passed
to it. For example, paintables may decide to use more detailed images on higher
resolution screens or when OpenGL is available. A <link linkend="GdkPaintable"><type>GdkPaintable</type></link> will however
always produce the same output for the same snapshot.</para>
<para>A <link linkend="GdkPaintable"><type>GdkPaintable</type></link> may change its contents, meaning that it will now produce a
different output with the same snapshot. Once that happens, it will call
<link linkend="gdk-paintable-invalidate-contents"><function>gdk_paintable_invalidate_contents()</function></link> which will emit the
<link linkend="GdkPaintable-invalidate-contents"><type>“invalidate-contents”</type></link> signal. If a paintable is known to never
change its contents, it will set the <link linkend="GDK-PAINTABLE-STATIC-CONTENTS:CAPS"><literal>GDK_PAINTABLE_STATIC_CONTENTS</literal></link> flag.
If a consumer cannot deal with changing contents, it may call
<link linkend="gdk-paintable-get-current-image"><function>gdk_paintable_get_current_image()</function></link> which will return a static paintable and
use that.</para>
<para>A paintable can report an intrinsic (or preferred) size or aspect ratio it
wishes to be rendered at, though it doesn't have to. Consumers of the interface
can use this information to layout thepaintable appropriately.
Just like the contents, the size of a paintable can change. A paintable will
indicate this by calling <link linkend="gdk-paintable-invalidate-size"><function>gdk_paintable_invalidate_size()</function></link> which will emit the
<link linkend="GdkPaintable-invalidate-size"><type>“invalidate-size”</type></link> signal.
And just like for contents, if a paintable is known to never change its size,
it will set the <link linkend="GDK-PAINTABLE-STATIC-SIZE:CAPS"><literal>GDK_PAINTABLE_STATIC_SIZE</literal></link> flag.</para>
<para>Besides API for applications, there are some functions that are only
useful for implementing subclasses and should not be used by applications:
<link linkend="gdk-paintable-invalidate-contents"><function>gdk_paintable_invalidate_contents()</function></link>,
<link linkend="gdk-paintable-invalidate-size"><function>gdk_paintable_invalidate_size()</function></link>,
<link linkend="gdk-paintable-new-empty"><function>gdk_paintable_new_empty()</function></link>.</para>

</refsect1>
<refsect1 id="GdkPaintable.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gdk-paintable-get-current-image" role="function">
<title>gdk_paintable_get_current_image&#160;()</title>
<indexterm zone="gdk-paintable-get-current-image"><primary>gdk_paintable_get_current_image</primary></indexterm>
<programlisting language="C"><link linkend="GdkPaintable"><returnvalue>GdkPaintable</returnvalue></link>&#160;*
gdk_paintable_get_current_image (<parameter><link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable</parameter>);</programlisting>
<para>Gets an immutable paintable for the current contents displayed by <parameter>paintable</parameter>
.</para>
<para>This is useful when you want to retain the current state of an animation, for
example to take a screenshot of a running animation.</para>
<para>If the <parameter>paintable</parameter>
 is already immutable, it will return itself.</para>
<refsect3 id="gdk-paintable-get-current-image.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-paintable-get-current-image.returns" role="returns">
<title>Returns</title>
<para>An immutable paintable for the current
contents of <parameter>paintable</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gdk-paintable-snapshot" role="function">
<title>gdk_paintable_snapshot&#160;()</title>
<indexterm zone="gdk-paintable-snapshot"><primary>gdk_paintable_snapshot</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_paintable_snapshot (<parameter><link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable</parameter>,
                        <parameter><link linkend="GdkSnapshot"><type>GdkSnapshot</type></link> *snapshot</parameter>,
                        <parameter><link linkend="double"><type>double</type></link> width</parameter>,
                        <parameter><link linkend="double"><type>double</type></link> height</parameter>);</programlisting>
<para>Snapshots the given paintable with the given <parameter>width</parameter>
 and <parameter>height</parameter>
 at the
current (0,0) offset of the <parameter>snapshot</parameter>
. If <parameter>width</parameter>
 and <parameter>height</parameter>
 are not larger
than zero, this function will do nothing.</para>
<refsect3 id="gdk-paintable-snapshot.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>snapshot</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkSnapshot"><type>GdkSnapshot</type></link> to snapshot to</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>width</para></entry>
<entry role="parameter_description"><para>width to snapshot in</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>height</para></entry>
<entry role="parameter_description"><para>height to snapshot in</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-paintable-get-flags" role="function">
<title>gdk_paintable_get_flags&#160;()</title>
<indexterm zone="gdk-paintable-get-flags"><primary>gdk_paintable_get_flags</primary></indexterm>
<programlisting language="C"><link linkend="GdkPaintableFlags"><returnvalue>GdkPaintableFlags</returnvalue></link>
gdk_paintable_get_flags (<parameter><link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable</parameter>);</programlisting>
<para>Get flags for the paintable. This is oftentimes useful for optimizations.</para>
<para>See <link linkend="GdkPaintableFlags"><type>GdkPaintableFlags</type></link> for the flags and what they mean.</para>
<refsect3 id="gdk-paintable-get-flags.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-paintable-get-flags.returns" role="returns">
<title>Returns</title>
<para> The <link linkend="GdkPaintableFlags"><type>GdkPaintableFlags</type></link> for this paintable.</para>
</refsect3></refsect2>
<refsect2 id="gdk-paintable-get-intrinsic-width" role="function">
<title>gdk_paintable_get_intrinsic_width&#160;()</title>
<indexterm zone="gdk-paintable-get-intrinsic-width"><primary>gdk_paintable_get_intrinsic_width</primary></indexterm>
<programlisting language="C"><link linkend="int"><returnvalue>int</returnvalue></link>
gdk_paintable_get_intrinsic_width (<parameter><link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable</parameter>);</programlisting>
<para>Gets the preferred width the <parameter>paintable</parameter>
 would like to be displayed at.
Consumers of this interface can use this to reserve enough space to draw
the paintable.</para>
<para>This is a purely informational value and does not in any way limit the values
that may be passed to <link linkend="gdk-paintable-snapshot"><function>gdk_paintable_snapshot()</function></link>.</para>
<para>If the <parameter>paintable</parameter>
 does not have a preferred width, it returns 0. Negative
values are never returned.</para>
<refsect3 id="gdk-paintable-get-intrinsic-width.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-paintable-get-intrinsic-width.returns" role="returns">
<title>Returns</title>
<para> the intrinsic width of <parameter>paintable</parameter>
or 0 if none.</para>
</refsect3></refsect2>
<refsect2 id="gdk-paintable-get-intrinsic-height" role="function">
<title>gdk_paintable_get_intrinsic_height&#160;()</title>
<indexterm zone="gdk-paintable-get-intrinsic-height"><primary>gdk_paintable_get_intrinsic_height</primary></indexterm>
<programlisting language="C"><link linkend="int"><returnvalue>int</returnvalue></link>
gdk_paintable_get_intrinsic_height (<parameter><link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable</parameter>);</programlisting>
<para>Gets the preferred height the <parameter>paintable</parameter>
 would like to be displayed at.
Consumers of this interface can use this to reserve enough space to draw
the paintable.</para>
<para>This is a purely informational value and does not in any way limit the values
that may be passed to <link linkend="gdk-paintable-snapshot"><function>gdk_paintable_snapshot()</function></link>.</para>
<para>If the <parameter>paintable</parameter>
 does not have a preferred height, it returns 0. Negative
values are never returned.</para>
<refsect3 id="gdk-paintable-get-intrinsic-height.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-paintable-get-intrinsic-height.returns" role="returns">
<title>Returns</title>
<para> the intrinsic height of <parameter>paintable</parameter>
or 0 if none.</para>
</refsect3></refsect2>
<refsect2 id="gdk-paintable-get-intrinsic-aspect-ratio" role="function">
<title>gdk_paintable_get_intrinsic_aspect_ratio&#160;()</title>
<indexterm zone="gdk-paintable-get-intrinsic-aspect-ratio"><primary>gdk_paintable_get_intrinsic_aspect_ratio</primary></indexterm>
<programlisting language="C"><link linkend="double"><returnvalue>double</returnvalue></link>
gdk_paintable_get_intrinsic_aspect_ratio
                               (<parameter><link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable</parameter>);</programlisting>
<para>Gets the preferred aspect ratio the <parameter>paintable</parameter>
 would like to be displayed at.
The aspect ration is the width divided by the height, so a value of 0.5 means
that the <parameter>paintable</parameter>
 prefers to be displayed twice as high as it is wide.
Consumers of this interface can use this to preserve aspect ratio when displaying
this paintable.</para>
<para>This is a purely informational value and does not in any way limit the values
that may be passed to <link linkend="gdk-paintable-snapshot"><function>gdk_paintable_snapshot()</function></link>.</para>
<para>Usually when a <parameter>paintable</parameter>
 returns non-0 values from
<link linkend="gdk-paintable-get-intrinsic-width"><function>gdk_paintable_get_intrinsic_width()</function></link> and <link linkend="gdk-paintable-get-intrinsic-height"><function>gdk_paintable_get_intrinsic_height()</function></link>
the aspect ratio should conform to those values, though that is not required.</para>
<para>If the <parameter>paintable</parameter>
 does not have a preferred aspect ratio, it returns 0.0.
Negative values are never returned.</para>
<refsect3 id="gdk-paintable-get-intrinsic-aspect-ratio.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-paintable-get-intrinsic-aspect-ratio.returns" role="returns">
<title>Returns</title>
<para> the intrinsic aspect ratio of <parameter>paintable</parameter>
or 0.0 if none.</para>
</refsect3></refsect2>
<refsect2 id="gdk-paintable-compute-concrete-size" role="function">
<title>gdk_paintable_compute_concrete_size&#160;()</title>
<indexterm zone="gdk-paintable-compute-concrete-size"><primary>gdk_paintable_compute_concrete_size</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_paintable_compute_concrete_size (<parameter><link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable</parameter>,
                                     <parameter><link linkend="double"><type>double</type></link> specified_width</parameter>,
                                     <parameter><link linkend="double"><type>double</type></link> specified_height</parameter>,
                                     <parameter><link linkend="double"><type>double</type></link> default_width</parameter>,
                                     <parameter><link linkend="double"><type>double</type></link> default_height</parameter>,
                                     <parameter><link linkend="double"><type>double</type></link> *concrete_width</parameter>,
                                     <parameter><link linkend="double"><type>double</type></link> *concrete_height</parameter>);</programlisting>
<para>Applies the sizing algorithm outlined in 
https://drafts.csswg.org/css-images-3/<link linkend="default-sizing"><type>default-sizing</type></link>
to the given <parameter>paintable</parameter>
. See that link for more details.</para>
<para>It is not necessary to call this function when both <parameter>specified_width</parameter>

and <parameter>specified_height</parameter>
 are known, but it is useful to call this
function in GtkWidget:measure implementations to compute the
other dimension when only one dimension is given.</para>
<refsect3 id="gdk-paintable-compute-concrete-size.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>specified_width</para></entry>
<entry role="parameter_description"><para>the width <parameter>paintable</parameter>
could be drawn into or
0.0 if unknown</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>specified_height</para></entry>
<entry role="parameter_description"><para>the height <parameter>paintable</parameter>
could be drawn into or
0.0 if unknown</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>default_width</para></entry>
<entry role="parameter_description"><para>the width <parameter>paintable</parameter>
would be drawn into if
no other constraints were given</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>default_height</para></entry>
<entry role="parameter_description"><para>the height <parameter>paintable</parameter>
would be drawn into if
no other constraints were given</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>concrete_width</para></entry>
<entry role="parameter_description"><para>will be set to the concrete width
computed. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>concrete_height</para></entry>
<entry role="parameter_description"><para>will be set to the concrete height
computed. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-paintable-invalidate-contents" role="function">
<title>gdk_paintable_invalidate_contents&#160;()</title>
<indexterm zone="gdk-paintable-invalidate-contents"><primary>gdk_paintable_invalidate_contents</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_paintable_invalidate_contents (<parameter><link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable</parameter>);</programlisting>
<para>Called by implementations of <link linkend="GdkPaintable"><type>GdkPaintable</type></link> to invalidate their contents.  
Unless the contents are invalidated, implementations must guarantee that
multiple calls to GdkPaintable::snapshot produce the same output.</para>
<para>This function will emit the <link linkend="GdkPaintable-invalidate-contents"><type>“invalidate-contents”</type></link> signal.</para>
<para>If a <parameter>paintable</parameter>
 reports the <link linkend="GDK-PAINTABLE-STATIC-CONTENTS:CAPS"><literal>GDK_PAINTABLE_STATIC_CONTENTS</literal></link> flag,
it must not call this function.</para>
<refsect3 id="gdk-paintable-invalidate-contents.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-paintable-invalidate-size" role="function">
<title>gdk_paintable_invalidate_size&#160;()</title>
<indexterm zone="gdk-paintable-invalidate-size"><primary>gdk_paintable_invalidate_size</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_paintable_invalidate_size (<parameter><link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable</parameter>);</programlisting>
<para>Called by implementations of <link linkend="GdkPaintable"><type>GdkPaintable</type></link> to invalidate their size.  
As long as the size is not invalidated, <parameter>paintable</parameter>
 must return the same values
for its width, height and intrinsic height.</para>
<para>This function will emit the <link linkend="GdkPaintable-invalidate-size"><type>“invalidate-size”</type></link> signal.</para>
<para>If a <parameter>paintable</parameter>
 reports the <link linkend="GDK-PAINTABLE-STATIC-SIZE:CAPS"><literal>GDK_PAINTABLE_STATIC_SIZE</literal></link> flag,
it must not call this function.</para>
<refsect3 id="gdk-paintable-invalidate-size.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-paintable-new-empty" role="function">
<title>gdk_paintable_new_empty&#160;()</title>
<indexterm zone="gdk-paintable-new-empty"><primary>gdk_paintable_new_empty</primary></indexterm>
<programlisting language="C"><link linkend="GdkPaintable"><returnvalue>GdkPaintable</returnvalue></link>&#160;*
gdk_paintable_new_empty (<parameter><link linkend="int"><type>int</type></link> intrinsic_width</parameter>,
                         <parameter><link linkend="int"><type>int</type></link> intrinsic_height</parameter>);</programlisting>
<para>Returns a paintable that has the given intrinsic size and draws nothing.
This is often useful for implementing the <link linkend="GdkPaintableInterface.get-current-image"><function>GdkPaintableInterface.get_current_image()</function></link>
virtual function when the paintable is in an incomplete state (like a
<link linkend="GtkMediaStream"><type>GtkMediaStream</type></link> before receiving the first frame).</para>
<refsect3 id="gdk-paintable-new-empty.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>intrinsic_width</para></entry>
<entry role="parameter_description"><para>The intrinsic width to report. Can be 0 for no width.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>intrinsic_height</para></entry>
<entry role="parameter_description"><para>The intrinsic height to report. Can be 0 for no height.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-paintable-new-empty.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GdkPaintable.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GdkPaintable-struct" role="struct">
<title>GdkPaintable</title>
<indexterm zone="GdkPaintable-struct"><primary>GdkPaintable</primary></indexterm>
<programlisting language="C">typedef struct _GdkPaintable GdkPaintable;</programlisting>
</refsect2>
<refsect2 id="GdkPaintableInterface" role="struct">
<title>struct GdkPaintableInterface</title>
<indexterm zone="GdkPaintableInterface"><primary>GdkPaintableInterface</primary></indexterm>
<programlisting language="C">struct GdkPaintableInterface {
  /* draw to 0,0 with the given width and height */
  void                  (* snapshot)                    (GdkPaintable           *paintable,
                                                         GdkSnapshot            *snapshot,
                                                         double                  width,
                                                         double                  height);
  /* get the current contents in an immutable form (optional) */
  GdkPaintable *        (* get_current_image)           (GdkPaintable           *paintable);

  /* get flags for potential optimizations (optional) */
  GdkPaintableFlags     (* get_flags)                   (GdkPaintable           *paintable);
  /* preferred width of paintable or 0 if it has no width (optional) */
  int                   (* get_intrinsic_width)         (GdkPaintable           *paintable);
  /* preferred height of paintable or 0 if it has no height (optional) */
  int                   (* get_intrinsic_height)        (GdkPaintable           *paintable);
  /* aspect ratio (width / height) of paintable or 0 if it has no aspect ratio (optional) */
  double                (* get_intrinsic_aspect_ratio)  (GdkPaintable           *paintable);
};
</programlisting>
<para>The list of functions that can be implemented for the <link linkend="GdkPaintable"><type>GdkPaintable</type></link> interface.
Note that apart from the first function, no function is mandatory to implement,
though it is a good idea to implement <link linkend="GdkPaintableInterface.get-current-image"><function>GdkPaintableInterface.get_current_image()</function></link>
for non-static paintables and <link linkend="GdkPaintableInterface.get-flags"><function>GdkPaintableInterface.get_flags()</function></link> if the image
is not dynamic as the default implementation returns no flags and that will
make the implementation likely quite slow.</para>
<refsect3 id="GdkPaintableInterface.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><structfield id="GdkPaintableInterface.snapshot">snapshot</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Snapshot the paintable. The given <parameter>width</parameter>
and <parameter>height</parameter>
are
guaranteed to be larger than 0.0. The resulting snapshot must modify
only the area in the rectangle from (0,0) to (width, height).
This is the only function that must be implemented for this interface.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GdkPaintableInterface.get-current-image">get_current_image</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>return a <link linkend="GdkPaintable"><type>GdkPaintable</type></link> that does not change over
time. This means the GDK_PAINTABLE_STATIC_SIZE and
<link linkend="GDK-PAINTABLE-STATIC-CONTENTS:CAPS"><literal>GDK_PAINTABLE_STATIC_CONTENTS</literal></link> flag are set.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GdkPaintableInterface.get-flags">get_flags</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Get the flags for this instance. See <link linkend="GdkPaintableFlags"><type>GdkPaintableFlags</type></link>
for details.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GdkPaintableInterface.get-intrinsic-width">get_intrinsic_width</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>The preferred width for this object to be
snapshot at or 0 if none. This is purely a hint. The object must still
be able to render at any size.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GdkPaintableInterface.get-intrinsic-height">get_intrinsic_height</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>The preferred height for this object to be
snapshot at or 0 if none. This is purely a hint. The object must still
be able to render at any size.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GdkPaintableInterface.get-intrinsic-aspect-ratio">get_intrinsic_aspect_ratio</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>The preferred aspect ratio for this object
or 0 if none. If both <link linkend="GdkPaintableInterface.get-intrinsic-width"><function>GdkPaintableInterface.get_intrinsic_width()</function></link> and
<link linkend="GdkPaintableInterface.get-intrinsic-height"><function>GdkPaintableInterface.get_intrinsic_height()</function></link> return non-zero values,
this function should return the aspect ratio computed from those.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>
<refsect2 id="GdkPaintableFlags" role="enum">
<title>enum GdkPaintableFlags</title>
<indexterm zone="GdkPaintableFlags"><primary>GdkPaintableFlags</primary></indexterm>
<para>Flags about this object. Implementations use these for optimizations
such as caching.</para>
<refsect3 id="GdkPaintableFlags.members" role="enum_members">
<title>Members</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="enum_members_name" colwidth="300px"/>
<colspec colname="enum_members_description"/>
<colspec colname="enum_members_annotations" colwidth="200px"/>
<tbody>
<row role="constant"><entry role="enum_member_name"><para id="GDK-PAINTABLE-STATIC-SIZE:CAPS">GDK_PAINTABLE_STATIC_SIZE</para></entry>
<entry role="enum_member_description"><para>The size is immutable.
The <link linkend="GdkPaintable-invalidate-size"><type>“invalidate-size”</type></link> signal will never be
emitted.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GDK-PAINTABLE-STATIC-CONTENTS:CAPS">GDK_PAINTABLE_STATIC_CONTENTS</para></entry>
<entry role="enum_member_description"><para>The content is immutable.
The <link linkend="GdkPaintable-invalidate-contents"><type>“invalidate-contents”</type></link> signal will never be
emitted.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="GdkSnapshot-struct" role="struct">
<title>GdkSnapshot</title>
<indexterm zone="GdkSnapshot-struct"><primary>GdkSnapshot</primary></indexterm>
<programlisting language="C">typedef struct _GdkSnapshot GdkSnapshot;</programlisting>
</refsect2>

</refsect1>
<refsect1 id="GdkPaintable.signal-details" role="signals">
<title role="signals.title">Signal Details</title>
<refsect2 id="GdkPaintable-invalidate-contents" role="signal"><title>The <literal>“invalidate-contents”</literal> signal</title>
<indexterm zone="GdkPaintable-invalidate-contents"><primary>GdkPaintable::invalidate-contents</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
user_function (<link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable,
               <link linkend="gpointer"><type>gpointer</type></link>      user_data)</programlisting>
<para>Emitted when the contents of the <parameter>paintable</parameter>
 change.</para>
<para>Examples for such an event would be videos changing to the next frame or
the icon theme for an icon changing.</para>
<refsect3 id="GdkPaintable-invalidate-contents.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para>Flags: <link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></para>
</refsect2><refsect2 id="GdkPaintable-invalidate-size" role="signal"><title>The <literal>“invalidate-size”</literal> signal</title>
<indexterm zone="GdkPaintable-invalidate-size"><primary>GdkPaintable::invalidate-size</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
user_function (<link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable,
               <link linkend="gpointer"><type>gpointer</type></link>      user_data)</programlisting>
<para>Emitted when the intrinsic size of the <parameter>paintable</parameter>
 changes. This means the values
reported by at least one of <link linkend="gdk-paintable-get-intrinsic-width"><function>gdk_paintable_get_intrinsic_width()</function></link>,
<link linkend="gdk-paintable-get-intrinsic-height"><function>gdk_paintable_get_intrinsic_height()</function></link> or <link linkend="gdk-paintable-get-intrinsic-aspect-ratio"><function>gdk_paintable_get_intrinsic_aspect_ratio()</function></link>
has changed.</para>
<para>Examples for such an event would be a paintable displaying the contents of a toplevel
surface being resized.</para>
<refsect3 id="GdkPaintable-invalidate-size.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>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para>Flags: <link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></para>
</refsect2>
</refsect1>
<refsect1 id="GdkPaintable.see-also">
<title>See Also</title>
<para><link linkend="ClutterContent"><type>ClutterContent</type></link>, <link linkend="GtkImage"><type>GtkImage</type></link>, <link linkend="GdkTexture"><type>GdkTexture</type></link>, <link linkend="GtkSnapshot"><type>GtkSnapshot</type></link></para>

</refsect1>

</refentry>
