1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gio.DesktopAppInfo;
26 
27 private import gio.AppInfoIF;
28 private import gio.AppInfoT;
29 private import gio.AppLaunchContext;
30 private import glib.ConstructionException;
31 private import glib.ErrorG;
32 private import glib.GException;
33 private import glib.KeyFile;
34 private import glib.ListG;
35 private import glib.Str;
36 private import gobject.ObjectG;
37 private import gtkc.gio;
38 public  import gtkc.giotypes;
39 
40 
41 /**
42  * #GDesktopAppInfo is an implementation of #GAppInfo based on
43  * desktop files.
44  * 
45  * Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
46  * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
47  * file when using it.
48  */
49 public class DesktopAppInfo : ObjectG, AppInfoIF
50 {
51 	/** the main Gtk struct */
52 	protected GDesktopAppInfo* gDesktopAppInfo;
53 
54 	/** Get the main Gtk struct */
55 	public GDesktopAppInfo* getDesktopAppInfoStruct()
56 	{
57 		return gDesktopAppInfo;
58 	}
59 
60 	/** the main Gtk struct as a void* */
61 	protected override void* getStruct()
62 	{
63 		return cast(void*)gDesktopAppInfo;
64 	}
65 
66 	protected override void setStruct(GObject* obj)
67 	{
68 		gDesktopAppInfo = cast(GDesktopAppInfo*)obj;
69 		super.setStruct(obj);
70 	}
71 
72 	/**
73 	 * Sets our main struct and passes it to the parent class.
74 	 */
75 	public this (GDesktopAppInfo* gDesktopAppInfo, bool ownedRef = false)
76 	{
77 		this.gDesktopAppInfo = gDesktopAppInfo;
78 		super(cast(GObject*)gDesktopAppInfo, ownedRef);
79 	}
80 
81 	// add the AppInfo capabilities
82 	mixin AppInfoT!(GDesktopAppInfo);
83 
84 	/**
85 	 * Creates a new #GDesktopAppInfo.
86 	 *
87 	 * Params:
88 	 *     filename = the path of a desktop file, in the GLib filename encoding
89 	 *
90 	 * Return: a new #GDesktopAppInfo or %NULL on error.
91 	 *
92 	 * Throws: ConstructionException GTK+ fails to create the object.
93 	 */
94 	public static DesktopAppInfo createFromFilename(string filename)
95 	{
96 		auto p = g_desktop_app_info_new_from_filename(Str.toStringz(filename));
97 		
98 		if(p is null)
99 		{
100 			throw new ConstructionException("null returned by g_desktop_app_info_new_from_filename");
101 		}
102 		
103 		return new DesktopAppInfo(p, true);
104 	}
105 
106 	/**
107 	 */
108 
109 	/** */
110 	public static GType getType()
111 	{
112 		return g_desktop_app_info_get_type();
113 	}
114 
115 	/**
116 	 * Creates a new #GDesktopAppInfo based on a desktop file id.
117 	 *
118 	 * A desktop file id is the basename of the desktop file, including the
119 	 * .desktop extension. GIO is looking for a desktop file with this name
120 	 * in the `applications` subdirectories of the XDG
121 	 * data directories (i.e. the directories specified in the `XDG_DATA_HOME`
122 	 * and `XDG_DATA_DIRS` environment variables). GIO also supports the
123 	 * prefix-to-subdirectory mapping that is described in the
124 	 * [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/)
125 	 * (i.e. a desktop id of kde-foo.desktop will match
126 	 * `/usr/share/applications/kde/foo.desktop`).
127 	 *
128 	 * Params:
129 	 *     desktopId = the desktop file id
130 	 *
131 	 * Return: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
132 	 *
133 	 * Throws: ConstructionException GTK+ fails to create the object.
134 	 */
135 	public this(string desktopId)
136 	{
137 		auto p = g_desktop_app_info_new(Str.toStringz(desktopId));
138 		
139 		if(p is null)
140 		{
141 			throw new ConstructionException("null returned by new");
142 		}
143 		
144 		this(cast(GDesktopAppInfo*) p, true);
145 	}
146 
147 	/**
148 	 * Creates a new #GDesktopAppInfo.
149 	 *
150 	 * Params:
151 	 *     keyFile = an opened #GKeyFile
152 	 *
153 	 * Return: a new #GDesktopAppInfo or %NULL on error.
154 	 *
155 	 * Since: 2.18
156 	 *
157 	 * Throws: ConstructionException GTK+ fails to create the object.
158 	 */
159 	public this(KeyFile keyFile)
160 	{
161 		auto p = g_desktop_app_info_new_from_keyfile((keyFile is null) ? null : keyFile.getKeyFileStruct());
162 		
163 		if(p is null)
164 		{
165 			throw new ConstructionException("null returned by new_from_keyfile");
166 		}
167 		
168 		this(cast(GDesktopAppInfo*) p, true);
169 	}
170 
171 	/**
172 	 * Gets all applications that implement @interface.
173 	 *
174 	 * An application implements an interface if that interface is listed in
175 	 * the Implements= line of the desktop file of the application.
176 	 *
177 	 * Params:
178 	 *     iface = the name of the interface
179 	 *
180 	 * Return: a list of #GDesktopAppInfo
181 	 *     objects.
182 	 *
183 	 * Since: 2.42
184 	 */
185 	public static ListG getImplementations(string iface)
186 	{
187 		auto p = g_desktop_app_info_get_implementations(Str.toStringz(iface));
188 		
189 		if(p is null)
190 		{
191 			return null;
192 		}
193 		
194 		return new ListG(cast(GList*) p, true);
195 	}
196 
197 	/**
198 	 * Searches desktop files for ones that match @search_string.
199 	 *
200 	 * The return value is an array of strvs.  Each strv contains a list of
201 	 * applications that matched @search_string with an equal score.  The
202 	 * outer list is sorted by score so that the first strv contains the
203 	 * best-matching applications, and so on.
204 	 * The algorithm for determining matches is undefined and may change at
205 	 * any time.
206 	 *
207 	 * Params:
208 	 *     searchString = the search string to use
209 	 *
210 	 * Return: a
211 	 *     list of strvs.  Free each item with g_strfreev() and free the outer
212 	 *     list with g_free().
213 	 */
214 	public static string[][] search(string searchString)
215 	{
216 		auto retStr = g_desktop_app_info_search(Str.toStringz(searchString));
217 		
218 		scope(exit) Str.freeStringArray(retStr);
219 		return Str.toStringArray(retStr);
220 	}
221 
222 	/**
223 	 * Sets the name of the desktop that the application is running in.
224 	 * This is used by g_app_info_should_show() and
225 	 * g_desktop_app_info_get_show_in() to evaluate the
226 	 * `OnlyShowIn` and `NotShowIn`
227 	 * desktop entry fields.
228 	 *
229 	 * Should be called only once; subsequent calls are ignored.
230 	 *
231 	 * Deprecated: do not use this API.  Since 2.42 the value of the
232 	 * `XDG_CURRENT_DESKTOP` environment variable will be used.
233 	 *
234 	 * Params:
235 	 *     desktopEnv = a string specifying what desktop this is
236 	 */
237 	public static void setDesktopEnv(string desktopEnv)
238 	{
239 		g_desktop_app_info_set_desktop_env(Str.toStringz(desktopEnv));
240 	}
241 
242 	/**
243 	 * Gets the user-visible display name of the "additional application
244 	 * action" specified by @action_name.
245 	 *
246 	 * This corresponds to the "Name" key within the keyfile group for the
247 	 * action.
248 	 *
249 	 * Params:
250 	 *     actionName = the name of the action as from
251 	 *         g_desktop_app_info_list_actions()
252 	 *
253 	 * Return: the locale-specific action name
254 	 *
255 	 * Since: 2.38
256 	 */
257 	public string getActionName(string actionName)
258 	{
259 		auto retStr = g_desktop_app_info_get_action_name(gDesktopAppInfo, Str.toStringz(actionName));
260 		
261 		scope(exit) Str.freeString(retStr);
262 		return Str.toString(retStr);
263 	}
264 
265 	/**
266 	 * Looks up a boolean value in the keyfile backing @info.
267 	 *
268 	 * The @key is looked up in the "Desktop Entry" group.
269 	 *
270 	 * Params:
271 	 *     key = the key to look up
272 	 *
273 	 * Return: the boolean value, or %FALSE if the key
274 	 *     is not found
275 	 *
276 	 * Since: 2.36
277 	 */
278 	public bool getBoolean(string key)
279 	{
280 		return g_desktop_app_info_get_boolean(gDesktopAppInfo, Str.toStringz(key)) != 0;
281 	}
282 
283 	/**
284 	 * Gets the categories from the desktop file.
285 	 *
286 	 * Return: The unparsed Categories key from the desktop file;
287 	 *     i.e. no attempt is made to split it by ';' or validate it.
288 	 */
289 	public string getCategories()
290 	{
291 		return Str.toString(g_desktop_app_info_get_categories(gDesktopAppInfo));
292 	}
293 
294 	/**
295 	 * When @info was created from a known filename, return it.  In some
296 	 * situations such as the #GDesktopAppInfo returned from
297 	 * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
298 	 *
299 	 * Return: The full path to the file for @info,
300 	 *     or %NULL if not known.
301 	 *
302 	 * Since: 2.24
303 	 */
304 	public string getFilename()
305 	{
306 		return Str.toString(g_desktop_app_info_get_filename(gDesktopAppInfo));
307 	}
308 
309 	/**
310 	 * Gets the generic name from the destkop file.
311 	 *
312 	 * Return: The value of the GenericName key
313 	 */
314 	public string getGenericName()
315 	{
316 		return Str.toString(g_desktop_app_info_get_generic_name(gDesktopAppInfo));
317 	}
318 
319 	/**
320 	 * A desktop file is hidden if the Hidden key in it is
321 	 * set to True.
322 	 *
323 	 * Return: %TRUE if hidden, %FALSE otherwise.
324 	 */
325 	public bool getIsHidden()
326 	{
327 		return g_desktop_app_info_get_is_hidden(gDesktopAppInfo) != 0;
328 	}
329 
330 	/**
331 	 * Gets the keywords from the desktop file.
332 	 *
333 	 * Return: The value of the Keywords key
334 	 *
335 	 * Since: 2.32
336 	 */
337 	public string[] getKeywords()
338 	{
339 		return Str.toStringArray(g_desktop_app_info_get_keywords(gDesktopAppInfo));
340 	}
341 
342 	/**
343 	 * Gets the value of the NoDisplay key, which helps determine if the
344 	 * application info should be shown in menus. See
345 	 * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
346 	 *
347 	 * Return: The value of the NoDisplay key
348 	 *
349 	 * Since: 2.30
350 	 */
351 	public bool getNodisplay()
352 	{
353 		return g_desktop_app_info_get_nodisplay(gDesktopAppInfo) != 0;
354 	}
355 
356 	/**
357 	 * Checks if the application info should be shown in menus that list available
358 	 * applications for a specific name of the desktop, based on the
359 	 * `OnlyShowIn` and `NotShowIn` keys.
360 	 *
361 	 * @desktop_env should typically be given as %NULL, in which case the
362 	 * `XDG_CURRENT_DESKTOP` environment variable is consulted.  If you want
363 	 * to override the default mechanism then you may specify @desktop_env,
364 	 * but this is not recommended.
365 	 *
366 	 * Note that g_app_info_should_show() for @info will include this check (with
367 	 * %NULL for @desktop_env) as well as additional checks.
368 	 *
369 	 * Params:
370 	 *     desktopEnv = a string specifying a desktop name
371 	 *
372 	 * Return: %TRUE if the @info should be shown in @desktop_env according to the
373 	 *     `OnlyShowIn` and `NotShowIn` keys, %FALSE
374 	 *     otherwise.
375 	 *
376 	 * Since: 2.30
377 	 */
378 	public bool getShowIn(string desktopEnv)
379 	{
380 		return g_desktop_app_info_get_show_in(gDesktopAppInfo, Str.toStringz(desktopEnv)) != 0;
381 	}
382 
383 	/**
384 	 * Retrieves the StartupWMClass field from @info. This represents the
385 	 * WM_CLASS property of the main window of the application, if launched
386 	 * through @info.
387 	 *
388 	 * Return: the startup WM class, or %NULL if none is set
389 	 *     in the desktop file.
390 	 *
391 	 * Since: 2.34
392 	 */
393 	public string getStartupWmClass()
394 	{
395 		return Str.toString(g_desktop_app_info_get_startup_wm_class(gDesktopAppInfo));
396 	}
397 
398 	/**
399 	 * Looks up a string value in the keyfile backing @info.
400 	 *
401 	 * The @key is looked up in the "Desktop Entry" group.
402 	 *
403 	 * Params:
404 	 *     key = the key to look up
405 	 *
406 	 * Return: a newly allocated string, or %NULL if the key
407 	 *     is not found
408 	 *
409 	 * Since: 2.36
410 	 */
411 	public string getString(string key)
412 	{
413 		auto retStr = g_desktop_app_info_get_string(gDesktopAppInfo, Str.toStringz(key));
414 		
415 		scope(exit) Str.freeString(retStr);
416 		return Str.toString(retStr);
417 	}
418 
419 	/**
420 	 * Returns whether @key exists in the "Desktop Entry" group
421 	 * of the keyfile backing @info.
422 	 *
423 	 * Params:
424 	 *     key = the key to look up
425 	 *
426 	 * Return: %TRUE if the @key exists
427 	 *
428 	 * Since: 2.36
429 	 */
430 	public bool hasKey(string key)
431 	{
432 		return g_desktop_app_info_has_key(gDesktopAppInfo, Str.toStringz(key)) != 0;
433 	}
434 
435 	/**
436 	 * Activates the named application action.
437 	 *
438 	 * You may only call this function on action names that were
439 	 * returned from g_desktop_app_info_list_actions().
440 	 *
441 	 * Note that if the main entry of the desktop file indicates that the
442 	 * application supports startup notification, and @launch_context is
443 	 * non-%NULL, then startup notification will be used when activating the
444 	 * action (and as such, invocation of the action on the receiving side
445 	 * must signal the end of startup notification when it is completed).
446 	 * This is the expected behaviour of applications declaring additional
447 	 * actions, as per the desktop file specification.
448 	 *
449 	 * As with g_app_info_launch() there is no way to detect failures that
450 	 * occur while using this function.
451 	 *
452 	 * Params:
453 	 *     actionName = the name of the action as from
454 	 *         g_desktop_app_info_list_actions()
455 	 *     launchContext = a #GAppLaunchContext
456 	 *
457 	 * Since: 2.38
458 	 */
459 	public void launchAction(string actionName, AppLaunchContext launchContext)
460 	{
461 		g_desktop_app_info_launch_action(gDesktopAppInfo, Str.toStringz(actionName), (launchContext is null) ? null : launchContext.getAppLaunchContextStruct());
462 	}
463 
464 	/**
465 	 * This function performs the equivalent of g_app_info_launch_uris(),
466 	 * but is intended primarily for operating system components that
467 	 * launch applications.  Ordinary applications should use
468 	 * g_app_info_launch_uris().
469 	 *
470 	 * If the application is launched via traditional UNIX fork()/exec()
471 	 * then @spawn_flags, @user_setup and @user_setup_data are used for the
472 	 * call to g_spawn_async().  Additionally, @pid_callback (with
473 	 * @pid_callback_data) will be called to inform about the PID of the
474 	 * created process.
475 	 *
476 	 * If application launching occurs via some other mechanism (eg: D-Bus
477 	 * activation) then @spawn_flags, @user_setup, @user_setup_data,
478 	 * @pid_callback and @pid_callback_data are ignored.
479 	 *
480 	 * Params:
481 	 *     uris = List of URIs
482 	 *     launchContext = a #GAppLaunchContext
483 	 *     spawnFlags = #GSpawnFlags, used for each process
484 	 *     userSetup = a #GSpawnChildSetupFunc, used once
485 	 *         for each process.
486 	 *     userSetupData = User data for @user_setup
487 	 *     pidCallback = Callback for child processes
488 	 *     pidCallbackData = User data for @callback
489 	 *
490 	 * Return: %TRUE on successful launch, %FALSE otherwise.
491 	 *
492 	 * Throws: GException on failure.
493 	 */
494 	public bool launchUrisAsManager(ListG uris, AppLaunchContext launchContext, GSpawnFlags spawnFlags, GSpawnChildSetupFunc userSetup, void* userSetupData, GDesktopAppLaunchCallback pidCallback, void* pidCallbackData)
495 	{
496 		GError* err = null;
497 		
498 		auto p = g_desktop_app_info_launch_uris_as_manager(gDesktopAppInfo, (uris is null) ? null : uris.getListGStruct(), (launchContext is null) ? null : launchContext.getAppLaunchContextStruct(), spawnFlags, userSetup, userSetupData, pidCallback, pidCallbackData, &err) != 0;
499 		
500 		if (err !is null)
501 		{
502 			throw new GException( new ErrorG(err) );
503 		}
504 		
505 		return p;
506 	}
507 
508 	/**
509 	 * Returns the list of "additional application actions" supported on the
510 	 * desktop file, as per the desktop file specification.
511 	 *
512 	 * As per the specification, this is the list of actions that are
513 	 * explicitly listed in the "Actions" key of the [Desktop Entry] group.
514 	 *
515 	 * Return: a list of strings, always non-%NULL
516 	 *
517 	 * Since: 2.38
518 	 */
519 	public string[] listActions()
520 	{
521 		return Str.toStringArray(g_desktop_app_info_list_actions(gDesktopAppInfo));
522 	}
523 }