← Back to branch summary

~xubuntu-dev/libxfce4util/maverick

« back to all changes in this revision

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

  • Committer: Bazaar Package Importer
  • Author(s): Yves-Alexis Perez
  • Date: 2008-07-06 10:58:49 UTC
  • mfrom: (1.2.11 upstream)
  • mto: (2.2.1 squeeze)
  • mto: This revision was merged to the branch mainline in revision 18.
  • Revision ID: james.westby@ubuntu.com-20080706105849-zetal1iaztbjbj6x
Tags: 4.4.2-3
http://bugs.debian.org/489493
* debian/control:
  - fixed typo in short description.                          closes: #489493
  - removed Martin Loschwitz from Uploaders.
  - updated standards version to 3.8.0.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/xml/xfce-desktopentry.xml
 
1
<refentry id="libxfce4util-Desktop-entries">
 
2
<refmeta>
 
3
<refentrytitle role="top_of_page">XfceDesktopEntry</refentrytitle>
 
4
<manvolnum>3</manvolnum>
 
5
<refmiscinfo>LIBXFCE4UTIL Library</refmiscinfo>
 
6
</refmeta>
 
7
 
 
8
<refnamediv>
 
9
<refname>XfceDesktopEntry</refname>
 
10
<refpurpose>A GObject that wraps a .desktop file.</refpurpose>
 
11
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
 
12
</refnamediv>
 
13
 
 
14
<refsynopsisdiv role="synopsis">
 
15
<title role="synopsis.title">Synopsis</title>
 
16
<anchor id="XfceDesktopEntry"/>
 
17
<synopsis>
 
18
 
 
19
#include &lt;libxfce4util/libxfce4util.h&gt;
 
20
 
 
21
 
 
22
                    <link linkend="XfceDesktopEntry-struct">XfceDesktopEntry</link>;
 
23
<link linkend="XfceDesktopEntry">XfceDesktopEntry</link>*   <link linkend="xfce-desktop-entry-new">xfce_desktop_entry_new</link>              (const <link linkend="gchar">gchar</link> *file,
 
24
                                                         const <link linkend="gchar">gchar</link> **categories,
 
25
                                                         <link linkend="gint">gint</link> num_categories);
 
26
<link linkend="XfceDesktopEntry">XfceDesktopEntry</link>*   <link linkend="xfce-desktop-entry-new-from-data">xfce_desktop_entry_new_from_data</link>    (const <link linkend="gchar">gchar</link> *data,
 
27
                                                         const <link linkend="gchar">gchar</link> **categories,
 
28
                                                         <link linkend="gint">gint</link> num_categories);
 
29
const <link linkend="gchar">gchar</link>*        <link linkend="xfce-desktop-entry-get-file">xfce_desktop_entry_get_file</link>         (<link linkend="XfceDesktopEntry">XfceDesktopEntry</link> *desktop_entry);
 
30
<link linkend="gboolean">gboolean</link>            <link linkend="xfce-desktop-entry-get-string">xfce_desktop_entry_get_string</link>       (<link linkend="XfceDesktopEntry">XfceDesktopEntry</link> *desktop_entry,
 
31
                                                         const <link linkend="gchar">gchar</link> *key,
 
32
                                                         <link linkend="gboolean">gboolean</link> translated,
 
33
                                                         <link linkend="gchar">gchar</link> **value_return);
 
34
<link linkend="gboolean">gboolean</link>            <link linkend="xfce-desktop-entry-get-int">xfce_desktop_entry_get_int</link>          (<link linkend="XfceDesktopEntry">XfceDesktopEntry</link> *desktop_entry,
 
35
                                                         const <link linkend="gchar">gchar</link> *key,
 
36
                                                         <link linkend="gint">gint</link> *value_return);
 
37
<link linkend="gboolean">gboolean</link>            <link linkend="xfce-desktop-entry-has-translated-entry">xfce_desktop_entry_has_translated_entry</link>
 
38
                                                        (<link linkend="XfceDesktopEntry">XfceDesktopEntry</link> *desktop_entry,
 
39
                                                         const <link linkend="gchar">gchar</link> *key);
 
