← Back to branch summary

~xubuntu-dev/libxfce4util/maverick

« back to all changes in this revision

Viewing changes to docs/xml/xfce-resource.xml

  • Committer: Lionel Le Folgoc
  • Date: 2010-05-23 18:00:15 UTC
  • Revision ID: mrpouit@ubuntu.com-20100523180015-0ddtdmn4xstvm2y8
* Merge from debian testing, remaining Ubuntu changes:
  - debian/control: use our Vcs-* fields.
  - debian/patches:
    + xubuntu_desktop-x-ubuntu-gettext.patch: display translations for
      "X-Ubuntu-Gettext-Domain" desktop files
    + series:
      . don't apply 01_add-desktop-base-in-config-dirs.patch
      . refreshed.
* New upstream release.
* debian/control:
  - bump standards version to 3.8.4.
  - add build-dep on intltool. 
  - drop quilt and chrpath build-deps.
  - bump debhelper build-deps for overrides.
* debian/rules:
  - switch to debhelper 7.
* switch to 3.0 (quilt) source format.
* debian/watch edited to track Xfce archive reorganisation.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/xml/xfce-resource.xml
1
 
<refentry id="libxfce4util-Resource-lookup-functions">
2
 
<refmeta>
3
 
<refentrytitle role="top_of_page" id="libxfce4util-Resource-lookup-functions.top_of_page">Resource lookup functions</refentrytitle>
4
 
<manvolnum>3</manvolnum>
5
 
<refmiscinfo>LIBXFCE4UTIL Library</refmiscinfo>
6
 
</refmeta>
7
 
 
8
 
<refnamediv>
9
 
<refname>Resource lookup functions</refname>
10
 
<refpurpose></refpurpose>
11
 
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
12
 
</refnamediv>
13
 
 
14
 
<refsynopsisdiv id="libxfce4util-Resource-lookup-functions.synopsis" role="synopsis">
15
 
<title role="synopsis.title">Synopsis</title>
16
 
 
17
 
<synopsis>
18
 
 
19
 
#include &lt;libxfce4util/libxfce4util.h&gt;
20
 
 
21
 
enum                <link linkend="XfceResourceType">XfceResourceType</link>;
22
 
<link linkend="gboolean">gboolean</link>            (<link linkend="XfceMatchFunc">*XfceMatchFunc</link>)                    (const <link linkend="gchar">gchar</link> *basedir,
23
 
                                                         const <link linkend="gchar">gchar</link> *relpath,
24
 
                                                         <link linkend="gpointer">gpointer</link> user_data);
25
 
<link linkend="gchar">gchar</link>**             <link linkend="xfce-resource-dirs">xfce_resource_dirs</link>                  (<link linkend="XfceResourceType">XfceResourceType</link> type);
26
 
<link linkend="gchar">gchar</link>*              <link linkend="xfce-resource-lookup">xfce_resource_lookup</link>                (<link linkend="XfceResourceType">XfceResourceType</link> type,
27
 
                                                         const <link linkend="gchar">gchar</link> *filename);
28
 
<link linkend="gchar">gchar</link>**             <link linkend="xfce-resource-lookup-all">xfce_resource_lookup_all</link>            (<link linkend="XfceResourceType">XfceResourceType</link> type,
29
 
                                                         const <link linkend="gchar">gchar</link> *filename);
30
 
<link linkend="gchar">gchar</link>**             <link linkend="xfce-resource-match">xfce_resource_match</link>                 (<link linkend="XfceResourceType">XfceResourceType</link> type,
31
 
                                                         const <link linkend="gchar">gchar</link> *pattern,
32
 
                                                         <link linkend="gboolean">gboolean</link> unique);
33
 
<link linkend="gchar">gchar</link>**             <link linkend="xfce-resource-match-custom">xfce_resource_match_custom</link>          (<link linkend="XfceResourceType">XfceResourceType</link> type,
34
 
                                                         <link linkend="gboolean">gboolean</link> unique,
35
 
                                                         <link linkend="XfceMatchFunc">XfceMatchFunc</link> func,
36
 
                                                         <link linkend="gpointer">gpointer</link> user_data);
37
 
<link linkend="void">void</link>                <link linkend="xfce-resource-push-path">xfce_resource_push_path</link>             (<link linkend="XfceResourceType">XfceResourceType</link> type,
38
 
                                                         const <link linkend="gchar">gchar</link> *path);
39
 
