# 将现有软件集成到 GNOME

给独立软件开发者的指南

给独立软件开发者的指南

Rosanna
Yuen

    	    zana@gnome.org

Federico
Mena-Quintero

    	    federico@gnu.org

Mike
Hearn

    	    mike@navi.cx

2005, 2006
Rosanna Yuen, Federico Mena-Quintero, Mike Hearn
2008.
Aron Xu (happyaron.xu@gmail.com)
2010.
YunQiang Su (wzssyqa@gmail.com)
0.6
2006年9月19日

扩展的图标指南。

0.5
2006年9月18日

集成了 Rosanna Yuen 的关于 freedesktop.org 标准的第一篇论文的内容。

0.0
2005年6月

此文档的初始版本。

对于本文档的复制、分发和/或修改必须遵循自由软件基金会 (Free Software Foundation) 发布的 GNU 自由文档许可证 (GFDL) 版本 1.1 或更高版本，该许可证没有固定的部分、没有封面和背页文本。您可以在此链接上或在随本手册一起分发的 COPYING-DOCS 文件中找到 GFDL 的副本。

本手册是在 GFDL 许可之下分发的 GNOME 手册集合的一部分。如果想要单独分发此手册，可以在手册中添加该许可证的一份副本然后分发，如该许可证的第 6 部分所述。

各个公司使用的许多用于区别它们产品和服务的名称都声明为商标。在所有的 GNOME 文档以及 GNOME 文档项目的成员中，这些名称都是以全大写字母或首字母大写显示，从而表明它们是商标。

本文档以及文档的修改版本都是在遵循 GNU 自由文档许可证的条款下提供，这表示具有以下含义：

1. 文档按“原样”提供，不提供任何明示或暗示的保证，包括但不限于：文档或文档的修改版本没有适销性方面的缺陷、适合特定目的的适用性，以及没有侵权行为。您将自行承担本文档以及文档修改版本的质量、准确性以及性能方面的风险。如果任何文档或文档修改版本存在缺陷，您（而不是最初的编写者、作者或撰写人）将承担所有必需的服务、维修或更正的费用。此免责声明是本许可证的重要组成部分。如果不接受此免责声明，那么您就没有权利使用任何文档或文档的修改版本；并且

2. 无论在任何情况以及在任何法律理论下，本文档或文档修改版本的作者、最初的编写者、任何撰写人或任何分发者，或者任意这些方的任何提供者都不对任何人由于使用本文档或文档修改版本引起或带来的任何直接的、间接的、特殊的、偶然的或继发的损失承担任何民事（包括疏忽）、合同或其它方面的责任，这些损失包括但不限于信誉损失、工作停止、计算机失败或故障，或任何以及所有其它损失或由此引发的或与之相关的损失，即使这些方已被告知存在出现此类损失的可能性时也是如此。

## 前言

GNOME 是一个完全基于自由软件构建完整的桌面和开发平台的项目。很多公司、政府机构、学校、研究机构和个人在其系统上部署了 GNOME 桌面。如果您是第三方开发者(独立软件开发商 (ISV) 或者在不商业经营时，叫独立软件开发者 (ISD))，您可能希望确保您现有的软件可以在 GNOME 上正常运行。本文档解释怎样将现有软件和 GNOME 集成，而不用明确地使用 GNOME 平台库和开发工具重写软件。

本指南在下列情况下会有用：

- 您是软件开发者或发行者，拥有一个不是明确的为 GNOME 而设计，但是您可能希望确保其可以在 GNOME 桌面较好的运行。

- 您是为用户部署了 GNOME 桌的单位的系统管理员。您也有一些旧的或内部的应用程序，并且您希望您的 GNOME 用户可以方便地使用那些程序。

- 您正在希望正确地编写一个 GNOME 应用程序，需要一些基本的检查项以确保您的应用程序可以和 GNOME 桌面的其它部分很好地集成。

