glib2.0_2.20.1
[mer:glib2_0.git] / docs / reference / gio / xml / gdesktopappinfo.xml
1 <?xml version="1.0"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4 <!ENTITY version SYSTEM "version.xml">
5 ]>
6 <refentry id="gio-Desktop-file-based-GAppInfo">
7 <refmeta>
8 <refentrytitle role="top_of_page" id="gio-Desktop-file-based-GAppInfo.top_of_page">Desktop file based GAppInfo</refentrytitle>
9 <manvolnum>3</manvolnum>
10 <refmiscinfo>GIO Library</refmiscinfo>
11 </refmeta>
12
13 <refnamediv>
14 <refname>Desktop file based GAppInfo</refname>
15 <refpurpose>Application information from desktop files</refpurpose>
16 </refnamediv>
17
18 <refsynopsisdiv id="gio-Desktop-file-based-GAppInfo.synopsis" role="synopsis">
19 <title role="synopsis.title">Synopsis</title>
20 <anchor id="GDesktopAppInfo"/><anchor id="GDesktopAppInfoLookup"/>
21 <synopsis>
22
23 #include &lt;gio/gdesktopappinfo.h&gt;
24
25                     <link linkend="GDesktopAppInfo-struct">GDesktopAppInfo</link>;
26 <link linkend="GDesktopAppInfo">GDesktopAppInfo</link> *   <link linkend="g-desktop-app-info-new-from-filename">g_desktop_app_info_new_from_filename</link>
27                                                         (const <link linkend="char">char</link> *filename);
28 <link linkend="GDesktopAppInfo">GDesktopAppInfo</link> *   <link linkend="g-desktop-app-info-new-from-keyfile">g_desktop_app_info_new_from_keyfile</link> (<link linkend="GKeyFile">GKeyFile</link> *key_file);
29 <link linkend="GDesktopAppInfo">GDesktopAppInfo</link> *   <link linkend="g-desktop-app-info-new">g_desktop_app_info_new</link>              (const <link linkend="char">char</link> *desktop_id);
30 <link linkend="gboolean">gboolean</link>            <link linkend="g-desktop-app-info-get-is-hidden">g_desktop_app_info_get_is_hidden</link>    (<link linkend="GDesktopAppInfo">GDesktopAppInfo</link> *info);
31 <link linkend="void">void</link>                <link linkend="g-desktop-app-info-set-desktop-env">g_desktop_app_info_set_desktop_env</link>  (const <link linkend="char">char</link> *desktop_env);
32                     <link linkend="GDesktopAppInfoLookup-struct">GDesktopAppInfoLookup</link>;
33 #define             <link linkend="G-DESKTOP-APP-INFO-LOOKUP-EXTENSION-POINT-NAME--CAPS">G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</link>
34 <link linkend="GAppInfo">GAppInfo</link> *          <link linkend="g-desktop-app-info-lookup-get-default-for-uri-scheme">g_desktop_app_info_lookup_get_default_for_uri_scheme</link>
35                                                         (<link linkend="GDesktopAppInfoLookup">GDesktopAppInfoLookup</link> *lookup,
36                                                          const <link linkend="char">char</link> *uri_scheme);
37 </synopsis>
38 </refsynopsisdiv>
39
40 <refsect1 id="gio-Desktop-file-based-GAppInfo.object-hierarchy" role="object_hierarchy">
41 <title role="object_hierarchy.title">Object Hierarchy</title>
42 <synopsis>
43   <link linkend="GObject">GObject</link>
44    +----GDesktopAppInfo
45 </synopsis>
46 <synopsis>
47   <link linkend="GInterface">GInterface</link>
48    +----GDesktopAppInfoLookup
49 </synopsis>
50 </refsect1>
51
52 <refsect1 id="gio-Desktop-file-based-GAppInfo.prerequisites" role="prerequisites">
53 <title role="prerequisites.title">Prerequisites</title>
54 <para>
55 GDesktopAppInfoLookup requires
56  <link linkend="GObject">GObject</link>.</para>
57 </refsect1>
58
59
60 <refsect1 id="gio-Desktop-file-based-GAppInfo.implemented-interfaces" role="impl_interfaces">
61 <title role="impl_interfaces.title">Implemented Interfaces</title>
62 <para>
63 GDesktopAppInfo implements
64  <link linkend="GAppInfo">GAppInfo</link>.</para>
65 </refsect1>
66
67
68
69
70
71 <refsect1 id="gio-Desktop-file-based-GAppInfo.description" role="desc">
72 <title role="desc.title">Description</title>
73 <para>
74 <link linkend="GDesktopAppInfo"><type>GDesktopAppInfo</type></link> is an implementation of <link linkend="GAppInfo"><type>GAppInfo</type></link> based on
75 desktop files.
76 </para>
77 <para>
78 Note that <filename>&lt;gio/gdesktopappinfo.h&gt;</filename> belongs to 
79 the UNIX-specific GIO interfaces, thus you have to use the 
80 <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.</para>
81 <para>
82 </para>
83 </refsect1>
84
85 <refsect1 id="gio-Desktop-file-based-GAppInfo.details" role="details">
86 <title role="details.title">Details</title>
87 <refsect2 id="GDesktopAppInfo-struct" role="struct">
88 <title>GDesktopAppInfo</title>
89 <indexterm zone="GDesktopAppInfo-struct"><primary sortas="DesktopAppInfo">GDesktopAppInfo</primary></indexterm><programlisting>typedef struct _GDesktopAppInfo GDesktopAppInfo;</programlisting>
90 <para>
91 Information about an installed application from a desktop file.</para>
92 <para>
93 </para></refsect2>
94 <refsect2 id="g-desktop-app-info-new-from-filename" role="function">
95 <title>g_desktop_app_info_new_from_filename ()</title>
96 <indexterm zone="g-desktop-app-info-new-from-filename"><primary sortas="desktop_app_info_new_from_filename">g_desktop_app_info_new_from_filename</primary></indexterm><programlisting><link linkend="GDesktopAppInfo">GDesktopAppInfo</link> *   g_desktop_app_info_new_from_filename
97                                                         (const <link linkend="char">char</link> *filename);</programlisting>
98 <para>
99 Creates a new <link linkend="GDesktopAppInfo"><type>GDesktopAppInfo</type></link>.</para>
100 <para>
101 </para><variablelist role="params">
102 <varlistentry><term><parameter>filename</parameter>&#160;:</term>
103 <listitem><simpara> the path of a desktop file, in the GLib filename encoding
104 </simpara></listitem></varlistentry>
105 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GDesktopAppInfo"><type>GDesktopAppInfo</type></link> or <link linkend="NULL--CAPS"><literal>NULL</literal></link> on error.
106 </simpara></listitem></varlistentry>
107 </variablelist></refsect2>
108 <refsect2 id="g-desktop-app-info-new-from-keyfile" role="function" condition="since:2.18">
109 <title>g_desktop_app_info_new_from_keyfile ()</title>
110 <indexterm zone="g-desktop-app-info-new-from-keyfile" role="2.18"><primary sortas="desktop_app_info_new_from_keyfile">g_desktop_app_info_new_from_keyfile</primary></indexterm><programlisting><link linkend="GDesktopAppInfo">GDesktopAppInfo</link> *   g_desktop_app_info_new_from_keyfile (<link linkend="GKeyFile">GKeyFile</link> *key_file);</programlisting>
111 <para>
112 Creates a new <link linkend="GDesktopAppInfo"><type>GDesktopAppInfo</type></link>.</para>
113 <para>
114 </para><variablelist role="params">
115 <varlistentry><term><parameter>key_file</parameter>&#160;:</term>
116 <listitem><simpara> an opened <link linkend="GKeyFile"><type>GKeyFile</type></link>
117 </simpara></listitem></varlistentry>
118 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GDesktopAppInfo"><type>GDesktopAppInfo</type></link> or <link linkend="NULL--CAPS"><literal>NULL</literal></link> on error.
119
120 </simpara></listitem></varlistentry>
121 </variablelist><para role="since">Since 2.18</para></refsect2>
122 <refsect2 id="g-desktop-app-info-new" role="function">
123 <title>g_desktop_app_info_new ()</title>
124 <indexterm zone="g-desktop-app-info-new"><primary sortas="desktop_app_info_new">g_desktop_app_info_new</primary></indexterm><programlisting><link linkend="GDesktopAppInfo">GDesktopAppInfo</link> *   g_desktop_app_info_new              (const <link linkend="char">char</link> *desktop_id);</programlisting>
125 <para>
126 Creates a new <link linkend="GDesktopAppInfo"><type>GDesktopAppInfo</type></link> based on a desktop file id. 
127 </para>
128 <para>
129 A desktop file id is the basename of the desktop file, including the 
130 .desktop extension. GIO is looking for a desktop file with this name 
131 in the <filename>applications</filename> subdirectories of the XDG data
132 directories (i.e. the directories specified in the 
133 <envar>XDG_DATA_HOME</envar> and <envar>XDG_DATA_DIRS</envar> environment 
134 variables). GIO also supports the prefix-to-subdirectory mapping that is
135 described in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Menu Spec</ulink> 
136 (i.e. a desktop id of kde-foo.desktop will match
137 <filename>/usr/share/applications/kde/foo.desktop</filename>).</para>
138 <para>
139 </para><variablelist role="params">
140 <varlistentry><term><parameter>desktop_id</parameter>&#160;:</term>
141 <listitem><simpara> the desktop file id
142 </simpara></listitem></varlistentry>
143 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GDesktopAppInfo"><type>GDesktopAppInfo</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if no desktop file with that id
144 </simpara></listitem></varlistentry>
145 </variablelist></refsect2>
146 <refsect2 id="g-desktop-app-info-get-is-hidden" role="function">
147 <title>g_desktop_app_info_get_is_hidden ()</title>
148 <indexterm zone="g-desktop-app-info-get-is-hidden"><primary sortas="desktop_app_info_get_is_hidden">g_desktop_app_info_get_is_hidden</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_desktop_app_info_get_is_hidden    (<link linkend="GDesktopAppInfo">GDesktopAppInfo</link> *info);</programlisting>
149 <para>
150 A desktop file is hidden if the Hidden key in it is
151 set to True.</para>
152 <para>
153 </para><variablelist role="params">
154 <varlistentry><term><parameter>info</parameter>&#160;:</term>
155 <listitem><simpara> a <link linkend="GDesktopAppInfo"><type>GDesktopAppInfo</type></link>.
156 </simpara></listitem></varlistentry>
157 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if hidden, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise. 
158 </simpara></listitem></varlistentry>
159 </variablelist></refsect2>
160 <refsect2 id="g-desktop-app-info-set-desktop-env" role="function">
161 <title>g_desktop_app_info_set_desktop_env ()</title>
162 <indexterm zone="g-desktop-app-info-set-desktop-env"><primary sortas="desktop_app_info_set_desktop_env">g_desktop_app_info_set_desktop_env</primary></indexterm><programlisting><link linkend="void">void</link>                g_desktop_app_info_set_desktop_env  (const <link linkend="char">char</link> *desktop_env);</programlisting>
163 <para>
164 Sets the name of the desktop that the application is running in.
165 This is used by <link linkend="g-app-info-should-show"><function>g_app_info_should_show()</function></link> to evaluate the
166 <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal>
167 desktop entry fields.
168 </para>
169 <para>
170 The <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop 
171 Menu specification</ulink> recognizes the following:
172 <simplelist>
173   <member>GNOME</member>
174   <member>KDE</member>
175   <member>ROX</member>
176   <member>XFCE</member>
177   <member>Old</member> 
178 </simplelist>
179 </para>
180 <para>
181 Should be called only once; subsequent calls are ignored.</para>
182 <para>
183 </para><variablelist role="params">
184 <varlistentry><term><parameter>desktop_env</parameter>&#160;:</term>
185 <listitem><simpara> a string specifying what desktop this is
186 </simpara></listitem></varlistentry>
187 </variablelist></refsect2>
188 <refsect2 id="GDesktopAppInfoLookup-struct" role="struct">
189 <title>GDesktopAppInfoLookup</title>
190 <indexterm zone="GDesktopAppInfoLookup-struct"><primary sortas="DesktopAppInfoLookup">GDesktopAppInfoLookup</primary></indexterm><programlisting>typedef struct _GDesktopAppInfoLookup GDesktopAppInfoLookup;</programlisting>
191 <para>
192 Interface that is used by backends to associate default
193 handlers with URI schemes.</para>
194 <para>
195 </para></refsect2>
196 <refsect2 id="G-DESKTOP-APP-INFO-LOOKUP-EXTENSION-POINT-NAME--CAPS" role="macro">
197 <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
198 <indexterm zone="G-DESKTOP-APP-INFO-LOOKUP-EXTENSION-POINT-NAME--CAPS"><primary sortas="DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME">G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</primary></indexterm><programlisting>#define G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME "gio-desktop-app-info-lookup"
199 </programlisting>
200 <para>
201 Extension point for default handler to URI association. See
202 <link linkend="extending-gio">Extending GIO</link>.</para>
203 <para>
204 </para></refsect2>
205 <refsect2 id="g-desktop-app-info-lookup-get-default-for-uri-scheme" role="function">
206 <title>g_desktop_app_info_lookup_get_default_for_uri_scheme ()</title>
207 <indexterm zone="g-desktop-app-info-lookup-get-default-for-uri-scheme"><primary sortas="desktop_app_info_lookup_get_default_for_uri_scheme">g_desktop_app_info_lookup_get_default_for_uri_scheme</primary></indexterm><programlisting><link linkend="GAppInfo">GAppInfo</link> *          g_desktop_app_info_lookup_get_default_for_uri_scheme
208                                                         (<link linkend="GDesktopAppInfoLookup">GDesktopAppInfoLookup</link> *lookup,
209                                                          const <link linkend="char">char</link> *uri_scheme);</programlisting>
210 <para>
211 Gets the default application for launching applications 
212 using this URI scheme for a particular GDesktopAppInfoLookup
213 implementation.
214 </para>
215 <para>
216 The GDesktopAppInfoLookup interface and this function is used
217 to implement <link linkend="g-app-info-get-default-for-uri-scheme"><function>g_app_info_get_default_for_uri_scheme()</function></link> backends
218 in a GIO module. There is no reason for applications to use it
219 directly. Applications should use <link linkend="g-app-info-get-default-for-uri-scheme"><function>g_app_info_get_default_for_uri_scheme()</function></link>.</para>
220 <para>
221 </para><variablelist role="params">
222 <varlistentry><term><parameter>lookup</parameter>&#160;:</term>
223 <listitem><simpara> a <link linkend="GDesktopAppInfoLookup"><type>GDesktopAppInfoLookup</type></link>
224 </simpara></listitem></varlistentry>
225 <varlistentry><term><parameter>uri_scheme</parameter>&#160;:</term>
226 <listitem><simpara> a string containing a URI scheme.
227 </simpara></listitem></varlistentry>
228 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="GAppInfo"><type>GAppInfo</type></link> for given <parameter>uri_scheme</parameter> or <link linkend="NULL--CAPS"><literal>NULL</literal></link> on error.
229 </simpara></listitem></varlistentry>
230 </variablelist></refsect2>
231
232 </refsect1>
233
234
235
236
237 </refentry>