<link linkend="void">void</link>                <link linkend="xfce-resource-pop-path">xfce_resource_pop_path</link>              (<link linkend="XfceResourceType">XfceResourceType</link> type);
40
 
<link linkend="gchar">gchar</link>*              <link linkend="xfce-resource-save-location">xfce_resource_save_location</link>         (<link linkend="XfceResourceType">XfceResourceType</link> type,
41
 
                                                         const <link linkend="gchar">gchar</link> *relpath,
42
 
                                                         <link linkend="gboolean">gboolean</link> create);
43
 
</synopsis>
44
 
</refsynopsisdiv>
45
 
 
46
 
 
47
 
 
48
 
 
49
 
 
50
 
 
51
 
 
52
 
 
53
 
 
54
 
<refsect1 id="libxfce4util-Resource-lookup-functions.description" role="desc">
55
 
<title role="desc.title">Description</title>
56
 
<para>
57
 
 
58
 
</para>
59
 
</refsect1>
60
 
 
61
 
<refsect1 id="libxfce4util-Resource-lookup-functions.details" role="details">
62
 
<title role="details.title">Details</title>
63
 
<refsect2 id="XfceResourceType" role="enum">
64
 
<title>enum XfceResourceType</title>
65
 
<indexterm zone="XfceResourceType"><primary>XfceResourceType</primary></indexterm><programlisting>typedef enum /*&lt; prefix=XFCE_RESOURCE_ &gt;*/
66
 
{
67
 
  XFCE_RESOURCE_DATA   = 0,
68
 
  XFCE_RESOURCE_CONFIG = 1,
69
 
  XFCE_RESOURCE_CACHE  = 2,
70
 
  XFCE_RESOURCE_ICONS  = 3,
71
 
  XFCE_RESOURCE_THEMES = 4,
72
 
} XfceResourceType;
73
 
</programlisting>
74
 
<para>
75
 
</para>
76
 
<para>
77
 
 
78
 
</para><variablelist role="enum">
79
 
</variablelist></refsect2>
80
 
<refsect2 id="XfceMatchFunc" role="function">
81
 
<title>XfceMatchFunc ()</title>
82
 
