obt/link.h

   1 /* -*- indent-tabs-mode: nil; tab-width: 4; c-basic-offset: 4; -*-
   2
   3    obt/link.h for the Openbox window manager
   4    Copyright (c) 2009-2011   Dana Jansens
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 2 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    See the COPYING file for a copy of the GNU General Public License.
  17 */
  18
  19 #ifndef __obt_link_h
  20 #define __obt_link_h
  21
  22 #include <glib.h>
  23
  24 G_BEGIN_DECLS
  25
  26 struct _ObtPaths;
  27
  28 typedef enum {
  29         OBT_LINK_TYPE_APPLICATION = 1,
  30         OBT_LINK_TYPE_URL         = 2,
  31         OBT_LINK_TYPE_DIRECTORY   = 3
  32 } ObtLinkType;
  33
  34 typedef enum {
  35         OBT_LINK_APP_STARTUP_NO_SUPPORT,
  36         OBT_LINK_APP_STARTUP_PROTOCOL_SUPPORT,
  37         OBT_LINK_APP_STARTUP_LEGACY_SUPPORT
  38 } ObtLinkAppStartup;
  39
  40 /*! These bit flags are environments for links.  Some links are used or not
  41   used in various environments. */
  42 typedef enum {
  43     OBT_LINK_ENV_OPENBOX = 1 << 0,
  44     OBT_LINK_ENV_GNOME   = 1 << 1,
  45     OBT_LINK_ENV_KDE     = 1 << 2,
  46     OBT_LINK_ENV_LXDE    = 1 << 3,
  47     OBT_LINK_ENV_ROX     = 1 << 4,
  48     OBT_LINK_ENV_XFCE    = 1 << 5,
  49     OBT_LINK_ENV_OLD     = 1 << 6
  50 } ObtLinkEnvFlags;
  51
  52 typedef enum {
  53         /*! The app can be launched with a single local file */
  54         OBT_LINK_APP_SINGLE_LOCAL = 1 << 0,
  55         /*! The app can be launched with multiple local files */
  56         OBT_LINK_APP_MULTI_LOCAL  = 1 << 1,
  57         /*! The app can be launched with a single URL */
  58         OBT_LINK_APP_SINGLE_URL   = 1 << 2,
  59         /*! The app can be launched with multiple URLs */
  60         OBT_LINK_APP_MULTI_URL    = 1 << 3
  61 } ObtLinkAppOpen;
  62
  63 typedef struct _ObtLink     ObtLink;
  64
  65 /*! Parse a .desktop (dd) file.
  66   @param path The full path to the .desktop file, encoded in UTF-8.
  67   @param o An ObtPaths structure, which contains the executable paths.
  68 */
  69 ObtLink* obt_link_from_ddfile(const gchar *path,
  70                               struct _ObtPaths *p,
  71                               const gchar *language,
  72                               const gchar *country,
  73                               const gchar *modifier);
  74
  75 /*! Determine the identifier for a .desktop (dd) file.
  76   @param filename The full path to the .desktop file _relative to_ some
  77     basepath.  For instance, if the desktop file is
  78     /usr/share/applications/foo/bar.desktop, and the basepath is
  79     /usr/share/applications, then the filename would be 'foo/bar.desktop'.
  80     The filename must end with ".desktop" and be encoded in utf8.
  81 */
  82 gchar* obt_link_id_from_ddfile(const gchar *filename);
  83
  84 void obt_link_ref(ObtLink *e);
  85 void obt_link_unref(ObtLink *e);
  86
  87 const gchar *obt_link_source_file(ObtLink *e);
  88
  89 /*! Returns TRUE if the file exists but says it should be ignored, with
  90     the Hidden flag.  No other functions can be used for the ObtLink
  91     in this case. */
  92 gboolean obt_link_deleted (ObtLink *e);
  93
  94 /*! Returns the type of object refered to by the .desktop file. */
  95 ObtLinkType obt_link_type (ObtLink *e);
  96
  97 /*! Returns TRUE if the .desktop file should be displayed to users, given the
  98     current     environment.  If FALSE, the .desktop file should not be showed.
  99         This also uses the TryExec option if it is present.
 100     @param environments A bitflags of values from ObtLinkEnvFlags indicating
 101       the active environments. */
 102 gboolean obt_link_display(ObtLink *e, const guint environments);
 103
 104 const gchar* obt_link_name           (ObtLink *e);
 105 const gchar* obt_link_generic_name   (ObtLink *e);
 106 const gchar* obt_link_comment        (ObtLink *e);
 107 /*! Returns the icon for the object referred to by the .desktop file.
 108     Returns either an absolute path, or a string which can be used to find the
 109     icon using the algorithm given by:
 110     http://freedesktop.org/wiki/Specifications/icon-theme-spec?action=show&redirect=Standards/icon-theme-spec
 111 */
 112 const gchar* obt_link_icon           (ObtLink *e);
 113
 114 const gchar *obt_link_url_path(ObtLink *e);
 115
 116 const gchar*  obt_link_app_executable      (ObtLink *e);
 117 /*! Returns the path in which the application should be run */
 118 const gchar*  obt_link_app_path            (ObtLink *e);
 119 gboolean      obt_link_app_run_in_terminal (ObtLink *e);
 120 const gchar*const* obt_link_app_mime_types (ObtLink *e);
 121
 122 /*! Returns a list of categories listed by the link.  This may be empty if the
 123   application does not list a category. */
 124 const GQuark* obt_link_app_categories      (ObtLink *e, gulong *n);
 125
 126 /*! Returns a combination of values in the ObtLinkAppOpen enum,
 127     specifying if the application can be launched to open one or more files
 128     and URLs. */
 129 ObtLinkAppOpen obt_link_app_open(ObtLink *e);
 130
 131 ObtLinkAppStartup obt_link_app_startup_notify(ObtLink *e);
 132 const gchar* obt_link_app_startup_wmclass(ObtLink *e);
 133
 134 /*! Compares two ObtLink objects.
 135   @param a An ObtLink** (pointer to a pointer)
 136   @param b An ObtLink** (pointer to a pointer)
 137   @return Returns 0 if their names are the same, a number < 0 if a has a name
 138     which comes first, and a number > 0 if b has a name which comes first.
 139 */
 140 int obt_link_cmp_by_name(const void *a, const void *b);
 141
 142
 143 G_END_DECLS
 144
 145 #endif