diff options
Diffstat (limited to 'docs/reference/pygio-icon.xml')
| -rw-r--r-- | docs/reference/pygio-icon.xml | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/docs/reference/pygio-icon.xml b/docs/reference/pygio-icon.xml new file mode 100644 index 0000000..5a32d28 --- /dev/null +++ b/docs/reference/pygio-icon.xml @@ -0,0 +1,217 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gioicon"> + <refnamediv> + <refname>gio.Icon</refname> + <refpurpose>Interface for icons.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.Icon</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioicon--equal">equal</link></methodname> + <methodparam><parameter role="keyword">icon2</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioicon--to-string">to_string</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + +<programlisting> +<emphasis role="bold">Functions</emphasis> + +<methodsynopsis language="python"> + <methodname><link linkend="function-gio--icon-new-from-string">gio.icon_new_from_string</link></methodname> + <methodparam></methodparam> +</methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-gioicon">gio.Icon</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Known Derived Interfaces</title> + <para> + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> is required by + <link linkend="class-gioloadableicon"><classname>gio.LoadableIcon</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Known Implementation</title> + <para> + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> is implemented by + <link linkend="class-giothemedicon"><classname>gio.ThemedIcon</classname></link>, + <link linkend="class-giofileicon"><classname>gio.FileIcon</classname></link>, + <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link>, + <link linkend="class-gioemblemedicon"><classname>gio.EmblemedIcon</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + is a very minimal interface for icons. It provides functions for checking + the equality of two icons, hashing of icons and serializing an icon to and from strings. + </para> + <para> + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + does not provide the actual pixmap for the icon as this is out of GIO's + scope, however implementations of + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + may contain the name of an icon (see + <link linkend="class-giothemedicon"><classname>gio.ThemedIcon</classname></link>), + or the path to an icon (see + <link linkend="class-gioloadableicon"><classname>gio.LoadableIcon</classname></link>). + </para> + <!-- + <para> + To obtain a hash of a <link linkend="class-gioicon"><classname>gio.Icon</classname></link>, see + <methodname><link linkend="method-gioicon- -hash">gio.Icon.hash</link></methodname>(). + </para> + --> + <para> + To check if two GIcons are equal, see + <methodname><link linkend="method-gioicon--equal">gio.Icon.equal</link></methodname>(). + </para> + <para> + For serializing a <link linkend="class-gioicon"><classname>gio.Icon</classname></link>, + use <methodname><link linkend="method-gioicon- -to-string">gio.Icon.to_string</link></methodname>() and + <methodname><link linkend="method-gioicon- -new-from-string">gio.Icon.new_from_string</link></methodname>(). + </para> + <para> + If your application or library provides one or more + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + implementations you need to ensure that each GType is registered + with the type system prior to calling + <methodname><link linkend="function-gioicon--new-from-string">gio.icon_new_from_string</link></methodname>(). + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioicon--equal"> + <title>gio.Icon.equal</title> + + <programlisting><methodsynopsis language="python"> + <methodname>equal</methodname> + <methodparam><parameter role="keyword">icon2</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>icon2</parameter> :</term> + <listitem><simpara>the second + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>equal</methodname>() method checks if two icons are equal. + </para> + </refsect2> + + <refsect2 id="method-gioicon--to-string"> + <title>gio.Icon.to_string</title> + + <programlisting><methodsynopsis language="python"> + <methodname>to_string</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>An UTF8 string or <literal>None</literal> + if icon can't be serialized. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>to_string</methodname>() method generates a textual + representation of icon that can be used for serialization such as when + passing icon to a different process or saving it to persistent storage. Use + <methodname><link linkend="function-gio--icon-new-from-string">gio.icon_new_from_string</link></methodname>() + to get icon back from the returned string. + </para> + <para> + The encoding of the returned string is proprietary to GIcon except in the following two cases + </para> + <para> + If icon is a <link linkend="class-giofileicon"><classname>gio.FileIcon</classname></link>, + the returned string is a native path (such as /path/to/my icon.png) without escaping + if the <link linkend="class-giofile"><classname>gio.File</classname></link> + for icon is a native file. If the file is not native, the returned string is the result of + <methodname><link linkend="method-giofile--get-uri">gio.File.get_uri</link></methodname>() + (such as sftp://path/to/my%20icon.png). + </para> + <para> + If icon is a <link linkend="class-giothemedicon"><classname>gio.ThemedIcon</classname></link> + with exactly one name, the encoding is simply the name (such as network-server). + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--icon-new-from-string"> + <title>gio.icon_new_from_string</title> + + <programlisting><methodsynopsis language="python"> + <methodname>icon_new_from_string</methodname> + <methodparam><parameter role="keyword">str</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>str</parameter> :</term> + <listitem><simpara>A string obtained via + <methodname><link linkend="method-gioicon--to-string">gio.Icon.to_string</link></methodname>(). + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>An object implementing the + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + interface or <literal>None</literal> if error is set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>icon_new_from_string</methodname>() function generate a + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + instance from str. This function can fail if str is not valid - see + <methodname><link linkend="method-gioicon--to-string">gio.Icon.to_string</link></methodname>() + for discussion. + </para> + <para> + If your application or library provides one or more GIcon implementations you need + to ensure that each GType is registered with the type system prior to calling + <methodname><link linkend="function-gio--icon-new-from-string">gio.icon_new_from_string</link></methodname>(). + </para> + </refsect2> + </refsect1> +</refentry> |