本文档是关于集成现有软件到 GNOME 桌面的一般事项。另一方面，如果您正在考虑编写一个新应用程序，我们鼓励您完全使用 GNOME 作为目标平台，这方面的更多信息，请参考 GNOME 开发者网站。

GNOME 的一项主要考虑是用户体验。用户应该有一个舒适的计算环境：这意味着有一个完整的桌面以及一套以相似方式运行的应用程序。通过很少的相关工作，不是明确地为 GNOME 编写的应用程序可以在 GNOME 桌面中舒适地使用。

### 本指南的结构

本指南按照将软件和 GNOME 集成所需要的一系列任务进行组织。指南中，呈现这些任务时，大致以重要性进行排序。例如，向 GNOME 桌面菜单添加应用程序比添加拖放支持出现得早。同时，本指南也有一个 关于集成工作检查项的附录 以帮助您对集成工作进行评估。

### freedesktop.org 和标准

本指南中的很多集成任务依赖于标准，而不仅与 GNOME 相关。其它桌面环境项目，比如 K 桌面环境 也使用这些标准：如果您将应用程序和 GNOME 进行了集成，您应该只需要做很少的工作甚至完全不用做任何工作就可以让它们在其它桌面环境中同样好地运行。

创造一个完美的应用程序是一种美妙的感觉。无论大小，您都会希望桌面环境可以识别您的应用程序并和它们进行适当的交互。对于当前可用的多种桌面环境，最好使您的应用程序可以和尽量多的桌面环境结合集成。尽管没有官方的规则，在 freedesktop.org 有一组规范。

虽然不是一个正式的标准，freedesktop.org 维护了一组非正式但是普遍认可的方针。服从这些方针时，允许应用程序和兼容的桌面环境集成。

## 基本集成

本章教您将一个程序集成到 GNOME 桌面的基本步骤。这些步骤考虑到了如下要求：

- 通过让程序出现在桌面面板菜单中或桌面的其它启动机制中，以方便用户启动程序。

- 让桌面环境知道哪种类型的用户文件需要启动您的应用程序。

- 让桌面环境知道如何为您的程序和程序创建的文件显示相应的图标。

### 桌面项文件：将您的应用程序放在桌面菜单中。

要从 GNOME 中运行应用程序，用户需要点击他们桌面上的图标或者从菜单中选择。因此，将现有程序集成到 GNOME 的第一步就是将其 注册 为一组用户可用的程序。

与 Windows 和 MacOS 不同，GNOME 中，用户菜单从注册了的应用程序列表自动组织。每个发布的应用程序指定其属于的一组类别，系统菜单配置对其进行排序和排列。此机制遵守 freedesktop.org 桌面想和菜单标准。

虽然在其它桌面环境中很普遍，但是不推荐创建自己应用程序的子菜单。而是为您安装的每个程序提供一个菜单项。额外的项，比如帮助文件、README 或者到您网站的链接应该嵌入到应用程序自身中。

在 GNOME 和其它兼容 freedesktop.org 的桌面环境中，应用程序通过 桌面项 注册到桌面菜单，桌面项是一个文本文件，使用 `.desktop` 作为扩展名。此桌面项文件包含了您应用程序的一系列配置。桌面从此文件中提取信息并将其用于：

- 在 Main Menu 中放置应用程序。

- 在 运行应用程序... 对话框中列出应用程序

- 在菜单或桌面上创建适当的启动器。

- 组合应用程序的名称和描述

- 使用合适的图标。

- 识别它支持的 MIME 类型以便打开。

要为您的程序添加菜单项，请创建一个桌面项文件。它应该有一个独特的文件名，并且没有长度限制，所以请避免缩写，可以随便添加商标。然而，不要在文件名中使用空格和国际化字符。例如，"foocorp-painter-pro.desktop" 是一个比 "fcpp.desktop" 好的名称，"FooCorp Painter Pro.desktop" 也不是一个不好的文件名。文件应该是 UTF-8 编码的，并且应该遵守如下模板：

    	[Desktop Entry]
    	Encoding=UTF-8
    	Name=FooCorp Painter Pro
    	Exec=foocorp-painter-pro
    	Icon=foocorp-painter-pro
    	Type=Application
    	Categories=Application;