40
 
 
41
 
 
42
</synopsis>
 
43
</refsynopsisdiv>
 
44
 
 
45
<refsect1 role="object_hierarchy">
 
46
<title role="object_hierarchy.title">Object Hierarchy</title>
 
47
<synopsis>
 
48
 
 
49
  <link linkend="GObject">GObject</link>
 
50
   +----XfceDesktopEntry
 
51
</synopsis>
 
52
 
 
53
</refsect1>
 
54
 
 
55
 
 
56
 
 
57
 
 
58
 
 
59
 
 
60
 
 
61
 
 
62
<refsect1 role="desc">
 
63
<title role="desc.title">Description</title>
 
64
<para>
 
65
XfceDesktopEntry is a wrapper for a so-called desktop entry file. The
 
66
desktop entry format is defined on <ulink
 
67
url="http://www.freedesktop.org/">Freedesktop.org</ulink>.
 
68
</para>
 
69
</refsect1>
 
70
 
 
71
<refsect1 role="details">
 
72
<title role="details.title">Details</title>
 
73
<refsect2>
 
74
<title><anchor id="XfceDesktopEntry-struct" role="struct"/>XfceDesktopEntry</title>
 
75
<indexterm><primary>XfceDesktopEntry</primary></indexterm><programlisting>typedef struct _XfceDesktopEntry XfceDesktopEntry;</programlisting>
 
76
<para>
 
77
All the fields in the XfceDesktopEntry structure are private to the
 
78
XfceDesktopEntry implementation and should never be accessed directly.
 
79
Instead, you should use the functions listed below.
 
80
</para></refsect2>
 
81
<refsect2>
 
82
<title><anchor id="xfce-desktop-entry-new" role="function" condition="since:4.2"/>xfce_desktop_entry_new ()</title>
 
83
<indexterm role="4.2"><primary>xfce_desktop_entry_new</primary></indexterm><programlisting><link linkend="XfceDesktopEntry">XfceDesktopEntry</link>*   xfce_desktop_entry_new              (const <link linkend="gchar">gchar</link> *file,
 
84
                                                         const <link linkend="gchar">gchar</link> **categories,
 
85
                                                         <link linkend="gint">gint</link> num_categories);</programlisting>
 
86
<para>
 
87
Create a new <link linkend="XfceDesktopEntry"><type>XfceDesktopEntry</type></link> object from a desktop entry stored in a file on disk.
 
88
</para>
 
89
<para>
 
90
The caller is responsible to free the returned object (if any) using
 
91
<link linkend="g-object-unref"><function>g_object_unref()</function></link> when no longer needed.</para>
 
92
<para>
 
93
 
 
94
</para><variablelist role="params">
 
95
<varlistentry><term><parameter>file</parameter>&nbsp;:</term>
 
96
<listitem><simpara> full path to the desktop entry file to use.
 
97
</simpara></listitem></varlistentry>
 
98
<varlistentry><term><parameter>categories</parameter>&nbsp;:</term>
 
99
<listitem><simpara> array of categories, not necessarily NULL terminated.
 
100
</simpara></listitem></varlistentry>
 
101
<varlistentry><term><parameter>num_categories</parameter>&nbsp;:</term>
 
102
<listitem><simpara> number of items in <parameter>categories</parameter>.
 
103
</simpara></listitem></varlistentry>
 
104
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> newly created <link linkend="XfceDesktopEntry"><type>XfceDesktopEntry</type></link> or NULL if something goes wrong.
 
105
 
 
106
</simpara></listitem></varlistentry>
 
107
</variablelist><para role="since">Since  4.2
 
108
</para></refsect2>
 
109
<refsect2>
 
110
<title><anchor id="xfce-desktop-entry-new-from-data" role="function" condition="since:4.2"/>xfce_desktop_entry_new_from_data ()</title>
 