<indexterm zone="XfceMatchFunc"><primary>XfceMatchFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*XfceMatchFunc)                    (const <link linkend="gchar">gchar</link> *basedir,
83
 
                                                         const <link linkend="gchar">gchar</link> *relpath,
84
 
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
85
 
<para>
86
 
Return value :</para>
87
 
<para>
88
 
 
89
 
</para><variablelist role="params">
90
 
<varlistentry><term><parameter>basedir</parameter>&nbsp;:</term>
91
 
<listitem><simpara>
92
 
</simpara></listitem></varlistentry>
93
 
<varlistentry><term><parameter>relpath</parameter>&nbsp;:</term>
94
 
<listitem><simpara>
95
 
</simpara></listitem></varlistentry>
96
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
97
 
<listitem><simpara> additional user data passed to <link linkend="xfce-resource-match-custom"><function>xfce_resource_match_custom()</function></link>.
98
 
</simpara></listitem></varlistentry>
99
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>
100
 
 
101
 
 
102
 
</simpara></listitem></varlistentry>
103
 
</variablelist></refsect2>
104
 
<refsect2 id="xfce-resource-dirs" role="function" condition="since:4.2">
105
 
<title>xfce_resource_dirs ()</title>
106
 
<indexterm zone="xfce-resource-dirs" role="4.2"><primary>xfce_resource_dirs</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             xfce_resource_dirs                  (<link linkend="XfceResourceType">XfceResourceType</link> type);</programlisting>
107
 
<para>
108
 
Queries the list of possible directories for the specified <parameter>type</parameter>. The
109
 
first element of the list is always the save location for <parameter>type</parameter>. None
110
 
of the directories returned in the list are garantied to exist.
111
 
</para>
112
 
<para>
113
 
This function should be rarely used. You should consider using
114
 
<link linkend="xfce-resource-lookup"><function>xfce_resource_lookup()</function></link>, <link linkend="xfce-resource-lookup-dirs"><function>xfce_resource_lookup_dirs()</function></link> or
115
 
<link linkend="xfce-resource-match"><function>xfce_resource_match()</function></link> instead.
116
 
</para>
117
 
<para>
118
 
The returned list must be freed using <link linkend="g-strfreev"><function>g_strfreev()</function></link>.</para>
119
 
<para>
120
 
 
121
 
</para><variablelist role="params">
122
 
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
123
 
<listitem><simpara> type of the resource.
124
 
</simpara></listitem></varlistentry>
125
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> list of possible directories for <parameter>type</parameter>.
126
 
 
127
 
</simpara></listitem></varlistentry>
128
 
</variablelist><para role="since">Since  4.2
129
 
</para></refsect2>
130
 
<refsect2 id="xfce-resource-lookup" role="function" condition="since:4.2">
131
 
<title>xfce_resource_lookup ()</title>
132
 
<indexterm zone="xfce-resource-lookup" role="4.2"><primary>xfce_resource_lookup</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              xfce_resource_lookup                (<link linkend="XfceResourceType">XfceResourceType</link> type,
133
 
                                                         const <link linkend="gchar">gchar</link> *filename);</programlisting>
134
 
<para>
135
 
Looks for a resource of the specified <parameter>type</parameter> whose relative path matches
136
 
<parameter>filename</parameter>. <parameter>filename</parameter> can either reference a regular file, in which case
137
 
it must not end with a slash character ('/'), or a directory, when
138
 
<parameter>filename</parameter> contains a trailing slash character ('/').
139
 
</para>
140
 
<para>
141
 
The caller is responsible to free the returned string using <link linkend="g-free"><function>g_free()</function></link>
142
 
when no longer needed.</para>
143
 
<para>
144
 
 
145
 
</para><variablelist role="params">
146
 
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
147
 
<listitem><simpara> type of resource to lookup.
148
 
</simpara></listitem></varlistentry>
149
 
<varlistentry><term><parameter>filename</parameter>&nbsp;:</term>
150
 
<listitem><simpara> relative filename of the resource, e.g. "xfwm4/xfwmrc".
151
 
</simpara></listitem></varlistentry>
152
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the absolute path to the first file or directory in the
153
 
              search path, that matches <parameter>filename</parameter> or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if no such
154
 
              file or directory could be found.
155
 
 
156
 
</simpara></listitem></varlistentry>
157
 
</variablelist><para role="since">Since  4.2
158
 
</para></refsect2>
159
 
<refsect2 id="xfce-resource-lookup-all" role="function" condition="since:4.2">
160
 
<title>xfce_resource_lookup_all ()</title>
161
 
<indexterm zone="xfce-resource-lookup-all" role="4.2"><primary>xfce_resource_lookup_all</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             xfce_resource_lookup_all            (<link linkend="XfceResourceType">XfceResourceType</link> type,
162
 
                                                         const <link linkend="gchar">gchar</link> *filename);</programlisting>
163
 
<para>
164
 
Similar to <link linkend="xfce-resource-lookup"><function>xfce_resource_lookup()</function></link>, but returns all resource of the specified <parameter>type</parameter>,
165
 
that whose name is <parameter>filename</parameter>.
166
 
</para>
167
 
<para>
168
 
The caller is responsible to free the returned string array using <link linkend="g-strfreev"><function>g_strfreev()</function></link>
169
 
when no longer needed.</para>
170
 
<para>
171
 
 
172
 
</para><variablelist role="params">
173
 
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
174
 
<listitem><simpara> type of the resource to lookup.
175
 
</simpara></listitem></varlistentry>
176
 
<varlistentry><term><parameter>filename</parameter>&nbsp;:</term>
177
 
<listitem><simpara> relative file path. If <parameter>filename</parameter> contains a trailing slash character
178
 
            it is taken to reference a directory, else it is taken to reference
179
 
            a file.
180
 
</simpara></listitem></varlistentry>
181
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>
182
 
 
183
 
</simpara></listitem></varlistentry>
184
 
</variablelist><para role="since">Since  4.2
185
 
</para></refsect2>
186
 
<refsect2 id="xfce-resource-match" role="function" condition="since:4.2">
187
 
<title>xfce_resource_match ()</title>
188
 
<indexterm zone="xfce-resource-match" role="4.2"><primary>xfce_resource_match</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             xfce_resource_match                 (<link linkend="XfceResourceType">XfceResourceType</link> type,
189
 
                                                         const <link linkend="gchar">gchar</link> *pattern,
190
 
                                                         <link linkend="gboolean">gboolean</link> unique);</programlisting>
191
 
<para>
192
 
Tries to find all resources with the specified <parameter>type</parameter>. The function will
193
 
look into all specified directories and return all filenames in these
194
 
directories. The returned filenames are given relative the base directories
195
 
specified by <parameter>type</parameter>.
196
 
</para>
197
 
<para>
198
 
If <parameter>pattern</parameter> contains a trailing slash, <link linkend="xfce-resource-match"><type>xfce_resource_match</type></link> looks only for
199
 
directories that match <parameter>pattern</parameter>, else it'll only look for regular files. In
200
 
case you are looking for directories, the returned entries will contain a
201
 
trailing slash as well, so you can easily use them with other resource
202
 
functions like <link linkend="xfce-resource-lookup"><type>xfce_resource_lookup</type></link> or <link linkend="xfce-resource-save-location"><type>xfce_resource_save_location</type></link>.
203
 
</para>
204
 
<para>
205
 
Example: xfce_resource_match (XFCE_RESOURCE_CONFIG, "foo/bar*") will probably
206
 
return ("foo/bar", "foo/barbaz", ...).</para>
207
 
<para>
208
 
 
209
 
</para><variablelist role="params">
210
 
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
211
 
<listitem><simpara> type of the resource to locate directories for.
212
 
</simpara></listitem></varlistentry>
213
 
<varlistentry><term><parameter>pattern</parameter>&nbsp;:</term>
214
 
<listitem><simpara> only accept filenames that fit to the pattern. The pattern
215
 
             needs to be a valid GPattern.
216
 
</simpara></listitem></varlistentry>
217
 
<varlistentry><term><parameter>unique</parameter>&nbsp;:</term>
218
 
<listitem><simpara> if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, only return items which have unique suffixes.
219
 
</simpara></listitem></varlistentry>
220
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> string array of all the relative paths whose names matches the
221
 
              given <parameter>pattern</parameter>. The return value has to be freed using
222
 
              <link linkend="g-strfreev"><function>g_strfreev()</function></link> when no longer needed.
223
 
 
224
 
</simpara></listitem></varlistentry>
225
 
</variablelist><para role="since">Since  4.2
226
 
</para></refsect2>
227
 
<refsect2 id="xfce-resource-match-custom" role="function" condition="since:4.2">
228
 
<title>xfce_resource_match_custom ()</title>
229
 
<indexterm zone="xfce-resource-match-custom" role="4.2"><primary>xfce_resource_match_custom</primary></indexterm><programlisting><link linkend="gchar">gchar</link>**             xfce_resource_match_custom          (<link linkend="XfceResourceType">XfceResourceType</link> type,
230
 
                                                         <link linkend="gboolean">gboolean</link> unique,
231
 
                                                         <link linkend="XfceMatchFunc">XfceMatchFunc</link> func,
232
 
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
233
 
<para>
234
 
Yet to be implemented!
235
 
</para>
236
 
<para>
237
 
The caller is responsible to free the returned string array using <link linkend="g-strfreev"><function>g_strfreev()</function></link>
238
 
when no longer needed.</para>
239
 
<para>
240
 
 
241
 
</para><variablelist role="params">
242
 
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
243
 
<listitem><simpara> type of the resource to locate directories for.
244
 
</simpara></listitem></varlistentry>
245
 
<varlistentry><term><parameter>unique</parameter>&nbsp;:</term>
246
 
<listitem><simpara> if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, only return items which have unique suffixes.
247
 
</simpara></listitem></varlistentry>
248
 
<varlistentry><term><parameter>func</parameter>&nbsp;:</term>
249
 
<listitem><simpara>
250
 
</simpara></listitem></varlistentry>
251
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
252
 
<listitem><simpara>
253
 
</simpara></listitem></varlistentry>
254
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>
255
 
 
256
 
</simpara></listitem></varlistentry>
257
 
</variablelist><para role="since">Since  4.2
258
 
</para></refsect2>
259
 
<refsect2 id="xfce-resource-push-path" role="function" condition="since:4.2">
260
 
<title>xfce_resource_push_path ()</title>
261
 
<indexterm zone="xfce-resource-push-path" role="4.2"><primary>xfce_resource_push_path</primary></indexterm><programlisting><link linkend="void">void</link>                xfce_resource_push_path             (<link linkend="XfceResourceType">XfceResourceType</link> type,
262
 
                                                         const <link linkend="gchar">gchar</link> *path);</programlisting>
263
 
<para>
264
 
Appends <parameter>path</parameter> to the search path list for <parameter>type</parameter>. This function was
265
 
written primary for use within modules in larger applications, for example
266
 
MCS plugins.
267
 
</para>
268
 
<para>
269
 
For example, if you need to add a specific path to the search path list
270
 
in your MCS, you should call <link linkend="xfce-resource-push-path"><function>xfce_resource_push_path()</function></link> prior to calling
271
 
one of the resource search functions and call <link linkend="xfce-resource-pop-path"><function>xfce_resource_pop_path()</function></link>
272
 
right afterwards.</para>
273
 
<para>
274
 
 
275
 
</para><variablelist role="params">
276
 
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
277
 
<listitem><simpara> type of the resource which search list should be expanded.
278
 
</simpara></listitem></varlistentry>
279
 
<varlistentry><term><parameter>path</parameter>&nbsp;:</term>
280
 
<listitem><simpara> search path to add.
281
 
</simpara></listitem></varlistentry>
282
 
</variablelist><para role="since">Since  4.2
283
 
</para></refsect2>
284
 
<refsect2 id="xfce-resource-pop-path" role="function" condition="since:4.2">
285
 
<title>xfce_resource_pop_path ()</title>
286
 
<indexterm zone="xfce-resource-pop-path" role="4.2"><primary>xfce_resource_pop_path</primary></indexterm><programlisting><link linkend="void">void</link>                xfce_resource_pop_path              (<link linkend="XfceResourceType">XfceResourceType</link> type);</programlisting>
287
 
<para>
288
 
Undoes the effect of the latest call to <link linkend="xfce-resource-push-path"><function>xfce_resource_push_path()</function></link>. You
289
 
should take special care to call <link linkend="xfce-resource-pop-path"><function>xfce_resource_pop_path()</function></link> exactly same
290
 
times as <link linkend="xfce-resource-push-path"><function>xfce_resource_push_path()</function></link>, everything else might result in
291
 
unwanted and maybe even undefined behaviour. You have been warned!</para>
292
 
<para>
293
 
 
294
 
</para><variablelist role="params">
295
 
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
296
 
<listitem><simpara> type of the resource which search list should be shrinked.
297
 
</simpara></listitem></varlistentry>
298
 
</variablelist><para role="since">Since  4.2
299
 
</para></refsect2>
300
 
<refsect2 id="xfce-resource-save-location" role="function" condition="since:4.2">
301
 
<title>xfce_resource_save_location ()</title>
302
 
<indexterm zone="xfce-resource-save-location" role="4.2"><primary>xfce_resource_save_location</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              xfce_resource_save_location         (<link linkend="XfceResourceType">XfceResourceType</link> type,
303
 
                                                         const <link linkend="gchar">gchar</link> *relpath,
304
 
                                                         <link linkend="gboolean">gboolean</link> create);</programlisting>
305
 
<para>
306
 
If <parameter>relpath</parameter> contains a trailing slash ('/') character, <link linkend="xfce-resource-save-location"><function>xfce_resource_save_location()</function></link>
307
 
finds the directory to save files into for the given type in the user's
308
 
home directory. All directories needed (including those given by
309
 
<parameter>relpath</parameter>) will be created on demand if <parameter>create</parameter> if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>.
310
 
</para>
311
 
<para>
312
 
If <parameter>relpath</parameter> does not end with a slash ('/') character, it is taken to be
313
 
the name of a file to return the save location for. All the directories
314
 
needed will be created on demand if <parameter>create</parameter> is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>.
315
 
</para>
316
 
<para>
317
 
Specifying <link linkend="NULL:CAPS"><literal>NULL</literal></link> or the empty string for <parameter>relpath</parameter> allows you to discover
318
 
the base path for saving files of the specified <parameter>type</parameter>, though normally
319
 
you should not need this.</para>
320
 
<para>
321
 
 
322
 
</para><variablelist role="params">
323
 
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
324
 
<listitem><simpara> type of location to return.
325
 
</simpara></listitem></varlistentry>
326
 
<varlistentry><term><parameter>relpath</parameter>&nbsp;:</term>
327
 
<listitem><simpara> relative path of the resource.
328
 
</simpara></listitem></varlistentry>
329
 
<varlistentry><term><parameter>create</parameter>&nbsp;:</term>
330
 
<listitem><simpara> whether to create missing directory.
331
 
</simpara></listitem></varlistentry>
332
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the path where resources of the specified <parameter>type</parameter> should be
333
 
              saved or <link linkend="NULL:CAPS"><literal>NULL</literal></link> on error. The returned string should be freed
334
 
              when no longer needed.
335
 
 
336
 
</simpara></listitem></varlistentry>
337
 
</variablelist><para role="since">Since  4.2
338
 
</para></refsect2>
339
 
 
340
 
</refsect1>
341
 
 
342
 
 
343
 
 
344
 
 
345
 
</refentry>