这些桌面项文件包含应用程序的元数据，在将程序和 GNOME 及其它兼容于标准的桌面环境集成中，起核心作用。此处给出的模板是最基本的。此文件可以包含翻译，以使用用户的本地语言显示程序名。

将这些文件放置在 `/usr/share/applications` 目录(所有用户都可用)，或者 `~/.local/share/applications` 目录(只对单个用户可用)。这应该根据您的程序是安装到整个系统的还是安装到一个用户的主目录。GNOME 监视这些目录的更改，所以只需要简单的将这些文件复制到正确的位置就足够将它们注册到系统。 注意：在 GNOME 2.10 (Fedora Core Linux 上是 2.8)之前不监视 `~/.local/share/applications` 。这些版本使用废弃了的虚拟文件夹标准，所以桌面项文件必须安装到 `~/.gnome2/vfolders/applications`。这个位置在 GNOME 2.10 (Fedora Core Linux 上是 2.8)以后的版本上不受支持，所以，为了最大的兼容性，将这些文件同时放在这两个位置。 注意 KDE 桌面要求一个，以运行 `kbuildsycoca` 来强制刷新菜单。

每个可以工作的桌面项文件需要遵守同样的格式。在 中给出了一个很小的桌面项文件示例。此文件被分为几个节，每部分以方括号扩起来的节描述开始。这个例子中，只有一个节，这是一个将桌面和程序集成的关键节。在每个节中，每行中等号之前的部分是 键，而另一部分是 值。在 中，有对于每一行的解释。

除了标识桌面项文件的第一行，行的顺序并不重要。在 中，`Type=Application` 行是第二行，第五行或者是最后一行都无所谓。

然而，键是区分大小写的。`Type=Application` 与 `type=Application` 或 `TYPE=Application` 并不相同。

#### 桌面项文件示例

    [Desktop Entry]
    Type=Application
    Encoding=UTF-8
    Name=Sample Application Name
    Comment=A sample application
    Exec=application
    Icon=application.png
    Terminal=false

#### 一行行的解释

行 | 解释
--- | ---
`[Desktop Entry]` | 每个桌面项文件的第一行和每节的开头，标识与桌面集成的键值对块，是桌面正确识别文件所必须的。
`Type=Application` | 告诉桌面，这个桌面文件是一个应用程序。这个键的其它有效值有 `Link` 和 `Directory`。
`Encoding=UTF-8` | 描述此桌面文件中的编码
`Name=Sample Application Name` | 主菜单和任何启动器中您的应用程序的名称。
`Comment=A sample application` | 描述这个应用程序。使用的是工具提示。
`Exec=application` | 从 shell 中启动此应用程序的命令，可以有参数。
`Icon=application.png` | 与此应用程序关联的图标名。
`Terminal=false` | 说明程序是否在终端中运行。

#### 启动您的应用程序

如果您的应用程序可以接受命令行参数，可以使用 中说明的字段。

##### Exec 变量

添加... | 接受...
--- | ---
`%f` | 单个文件名
`%F` | 多个文件名
`%u` | 单个 URL。
`%U` | 多个 URL。
`%d` | 单个目录。与 `%f` 结合，用来定位文件。
`%D` | 多个目录。与 `%F` 结合，用来定位文件。
`%n` | 不带路径的单个文件名。
`%N` | 不带路径的多个文件名。
`%k` | 用来表示桌面项文件位置的 URI 或本地文件名。
`%v` | 设备项的名称。

#### 其它语言

要创建一个本地化的名称和注释，需要为每个区域添加行。例如，要添加中国大陆简体中文版的注释，添加如下行：

`Comment[zh_CN]=示例程序`

在文件中，没有翻译行的数目限制。

因为在一个文件中维护一个很长的翻译列表是很笨重的，一种更好的创建这些翻译的方法是使用 intltool 包。查看 intltool-extract 和 intltool-merge 手册页获取更多信息。

