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
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
|
<?xml version="1.0"?>
<!DOCTYPE book 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'">
]>
<book id="index" lang="en">
<bookinfo>
<title>Exo Reference Manual</title>
<releaseinfo>Version <xi:include href="version.xml" parse="text"/></releaseinfo>
<pubdate>September 2009</pubdate>
<copyright>
<year>2004</year>
<year>2005</year>
<year>2006</year>
<year>2007</year>
<holder>os-cillation e.K.</holder>
</copyright>
<copyright>
<year>2009</year>
<holder>Xfce Development Team</holder>
</copyright>
<legalnotice id="legalnotice">
<para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. The complete license text is available from the <ulink
type="http" url="http://www.gnu.org/">Free Software Foundation</ulink>.
</para>
</legalnotice>
<authorgroup>
<author>
<firstname>Benedikt</firstname>
<surname>Meurer</surname>
<affiliation>
<address><email>benny@xfce.org</email></address>
<orgname>os-cillation</orgname>
<orgdiv>System development</orgdiv>
<jobtitle>Software developer</jobtitle>
</affiliation>
</author>
<author>
<firstname>Jannis</firstname>
<surname>Pohlmann</surname>
<affiliation>
<address><email>jannis@xfce.org</email></address>
</affiliation>
</author>
</authorgroup>
</bookinfo>
<part id="exo-overview">
<title>Overview</title>
<para>
<ulink type="http" url="http://libexo.os-cillation.com/">libexo</ulink> is an extension
library for <ulink url="http://www.xfce.org/" type="http">Xfce</ulink>,
developed by <ulink url="http://www.os-cillation.com/" type="http">os-cillation</ulink>.
While Xfce comes with quite a few libraries that are targeted at desktop development,
libexo is targeted at application developement - in particular, developing applications for
the Xfce Desktop Environment.
</para>
<para>
The <application>exo</application> library depends on the following libraries:
<variablelist>
<varlistentry>
<term>GLib</term>
<listitem>
<para>
A general-purpose utility library, not specific to graphical user interfaces.
GLib provides many useful data types, macros, type conversions,
string utilities, file utilities, a main loop abstraction, and so on.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Pango</term>
<listitem>
<para>
Pango is a library for internationalized text handling. It centers
around the <link linkend="PangoLayout">PangoLayout</link> object, representing
a paragraph of text. Pango provides the engine for <link
linkend="GtkTextView">GtkTextView</link>, <link linkend="GtkLabel">GtkLabel</link>,
<link linkend="GtkEntry">GtkEntry</link>, and other widgets that display text.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ATK</term>
<listitem>
<para>
ATK is the Accessibility Toolkit. It provides a set of generic
interfaces allowing accessibility technologies to interact with a
graphical user interface. For example, a screen reader uses ATK to
discover the text in an interface and read it to blind users. GTK+
widgets have built-in support for accessibility using the ATK
framework.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GdkPixbuf</term>
<listitem>
<para>
This is a small library which allows you to create <link linkend="GdkPixbuf">GdkPixbuf</link>
("pixel buffer") objects from image data or image files. Use a <link linkend="GdkPixbuf">GdkPixbuf</link>
in combination with <link linkend="GtkImage">GtkImage</link> to display images.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GDK</term>
<listitem>
<para>
GDK is the abstraction layer that allows GTK+ to support multiple
windowing systems. GDK provides drawing and window system facilities
on X11, Windows, and the Linux framebuffer device.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GTK+</term>
<listitem>
<para>
The GTK+ library contains <firstterm>widgets</firstterm>, that is, GUI
components such as <link linkend="GtkButton">GtkButton</link> or
<link linkend="GtkTextView">GtkTextView</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>libxfce4util</term>
<listitem>
<para>
The Xfce utility library provides various helper functions and classes for
C programmers, that aren't directly related to GUI tasks.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</part>
<part id="exo-toolbars">
<title>Editable Toolbars</title>
<para>
These classes together provide a framework for editable
toolbars based on the GtkAction facility introduced with Gtk+
2.4. To create editable toolbars with exo, use the <link
linkend="ExoToolbarsModel">ExoToolbarsModel</link> class with the
<link linkend="ExoToolbarsView">ExoToolbarsView</link> widget. This
widget is designed around a <firstterm>Model/View/Controller</firstterm>
design and consists of three parts:
<simplelist>
<member>The toolbars widget (<structname>ExoToolbarsView</structname>)</member>
<member>The toolbars model (<structname>ExoToolbarsModel</structname>)</member>
<member>The toolbars editor widget (<structname>ExoToolbarsEditor</structname>)</member>
</simplelist>
The <link linkend="ExoToolbarsEditorDialog">ExoToolbarsEditorDialog</link> widget is provided
for convenience, it simply wraps the <link linkend="ExoToolbarsEditor">ExoToolbarsEditor</link>
component into a <structname>GtkDialog</structname>.
</para>
<xi:include href="xml/exo-toolbars-model.xml"/>
<xi:include href="xml/exo-toolbars-editor.xml"/>
<xi:include href="xml/exo-toolbars-editor-dialog.xml"/>
<xi:include href="xml/exo-toolbars-view.xml"/>
</part>
<part id="exo-widgets">
<title>Additional widgets</title>
<para>
This section describes the additional widgets provided by the <application>exo</application> library. The <link
linkend="ExoIconBar">ExoIconBar</link>, <link linkend="ExoIconView">ExoIconView</link> and <link linkend="ExoTreeView">ExoTreeView</link>
are views that display data from a <link linkend="GtkTreeModel">GtkTreeModel</link>, and can be seen as extensions to the basic widgets
in Gtk+. For example, both <link linkend="ExoIconView">ExoIconView</link> and <link linkend="ExoTreeView">ExoTreeView</link> offer support
for single-click mode, which is not provided by their Gtk+ counterparts.
</para>
<para>
The <link linkend="ExoIconChooserDialog">ExoIconChooserDialog</link> is a special widget, that presents a dialog to let the user select
an icon from the current icon theme or from an image file in the file system. You should use this dialog whenever you want the user to
select an icon, instead of just displaying a <link linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>.
</para>
<xi:include href="xml/exo-icon-bar.xml"/>
<xi:include href="xml/exo-icon-chooser-dialog.xml"/>
<xi:include href="xml/exo-icon-view.xml"/>
<xi:include href="xml/exo-tree-view.xml"/>
<xi:include href="xml/exo-wrap-table.xml"/>
</part>
<part id="exo-cell-renderers">
<title>Additional cell renderers</title>
<para>
Gtk+ contains various cell renderers that are intended to be used with <link linkend="GtkTreeView">GtkTreeView</link>
and <link linkend="GtkComboBox">GtkComboBox</link>, but are difficult to use with <link linkend="ExoIconView">ExoIconView</link>
(or even <link linkend="GtkIconView">GtkIconView</link>), mainly because the renderers do not follow the state of the view and
render appropriate indicators.
</para>
<para>
Because of these issues, the <link linkend="ExoCellRendererEllipsizedText">ExoCellRendererEllipsizedText</link> (the name of the
class is rather confusing) and the <link linkend="ExoCellRendererIcon">ExoCellRendererIcon</link> classes are provided, which
both include a <literal>follow-state</literal> property that tells whether the renderer should follow the state of the view and
draw appropriate indicators.
</para>
<para>
The <link linkend="ExoCellRendererIcon">ExoCellRendererIcon</link> class should also be preferred over the the <link
linkend="GtkCellRendererPixbuf">GtkCellRendererPixbuf</link> class when using named icons or image files because it uses a fixed
size for layouting and loads the icons only on-demand (utilizing the thumbnail database whenever possible).
</para>
<xi:include href="xml/exo-cell-renderer-ellipsized-text.xml"/>
<xi:include href="xml/exo-cell-renderer-icon.xml"/>
</part>
<part id="exo-jobs">
<title>Framework for threaded/asynchronous jobs</title>
<para>
<link linkend="ExoJob">ExoJob</link> provides a simple way to deal with threaded/asynchronous operations (called jobs here).
It can be used to wrap any kind of blocking function calls like file operations or web service communication. It can be
subclassed to add additional signals for progress information or password requests.
<link linkend="ExoSimpleJob">ExoSimpleJob</link> is useful in situations where you don't need additional signals. It takes
a <link linkend="ExoSimpleJobFunc">ExoSimpleJobFunc</link> callback and creates a job so one doesn't have to subclass
<link linkend="ExoJob">ExoJob</link> just to execute a single function asynchronously.
</para>
<xi:include href="xml/exo-job.xml"/>
<xi:include href="xml/exo-simple-job.xml"/>
</part>
<part id="exo-extensions">
<title>Extensions to existing frameworks</title>
<para>
This section describes extensions to existing frameworks provided by the <application>exo</application>, that range from additional
methods for certain classes to specialized functions dealing with <link linkend="GdkPixbuf">GdkPixbuf</link>s.
</para>
<xi:include href="xml/exo-gdk-pixbuf-extensions.xml"/>
<xi:include href="xml/exo-gobject-extensions.xml"/>
<xi:include href="xml/exo-gtk-extensions.xml"/>
</part>
<part id="exo-miscelleanous">
<title>Miscelleanous</title>
<xi:include href="xml/exo-config.xml"/>
<xi:include href="xml/exo-binding.xml"/>
<xi:include href="xml/exo-execute.xml"/>
<xi:include href="xml/exo-string.xml"/>
<xi:include href="xml/exo-utils.xml"/>
<xi:include href="xml/exo-xsession-client.xml"/>
</part>
<part id="exo-tools">
<title>Tools</title>
<para>
This part presents the tools which are shipped with the
<application>exo</application> library.
</para>
<xi:include href="exo-csource.xml"/>
</part>
<!--
<part id="exo-deprecated-widgets">
<title>Deprecated widgets</title>
</part>
-->
<chapter>
<title>Visual Index</title>
<xi:include href="visual-index.xml"/>
</chapter>
<index>
<title>Index</title>
</index>
</book>
<!--
vi:set ts=2 sw=2 et ai:
-->
|