111
<indexterm role="4.2"><primary>xfce_desktop_entry_new_from_data</primary></indexterm><programlisting><link linkend="XfceDesktopEntry">XfceDesktopEntry</link>*   xfce_desktop_entry_new_from_data    (const <link linkend="gchar">gchar</link> *data,
 
112
                                                         const <link linkend="gchar">gchar</link> **categories,
 
113
                                                         <link linkend="gint">gint</link> num_categories);</programlisting>
 
114
<para>
 
115
Create a new <link linkend="XfceDesktopEntry"><type>XfceDesktopEntry</type></link> object from a desktop entry stored in memory.
 
116
</para>
 
117
<para>
 
118
The caller is responsible to free the returned object (if any) using
 
119
<link linkend="g-object-unref"><function>g_object_unref()</function></link> when no longer needed.</para>
 
120
<para>
 
121
 
 
122
</para><variablelist role="params">
 
123
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
124
<listitem><simpara> pointer to the desktop entry inline data.
 
125
</simpara></listitem></varlistentry>
 
126
<varlistentry><term><parameter>categories</parameter>&nbsp;:</term>
 
127
<listitem><simpara> array of categories, not necessarily NULL terminated.
 
128
</simpara></listitem></varlistentry>
 
129
<varlistentry><term><parameter>num_categories</parameter>&nbsp;:</term>
 
130
<listitem><simpara> number of items in <parameter>categories</parameter>.
 
131
</simpara></listitem></varlistentry>
 
132
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> newly created <link linkend="XfceDesktopEntry"><type>XfceDesktopEntry</type></link> or NULL if something goes wrong.
 
133
 
 
134
</simpara></listitem></varlistentry>
 
135
</variablelist><para role="since">Since  4.2
 
136
</para></refsect2>
 
137
<refsect2>
 
138
<title><anchor id="xfce-desktop-entry-get-file" role="function" condition="since:4.2"/>xfce_desktop_entry_get_file ()</title>
 
139
<indexterm role="4.2"><primary>xfce_desktop_entry_get_file</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        xfce_desktop_entry_get_file         (<link linkend="XfceDesktopEntry">XfceDesktopEntry</link> *desktop_entry);</programlisting>
 
140
<para>
 
141
Obtain the path to the desktop entry file associated with the
 
142
<link linkend="XfceDesktopEntry"><type>XfceDesktopEntry</type></link>.</para>
 
143
<para>
 
144
 
 
145
</para><variablelist role="params">
 
146
<varlistentry><term><parameter>desktop_entry</parameter>&nbsp;:</term>
 
147
<listitem><simpara> an <link linkend="XfceDesktopEntry"><type>XfceDesktopEntry</type></link>.
 
148
</simpara></listitem></varlistentry>
 
149
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> path of the desktop entry file used to create <parameter>desktop_entry</parameter>. The
 
150
              return value should be considered read-only and must not be freed
 
151
              by the caller.
 
152
</simpara></listitem></varlistentry>
 
153
</variablelist><para role="since">Since  4.2
 
154
</para></refsect2>
 
155
<refsect2>
 
156
<title><anchor id="xfce-desktop-entry-get-string" role="function" condition="since:4.2"/>xfce_desktop_entry_get_string ()</title>
 
157
<indexterm role="4.2"><primary>xfce_desktop_entry_get_string</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            xfce_desktop_entry_get_string       (<link linkend="XfceDesktopEntry">XfceDesktopEntry</link> *desktop_entry,
 
158
                                                         const <link linkend="gchar">gchar</link> *key,
 
159
                                                         <link linkend="gboolean">gboolean</link> translated,
 
160
                                                         <link linkend="gchar">gchar</link> **value_return);</programlisting>
 
161
<para>
 
162
Finds the value for <parameter>key</parameter>. When <parameter>translated</parameter> is TRUE the function will use
 
163
the translated value (using the current locale settings) if available or
 
164
the untranslated value if no translation can be found.</para>
 
165
<para>
 
166
 
 
167
</para><variablelist role="params">
 
168
<varlistentry><term><parameter>desktop_entry</parameter>&nbsp;:</term>
 