#### 指南

桌面项规范 — 创建桌面项文件的规范。

### 安装图标

中，我们已经将此程序的图标指定为 `application.png`。我们需要将那个图标放置在正确的位置。

桌面环境在 `/usr/share/icons/` 中选择的主题目录中查找图标。应用程序图标至少应该是 48x48 像素。将图标放置在 `/usr/share/icons/hicolor/48x48/apps/` 中。如果在选择的主题中没有为您的应用程序找到图标，就从这个目录中寻找。如果有对应于主题的图标，将它们放置在相应的目录中。

为了更好的和 GNOME 桌面进行视觉集成，而同时也让程序在运行在 KDE, Windows XP 或 Mac OS X 时保持本地样式，创建您的艺术效果时，请遵守 Tango 样式方针。这份文档解释了图标设计的多个方面的问题，包括颜色、亮度和大小，同时也提供典型的工作流程和视频教程。

#### 指南

图标主题规范 — 描述如何以可以使用主题的方式安装查找图标。

图标命名规范 — 提供一个典型的图标文件命名方案。

Tango 样式方针 — 解释如何设计清晰和多平台的图标。

### 添加 MIME 类型

如果您的程序可以打开指定的 MIME 类型，您需要在桌面项文件中告知桌面环境。例如，如果您的应用程序可以接受 PNG，向您的桌面项文件中添加如下行：

    MimeType=image/png

可以通过分号分隔来添加另外的 MIME 类型。

系统已经知晓了大量的 MIME 类型。然而，如果您创建了一个您自己的，你需要向 MIME 数据库注册您的 MIME 类型。在 `/usr/share/mime/packages/` 文件夹中，使用 中给出的格式创建一个 XML 文件。

#### 注册新 MIME 类型的示例文件

    <?xml version="1.0" encoding="UTF-8"?>
    <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
       <mime-type type="application/x-样例">
         <comment>Example file type </comment>
         <magic priority="50">
           <match value="搜索字符串" type="string" offset="10:140"/>
         </magic>
         <glob pattern="*.新扩展名"/>
       </mime-type>
    </mime-info>

这个例子中，使用您自己的 MIME 类型替换例子中的 MIME 类型。magic 部分搜索文件以获取标识用的字符串。glob 行使用文件名的后缀来标识。

因为 `magic` 命令强制计算机打开文件以搜索字符串，所以 `glob` 命令是更好的选择。

文件中描述的新 MIME 类型适配好之后，在 shell 中运行如下命令：

    update-mime-database·/usr/share/mime

关于选择一个适当的 MIME 扩展名和注册 MIME 类型的更多信息，请移步 IANA 网站。

#### 指南

共享的 MIME 信息规范 — 详细说明 MIME 注册系统。

## 桌面深度集成

本章包含将软件与 GNOME 桌面更好集成所需要做的一系列需要更多的工作。例如，GNOME 可以在程序启动时显示反馈，您可以在 看到怎样启用这个反馈。如果您的软件创建文档或其它可显示的数据，您可以安装缩略图工具，以便让 GNOME 文件管理器创建您的程序指定的缩略图。

### 启动时提示

虽然 中显示的内容提供了让桌面识别您的程序的足够信息，但是还有一些其它内容在您的特定情况下可能会对您有用。这些内容中的一项就是 启动时提示。

设置了启动时提示时，面板和光标提示用户程序已经启动，当程序出现在屏幕上时，面板和光标恢复正常。

要让启动器知道您的程序支持启动时提示，向您的桌面文件添加如下行：

`StartupNotify=true`

桌面项文件中的命令行允许桌面环境使用任何启动时提示，无论是内建在程序中还是工具集中。多数现代的工具集透明和启动时提示系统配合。如果您没有使用现代的工具集，启动时提示规范 中有怎样自己实现的细节。

