GNOME.org
 

[gnome-devel-docs/wip/kill-integration-guide: 1/3] Add desktop entry topics to platform overview

commit 06d5c255f4f4a8c0f36bc817054d1e6feb54a99d
Author: David King <amigadave amigadave com>
Date:   Mon Jan 27 18:59:12 2014 +0000

    Add desktop entry topics to platform overview

 platform-overview/C/dev-launching-desktop.page     |   74 ++++++++++++++++++++
 platform-overview/C/dev-launching-icons.page       |   39 ++++++++++
 platform-overview/C/dev-launching-mime.page        |   49 +++++++++++++
 .../C/dev-launching-startupnotify.page             |   40 +++++++++++
 platform-overview/C/dev-launching.page             |   35 +++++++++
 platform-overview/C/index.page                     |    2 +-
 platform-overview/Makefile.am                      |    5 ++
 7 files changed, 243 insertions(+), 1 deletions(-)
---
diff --git a/platform-overview/C/dev-launching-desktop.page b/platform-overview/C/dev-launching-desktop.page
new file mode 100644
index 0000000..6b69a6b
--- /dev/null
+++ b/platform-overview/C/dev-launching-desktop.page
@@ -0,0 +1,74 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="dev-launching-desktop">
+
+  <info>
+    <link type="next" xref="dev-launching-icons"/>
+    <revision version="0.1" date="2014-01-28" status="draft"/>
+
+    <credit type="author">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+      <years>2014</years>
+    </credit>
+
+    <include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Install a desktop file</title>
+
+  <links type="series" style="floatend">
+    <title>Launch your application</title>
+  </links>
+
+  <p>Write and install a desktop file so that users can discover and launch
+  your application.</p>
+  
+  <p>GNOME uses the <link type="seealso" 
href="http://standards.freedesktop.org/desktop-entry-spec/latest/index.html";>freedesktop.org
+  Desktop Entry</link> and <link type="seealso" 
href="http://standards.freedesktop.org/desktop-menu-spec/latest/index.html";>Desktop
+  Menu specifications</link> to describe application launchers. Installing a
+  desktop file is the standard way to register your application with GNOME and
+  other desktops.</p>
+  
+  <p>A desktop file lists your application binary, name and type, and can also
+  list an icon, description and several other pieces of information about
+  launching an application.</p>
+
+  <p>For a hypothetical application <app>My Application</app>, a desktop file
+  would look as follows:</p>
+  <example>
+    <listing>
+      <title><file>myapplication.desktop</file></title>
+<code>[Desktop Entry]
+Name=My Application
+Exec=myapplication
+Type=Application
+Icon=myapplication
+Comment=Do the thing that the application does
+Categories=GTK;GNOME;Utility;</code>
+    </listing>
+  </example>
+
+  <p>The <code>[Desktop Entry]</code> line indicates that this is a desktop
+  file. It is followed by keys, which describe the application launcher. The
+  <code>Name</code> key is the human-readable name of the application, to be
+  shown in the UI. The application binary is listed in the <code>Exec</code>
+  key, either the complete path or a binary that is looked up in the
+  <code>PATH</code>. The last required key is the <code>Type</code>, which for
+  applications is always <code>Application</code>. Alternative types are listed
+  in the desktop entry specification.</p>
+
+  <p>Other fields in the desktop file are optional, but recommended.
+  Applications should install an icon, and list the name of the icon (excluding
+  the extension) in the <code>Icon</code> key. The <code>Comment</code> is a
+  brief description of the application. To help users when browsing
+  applications, the <code>Categories</code> key should be populated with a
+  list of categories, separated by a semicolon, from the Desktop Menu
+  Specification.</p>
+
+  <p>There are several other keys that can be added to desktop files, which are
+  listed and described in the Desktop Entry Specification.</p>
+ 
+</page>
diff --git a/platform-overview/C/dev-launching-icons.page b/platform-overview/C/dev-launching-icons.page
new file mode 100644
index 0000000..13b84a2
--- /dev/null
+++ b/platform-overview/C/dev-launching-icons.page
@@ -0,0 +1,39 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="dev-launching-icons">
+
+  <info>
+    <link type="next" xref="dev-launching-startupnotify"/>
+    <revision version="0.1" date="2014-01-28" status="draft"/>
+
+    <credit type="author">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+      <years>2014</years>
+    </credit>
+
+    <include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Install an icon</title>
+
+  <links type="series" style="floatend">
+    <title>Launch your application</title>
+  </links>
+
+  <p>Install an icon to identify your application.</p>
+  
+  <p>When listing an icon in a desktop file, the image must be installed in a
+  standard location, given by the <link type="seealso" 
href="http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html";>freedesktop.org
+  Icon Theme</link> and <link type="seealso" 
href="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html";>Icon
+  Naming specifications</link>. As a minimum, an application should install a
+  48×48 pixel icon into <file><var>$prefix</var>/share/icons/hicolor/48x48/apps</file>
+  in PNG format.</p>
+
+  <p>To match with other icons, both in GNOME and other platforms, follow the
+  <link type="seealso" href="http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines";>Tango
+  Icon Theme guidelines</link> when creating icons and application artwork.</p>
+ 
+</page>
diff --git a/platform-overview/C/dev-launching-mime.page b/platform-overview/C/dev-launching-mime.page
new file mode 100644
index 0000000..eb56106
--- /dev/null
+++ b/platform-overview/C/dev-launching-mime.page
@@ -0,0 +1,49 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="dev-launching-mime">
+
+  <info>
+    <revision version="0.1" date="2014-01-28" status="draft"/>
+
+    <credit type="author">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+      <years>2014</years>
+    </credit>
+
+    <include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Associate MIME types</title>
+
+  <links type="series" style="floatend">
+    <title>Launch your application</title>
+  </links>
+
+  <p>Associate files with your application, using MIME types.</p>
+  
+  <p>If your application opens files of a certain type, such as PNG images, you
+  can add an association with the MIME type of the file. This is added to the
+  desktop file.</p>
+
+  <example>
+    <listing>
+      <title><file>myapplication.desktop</file></title>
+<code>[Desktop Entry]
+Name=My Application
+Exec=myapplication
+Type=Application
+MimeType=image/png</code>
+    </listing>
+  </example>
+
+  <p>For this hypothetical application, <code>image/png</code> is listed as the
+  supported MIME type.</p>
+
+  <p>Custom MIME types can be added to the system-wide MIME database, but this
+  is outside the scope of this guide. The <link type="seealso" 
href="http://standards.freedesktop.org/shared-mime-info-spec/latest/";>Shared
+  MIME-Info Database</link> specification for more details.</p>
+
+</page>
diff --git a/platform-overview/C/dev-launching-startupnotify.page 
b/platform-overview/C/dev-launching-startupnotify.page
new file mode 100644
index 0000000..7fdd59b
--- /dev/null
+++ b/platform-overview/C/dev-launching-startupnotify.page
@@ -0,0 +1,40 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="dev-launching-startupnotify">
+
+  <info>
+    <link type="next" xref="dev-launching-mime"/>
+    <revision version="0.1" date="2014-01-28" status="draft"/>
+
+    <credit type="author">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+      <years>2014</years>
+    </credit>
+
+    <include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Startup Notification</title>
+
+  <links type="series" style="floatend">
+    <title>Launch your application</title>
+  </links>
+
+  <p>Notify the user when your application has finished starting up.</p>
+  
+  <p>GNOME implements the <link type="seealso" 
href="http://standards.freedesktop.org/desktop-entry-spec/latest/index.html";>Startup
+  Notification protocol</link>, to give feedback to the user when application
+  startup finishes.</p>
+  
+  <p>GTK+ applications automatically support startup notification, and by
+  default notify that application startup is complete when the first window is
+  shown. Your application must declare that it supports startup notification by
+  adding <code>StartupNotify=true</code> to its desktop file.</p>
+
+  <p>More complicated startup scenarios, such as showing a splash screen during
+  startup, would need custom handling with <code 
href="https://developer.gnome.org/gdk3/stable/gdk3-General.html#gdk-notify-startup-complete";>gdk_notify_startup_complete()</code>.</p>
+
+</page>
diff --git a/platform-overview/C/dev-launching.page b/platform-overview/C/dev-launching.page
new file mode 100644
index 0000000..440cc6c
--- /dev/null
+++ b/platform-overview/C/dev-launching.page
@@ -0,0 +1,35 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="dev-launching">
+
+  <info>
+    <link type="guide" xref="index" group="launching"/>
+    <link type="next" xref="dev-launching-desktop"/>
+    <link type="seealso" xref="dev-translate"/>
+
+    <revision version="0.1" date="2014-01-27" status="draft"/>
+
+    <credit type="author copyright">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+      <years>2014</years>
+    </credit>
+
+    <include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+    <desc>Showing a launcher and starting your application.</desc>
+
+  </info>
+
+  <title>Application launching</title>
+
+  <links type="series" style="floatend">
+    <title>Launch your application</title>
+  </links>
+
+  <p>An icon in the launcher is the standard way to launch your application.
+  Use the freedesktop.org Desktop Entry Specification standard to create a
+  desktop file, giving your application name, icon and a brief description.</p>
+
+</page>
diff --git a/platform-overview/C/index.page b/platform-overview/C/index.page
index 37b3854..193ebba 100644
--- a/platform-overview/C/index.page
+++ b/platform-overview/C/index.page
@@ -62,7 +62,7 @@
     <links type="topic" style="2column" groups="#first ui"/>
   </section>-->
 
-  <links type="topic" style="grid center" groups="help translate">
+  <links type="topic" style="grid center" groups="launching help translate">
     <title style="heading">Integration guides</title>
   </links>
 
diff --git a/platform-overview/Makefile.am b/platform-overview/Makefile.am
index 5f66d83..78db36b 100644
--- a/platform-overview/Makefile.am
+++ b/platform-overview/Makefile.am
@@ -8,6 +8,11 @@ HELP_FILES = \
        dev-help-build.page \
        dev-help.page \
        dev-help-write.page \
+       dev-launching-desktop.page \
+       dev-launching-icons.page \
+       dev-launching-mime.page \
+       dev-launching-startupnotify.page \
+       dev-launching.page \
        dev-translate-build.page \
        dev-translate.page \
        dev-translate-setup.page \
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]