1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
<?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-gtkiconfactory">
<refnamediv>
<refname>gtk.IconFactory</refname>
<refpurpose>an object that manages a group of icon sets.</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<classsynopsis language="python">
<ooclass><classname>gtk.IconFactory</classname></ooclass>
<ooclass><classname><link
linkend="class-gobject">gobject.GObject</link></classname></ooclass>
<constructorsynopsis language="python">
<methodname><link
linkend="constructor-gtkiconfactory">gtk.IconFactory</link></methodname>
<methodparam></methodparam> </constructorsynopsis>
<methodsynopsis language="python">
<methodname><link
linkend="method-gtkiconfactory--add">add</link></methodname>
<methodparam><parameter
role="keyword">stock_id</parameter></methodparam>
<methodparam><parameter
role="keyword">icon_set</parameter></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link
linkend="method-gtkiconfactory--lookup">lookup</link></methodname>
<methodparam><parameter
role="keyword">stock_id</parameter></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link
linkend="method-gtkiconfactory--add-default">add_default</link></methodname>
<methodparam></methodparam> </methodsynopsis>
<methodsynopsis language="python">
<methodname><link
linkend="method-gtkiconfactory--remove-default">remove_default</link></methodname>
<methodparam></methodparam> </methodsynopsis>
</classsynopsis>
<programlisting>
<emphasis role="bold">Functions</emphasis>
<methodsynopsis language="python">
<methodname><link
linkend="function-gtk--icon-factory-lookup-default">gtk.icon_factory_lookup_default</link></methodname>
<methodparam><parameter role="keyword">stock_id</parameter>
</methodparam>
</methodsynopsis></programlisting>
</refsect1>
<refsect1>
<title>Ancestry</title>
<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
+-- <link linkend="class-gtkiconfactory">gtk.IconFactory</link>
</synopsis>
</refsect1>
<refsect1 id="signal-prototypes-gtkiconfactory">
<title>gtk.IconFactory Signal Prototypes</title>
<para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
</refsect1>
<refsect1>
<title>Description</title>
<para>A <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>
manages a group of <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link>s that
manage a set of variants (for different sizes and states) of a specific
icon. Icons in an icon factory are named by a stock ID, which is a simple
string identifying the icon e.g "gtk-ok". Each <link
linkend="class-gtkstyle"><classname>gtk.Style</classname></link> has a list
of <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>s
derived from the current theme; those icon factories are consulted first
when searching for an icon. If the theme doesn't set a particular icon, the
search continues for the icon in a list of default icon factories,
maintained by the <link
linkend="method-gtkiconfactory--add-default"><methodname>add_default</methodname>()</link>()
and <link
linkend="method-gtkiconfactory--remove-default"><methodname>remove_default</methodname>()</link>()
methods. Applications with icons should add a default icon factory with
their icons, which will allow themes to override the icons for the
application.</para>
<para>To display an icon, always use <link
linkend="method-gtkstyle--lookup-icon-set"><methodname>gtk.Style.lookup_icon_set</methodname>()</link>
on the widget that will display the icon, or the convenience function <link
linkend="method-gtkwidget--render-icon"><methodname>gtk.Widget.render_icon</methodname>()</link>.
These functions take the theme into account when looking up the icon to use
for a given stock ID. </para>
</refsect1>
<refsect1 id="constructor-gtkiconfactory">
<title>Constructor</title>
<programlisting><constructorsynopsis language="python">
<methodname>gtk.IconFactory</methodname>
<methodparam></methodparam> </constructorsynopsis></programlisting>
<variablelist>
<varlistentry>
<term><emphasis>Returns</emphasis> :</term>
<listitem><simpara>a new <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>
object</simpara></listitem>
</varlistentry>
</variablelist>
<para>Creates a new <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>.</para>
</refsect1>
<refsect1>
<title>Methods</title>
<refsect2 id="method-gtkiconfactory--add">
<title>gtk.IconFactory.add</title>
<programlisting><methodsynopsis language="python">
<methodname>add</methodname>
<methodparam><parameter
role="keyword">stock_id</parameter></methodparam>
<methodparam><parameter
role="keyword">icon_set</parameter></methodparam>
</methodsynopsis></programlisting>
<variablelist>
<varlistentry>
<term><parameter role="keyword">stock_id</parameter> :</term>
<listitem><simpara>an icon name</simpara></listitem>
</varlistentry>
<varlistentry>
<term><parameter role="keyword">icon_set</parameter> :</term>
<listitem><simpara>an icon set</simpara></listitem>
</varlistentry>
</variablelist>
<para>The <methodname>add</methodname>() method adds the specified
<parameter>icon_set</parameter> to the icon factory, under the name
<parameter>stock_id</parameter>. the <parameter>stock_id</parameter> string
should include the name of your application, e.g. "myapp-whatever-icon".
Normally applications create a <link
linkend="class-gtkiconfactory"><classname>gtk.IconFactory</classname></link>,
then add it to the list of default factories with the <link
linkend="method-gtkiconfactory--add-default"><methodname>add_default</methodname>()</link>.
Then they pass the <parameter>stock_id</parameter> to widgets such as <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> to display
the icon. Themes can provide an icon with the same name (such as
"myapp-whatever-icon") to override your application's default icons. If an
icon already existed in the icon factory for
<parameter>stock_id</parameter>, it is unreferenced and replaced with the
new <parameter>icon_set</parameter>.</para>
</refsect2>
<refsect2 id="method-gtkiconfactory--lookup">
<title>gtk.IconFactory.lookup</title>
<programlisting><methodsynopsis language="python">
<methodname>lookup</methodname>
<methodparam><parameter
role="keyword">stock_id</parameter></methodparam>
</methodsynopsis></programlisting>
<variablelist>
<varlistentry>
<term><parameter role="keyword">stock_id</parameter> :</term>
<listitem><simpara>an icon name</simpara></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>Returns</emphasis> :</term>
<listitem><simpara>the icon set named
<parameter>stock_id</parameter>.</simpara></listitem>
</varlistentry>
</variablelist>
<para>The <methodname>lookup</methodname>() method looks up
<parameter>stock_id</parameter> in the icon factory, returning an icon set
if found, otherwise <literal>None</literal>. For display to the user, you
should use <link
linkend="method-gtkstyle--lookup-icon-set"><methodname>gtk.Style.lookup_icon_set</methodname>()</link>
on the <link
linkend="class-gtkstyle"><classname>gtk.Style</classname></link> for the
widget that will display the icon, instead of using this function directly,
so that themes are taken into account.</para>
</refsect2>
<refsect2 id="method-gtkiconfactory--add-default">
<title>gtk.IconFactory.add_default</title>
<programlisting><methodsynopsis language="python">
<methodname>add_default</methodname>
<methodparam></methodparam> </methodsynopsis></programlisting>
<para>The <methodname>add_default</methodname>() method adds the icon
factory to the list of icon factories searched by <link
linkend="method-gtkstyle--lookup-icon-set"><methodname>gtk.Style.lookup_icon_set</methodname>()</link>.
This means that, for example, <link
linkend="method-gtkimage--set-from-stock"><methodname>gtk.Image.set_from_stock</methodname>()</link>
will be able to find icons in the icon factory. There will normally be an
icon factory added for each library or application that comes with icons.
The default icon factories can be overridden by themes.</para>
</refsect2>
<refsect2 id="method-gtkiconfactory--remove-default">
<title>gtk.IconFactory.remove_default</title>
<programlisting><methodsynopsis language="python">
<methodname>remove_default</methodname>
<methodparam></methodparam> </methodsynopsis></programlisting>
<para>The <methodname>remove_default</methodname>() method removes an
icon factory from the list of default icon factories. Not normally used
though you might use it for a library that can be unloaded or shut
down.</para>
</refsect2>
</refsect1>
<refsect1>
<title>Functions</title>
<refsect2 id="function-gtk--icon-factory-lookup-default">
<title>gtk.icon_factory_lookup_default</title>
<programlisting><methodsynopsis language="python">
<methodname>gtk.icon_factory_lookup_default</methodname>
<methodparam><parameter role="keyword">stock_id</parameter>
</methodparam>
</methodsynopsis></programlisting>
<variablelist>
<varlistentry>
<term><parameter role="keyword">stock_id</parameter> :</term>
<listitem><simpara>the stock ID to lookup</simpara></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>Returns</emphasis> :</term>
<listitem><simpara>the icon set matching
<parameter>stock_id</parameter> or <literal>None</literal> if no icon set
matches</simpara></listitem>
</varlistentry>
</variablelist>
<para>The <function>gtk.icon_factory_lookup_default</function>()
function returns the <link
linkend="class-gtkiconset"><classname>gtk.IconSet</classname></link> that
has the name specified by <parameter>stock_id</parameter>. If the icon set
cannot be found the function returns <literal>None</literal>.</para>
</refsect2>
</refsect1>
</refentry>
|