无论何种工具集，都有之中类型的应用程序您必须手动处理反馈。具有远程能力(让现有进程打开一个新窗口，而不是启动一个新进程)不能使用内置机制。DESKTOP_LAUNCH_ID 环境的值必须由您的程序传递并且让它通知新窗口的启动系统。如果您使用 GTK+，`gdk_notify_startup_complete()` 的文档有写更多的信息。

#### 指南

启动时提示协议 — 描述了在 X 窗口系统中启动时提示的实现细节。

### 安装缩略图程序

GNOME 文件管理器，Nautilus，可以为每个文件显示小的特制缩略图，而不是在文件列表中的通用图标。例如，字处理文档可以显示为文档中首页的某种形式。因为用户可以看到文件中的小部分数据，可能可以帮助用户想起那个是他们在找的文件，所以这是有用的。您可以使用几个简单的步骤让您的程序创建这些缩略图。

缩略图程序 是一个没有用户界面的程序，它使用一个文件和一个像素尺寸作为输出，然后为那个文件写入缩略图。GNOME 根据要生成缩略图的文件的 MIME 类型决定使用哪个缩略图程序。MIME 类型和缩略图程序的影射存储为一系列的 GConf 键。

对于每个想要处理的 MIME 类型，您必须创建一对 GConf 键：

`/desktop/gnome/thumbnailers/application@x-foo/enable`

  类型：boolean。决定是否运行此缩略图程序。您可以启用或禁用每个缩略图程序。当您安装一个新缩略图程序时，当然应该将这个键的值设置为 true。

`/desktop/gnome/thumbnailers/application@x-foo/command`

  类型：字符串。GNOME 需要为 application@x-foo 文件生成缩略图时运行的命令。例如，值可以是 "`application-x-foo-thumbnailer %i %o %s`"。查看下边关于百分号的解释。

也就是，每个 MIME 类型需要同路径下的两个 GConf 键 (`enable` 和 `command`)。路径名可以通过将 MIME 类型名中的 `/` 替换为 `@` 得到。例如，`image/x-my-format` 的缩略图程序需要两个键：`/desktop/gnome/thumbnailers/image@x-my-format/enable` 和 `/desktop/gnome/thumbnailers/image@x-my-format/command`。

在 `command` 键中，GNOME 将查找当前的序列并将其替换为实际的值：

`%i` | 输入文件名。这是您的缩略图程序需要读取的文件。
`%u` | 输入 URI。如果您的缩略图程序可以处理 URI，而不是纯文件名，使用 `%u` 代替 `%i`。
`%o` | 输出文件名。这是您的缩略图程序应该以 PNG 格式写入的缩略图文件。
`%s` | 单个整数形式的缩略图的尺寸。例如，如果被替换为 `128`，它意味着您的缩略图程序不应该输出大于 128×128 像素的图像。

`%i` 和 `%u` 中的一个必须出现在您的命令中，并且 `%o` 也是必须有的。`%s` 替代项是可选的，但是我们推荐您的缩略图程序对其进行关注。

#### 附加信息

对于更多的配置选项，您可以打开 boolean 键 `/desktop/gnome/thumbnailers/disable_all` 以禁止生成缩略图。

## 集成检查清单

本附录提供了一个本指南提供的多个任务的检查项。您可以使用这个检查项确定您的软件已经以基本的方法集成到了 GNOME，同时也是更多集成工作计划的资源。

1. 您的应用程序出现在 GNOME 面板的菜单中了吗？

2. 您的程序是否在菜单或面板上有图标？如果有，它使用提前制作好的多个大小还是一个可伸缩的 SVG？

3. 如果您的程序可以加载活保存文件，它注册到它可以处理的 MIME 类型了吗？

4. 您的应用程序为文件管理器提供 MIME 图标了吗？

5. 您的应用程序提供启动提示，以便 GNOME 可以在您的程序启动时提示用户吗？

6. 如果您的应用程序创建“可显示的”文档，它为文件管理器安装缩略图了吗？

## 致谢

非常感谢 Jakub Steiner 为本指南的 HTML 版提供了一份漂亮的 CSS 样式表！