169
<listitem><simpara> an <link linkend="XfceDesktopEntry"><type>XfceDesktopEntry</type></link>
 
170
</simpara></listitem></varlistentry>
 
171
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
172
<listitem><simpara> category to find value for.
 
173
</simpara></listitem></varlistentry>
 
174
<varlistentry><term><parameter>translated</parameter>&nbsp;:</term>
 
175
<listitem><simpara> set to TRUE if the translated value is preferred.
 
176
</simpara></listitem></varlistentry>
 
177
<varlistentry><term><parameter>value_return</parameter>&nbsp;:</term>
 
178
<listitem><simpara> location for the value, which will be newly allocated.
 
179
</simpara></listitem></varlistentry>
 
180
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> TRUE on success, FALSE on failure. <parameter>value_return</parameter> must be freed.
 
181
 
 
182
</simpara></listitem></varlistentry>
 
183
</variablelist><para role="since">Since  4.2
 
184
</para></refsect2>
 
185
<refsect2>
 
186
<title><anchor id="xfce-desktop-entry-get-int" role="function" condition="since:4.2"/>xfce_desktop_entry_get_int ()</title>
 
187
<indexterm role="4.2"><primary>xfce_desktop_entry_get_int</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            xfce_desktop_entry_get_int          (<link linkend="XfceDesktopEntry">XfceDesktopEntry</link> *desktop_entry,
 
188
                                                         const <link linkend="gchar">gchar</link> *key,
 
189
                                                         <link linkend="gint">gint</link> *value_return);</programlisting>
 
190
<para>
 
191
Gets a value from <parameter>desktop_entry</parameter> as integer. Therefore finds the value for
 
192
<parameter>key</parameter> and returns its integer representation.</para>
 
193
<para>
 
194
 
 
195
</para><variablelist role="params">
 
196
<varlistentry><term><parameter>desktop_entry</parameter>&nbsp;:</term>
 
197
<listitem><simpara> an <link linkend="XfceDesktopEntry"><type>XfceDesktopEntry</type></link>.
 
198
</simpara></listitem></varlistentry>
 
199
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
200
<listitem><simpara> category to find value for.
 
201
</simpara></listitem></varlistentry>
 
202
<varlistentry><term><parameter>value_return</parameter>&nbsp;:</term>
 
203
<listitem><simpara> location for the value.
 
204
</simpara></listitem></varlistentry>
 
205
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> TRUE on success, FALSE on failure.
 
206
 
 
207
</simpara></listitem></varlistentry>
 
208
</variablelist><para role="since">Since  4.2
 
209
</para></refsect2>
 
210
<refsect2>
 
211
<title><anchor id="xfce-desktop-entry-has-translated-entry" role="function" condition="since:4.3"/>xfce_desktop_entry_has_translated_entry ()</title>
 
212
<indexterm role="4.3"><primary>xfce_desktop_entry_has_translated_entry</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            xfce_desktop_entry_has_translated_entry
 
213
                                                        (<link linkend="XfceDesktopEntry">XfceDesktopEntry</link> *desktop_entry,
 
214
                                                         const <link linkend="gchar">gchar</link> *key);</programlisting>
 
215
<para>
 
216
Checks to see if <parameter>desktop_entry</parameter> has a value for <parameter>key</parameter> translated into
 
217
the current locale.</para>
 
218
<para>
 
219
 
 
220
</para><variablelist role="params">
 
221
<varlistentry><term><parameter>desktop_entry</parameter>&nbsp;:</term>
 
222
<listitem><simpara> an <link linkend="XfceDesktopEntry"><type>XfceDesktopEntry</type></link>.
 
223
</simpara></listitem></varlistentry>
 
224
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
225
<listitem><simpara> the key to check.
 
226
</simpara></listitem></varlistentry>
 
227
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if there is a translated key, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
 
228
 
 
229
</simpara></listitem></varlistentry>
 
230
</variablelist><para role="since">Since  4.3
 
231
</para></refsect2>
 
232
 
 
233
</refsect1>
 
234
 
 
235
 
 
236
 
 
237
 
 
238
</refentry>