548 lines
39 KiB
HTML
548 lines
39 KiB
HTML
<!doctype html>
|
||
<html class="no-js">
|
||
<head><meta charset="utf-8"/>
|
||
<meta name="viewport" content="width=device-width,initial-scale=1"/>
|
||
<meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
<link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" /><link rel="next" title="Developer Documentation Style Guidelines" href="../devel-docs.html" /><link rel="prev" title="Parallel Installability" href="parallel-installability.html" />
|
||
|
||
<meta name="generator" content="sphinx-4.3.0, furo 2022.06.21"/>
|
||
<title>Integrating with GNOME - GNOME Developer Documentation</title>
|
||
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
|
||
<link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=40978830699223671f4072448e654b5958f38b89" />
|
||
<link rel="stylesheet" type="text/css" href="../../_static/tabs.css" />
|
||
<link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
|
||
<link rel="stylesheet" type="text/css" href="../../_static/gnome.css" />
|
||
|
||
|
||
|
||
|
||
<style>
|
||
body {
|
||
--color-code-background: #f8f8f8;
|
||
--color-code-foreground: black;
|
||
--color-brand-primary: #4a86cf;
|
||
--color-brand-content: #4a86cf;
|
||
|
||
}
|
||
@media not print {
|
||
body[data-theme="dark"] {
|
||
--color-code-background: #202020;
|
||
--color-code-foreground: #d0d0d0;
|
||
|
||
}
|
||
@media (prefers-color-scheme: dark) {
|
||
body:not([data-theme="light"]) {
|
||
--color-code-background: #202020;
|
||
--color-code-foreground: #d0d0d0;
|
||
|
||
}
|
||
}
|
||
}
|
||
</style></head>
|
||
<body>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-toc" viewBox="0 0 24 24">
|
||
<title>Contents</title>
|
||
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
|
||
<path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-menu" viewBox="0 0 24 24">
|
||
<title>Menu</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
|
||
<line x1="3" y1="12" x2="21" y2="12"></line>
|
||
<line x1="3" y1="6" x2="21" y2="6"></line>
|
||
<line x1="3" y1="18" x2="21" y2="18"></line>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
|
||
<title>Expand</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
|
||
<polyline points="9 18 15 12 9 6"></polyline>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24">
|
||
<title>Light mode</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24">
|
||
<title>Dark mode</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24">
|
||
<title>Auto light/dark mode</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
|
||
<circle cx="12" cy="12" r="9" />
|
||
<path d="M13 12h5" />
|
||
<path d="M13 15h4" />
|
||
<path d="M13 18h1" />
|
||
<path d="M13 9h4" />
|
||
<path d="M13 6h1" />
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
|
||
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
|
||
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
|
||
<label class="overlay sidebar-overlay" for="__navigation"></label>
|
||
<label class="overlay toc-overlay" for="__toc"></label>
|
||
|
||
|
||
|
||
<div class="page">
|
||
<header class="mobile-header">
|
||
<div class="header-left">
|
||
<label class="nav-overlay-icon" for="__navigation">
|
||
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
|
||
</label>
|
||
</div>
|
||
<div class="header-center">
|
||
<a href="../../index.html"><div class="brand">GNOME Developer Documentation</div></a>
|
||
</div>
|
||
<div class="header-right">
|
||
<label class="toc-overlay-icon toc-header-icon" for="__toc">
|
||
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
|
||
</label>
|
||
</div>
|
||
</header>
|
||
<aside class="sidebar-drawer">
|
||
<div class="sidebar-container">
|
||
|
||
<div class="sidebar-sticky"><a class="sidebar-brand" href="../../index.html">
|
||
|
||
|
||
<span class="sidebar-brand-text">GNOME Developer Documentation</span>
|
||
|
||
</a><form class="sidebar-search-container" method="get" action="../../search.html" role="search">
|
||
<input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
|
||
<input type="hidden" name="check_keywords" value="yes">
|
||
<input type="hidden" name="area" value="default">
|
||
</form>
|
||
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
|
||
<p class="caption" role="heading"><span class="caption-text">Contents</span></p>
|
||
<ul class="current">
|
||
<li class="toctree-l1 has-children"><a class="reference internal" href="../../introduction.html">Platform Introduction</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
|
||
<li class="toctree-l2 has-children"><a class="reference internal" href="../../introduction/components.html">Platform Components</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="../../introduction/overview/libraries.html">Libraries</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="../../introduction/overview/services.html">Services</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../introduction/languages.html">Programming Languages</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../introduction/builder.html">GNOME Builder</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../introduction/flatpak.html">Flatpak</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1 current has-children"><a class="reference internal" href="../../guidelines.html">Guidelines</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current">
|
||
<li class="toctree-l2 has-children"><a class="reference internal" href="../programming.html">Programming Guidelines</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" role="switch" type="checkbox"/><label for="toctree-checkbox-4"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="../programming/coding-style.html">C Coding Style</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="../programming/memory-management.html">Managing Memory</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="../programming/writing-good-code.html">The Importance of Writing Good Code</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="../programming/optimizing.html">Optimizing GNOME Applications</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="../programming/namespacing.html">Namespacing</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="../programming/introspection.html">Introspection</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2 has-children"><a class="reference internal" href="../accessibility.html">Accessibility</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" role="switch" type="checkbox"/><label for="toctree-checkbox-5"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="../accessibility/coding-guidelines.html">Coding Guidelines for Supporting Accessibility</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="../accessibility/custom-widgets.html">Making Custom Components Accessible</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2 has-children"><a class="reference internal" href="../localization.html">Localization</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" role="switch" type="checkbox"/><label for="toctree-checkbox-6"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="../localization/practices.html">Best Practices for Localization</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2 current has-children"><a class="reference internal" href="../maintainer.html">Maintainer Guidelines</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" role="switch" type="checkbox"/><label for="toctree-checkbox-7"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current">
|
||
<li class="toctree-l3"><a class="reference internal" href="api-stability.html">API Stability</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="parallel-installability.html">Parallel Installability</a></li>
|
||
<li class="toctree-l3 current current-page"><a class="current reference internal" href="#">Integrating with GNOME</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../devel-docs.html">Developer Documentation Style Guidelines</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1 has-children"><a class="reference internal" href="../../tutorials.html">Tutorials</a><input class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" role="switch" type="checkbox"/><label for="toctree-checkbox-8"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
|
||
<li class="toctree-l2 has-children"><a class="reference internal" href="../../tutorials/beginners.html">Beginners Tutorials</a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" role="switch" type="checkbox"/><label for="toctree-checkbox-9"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
|
||
<li class="toctree-l3 has-children"><a class="reference internal" href="../../tutorials/beginners/getting_started.html">Getting Started</a><input class="toctree-checkbox" id="toctree-checkbox-10" name="toctree-checkbox-10" role="switch" type="checkbox"/><label for="toctree-checkbox-10"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/getting_started/content_view.html">Adding A Content View</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/getting_started/opening_files.html">Loading Content From A File</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/getting_started/cursor_position.html">Showing The Cursor Position</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/getting_started/saving_files.html">Saving The Content To A File</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/getting_started/saving_state.html">Saving The Application State</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/getting_started/adding_toasts.html">Notifying The User With Toasts</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/getting_started/dark_mode.html">Forcing The Dark Color Scheme</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l3 has-children"><a class="reference internal" href="../../tutorials/beginners/components.html">UI components</a><input class="toctree-checkbox" id="toctree-checkbox-11" name="toctree-checkbox-11" role="switch" type="checkbox"/><label for="toctree-checkbox-11"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/window.html">Windows</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/image.html">Images</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/label.html">Labels</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/button.html">Buttons</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/box.html">Boxes</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/stack.html">Stacks</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/leaflet.html">Leaflets</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/toggle.html">Toggles</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/check_box.html">Check Boxes</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/radio_button.html">Radio Buttons</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/spin_button.html">Spin Buttons</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/link_button.html">Link Buttons</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/switch.html">Switches</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/menu_button.html">Menu Buttons</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/entry.html">Entries</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/password_entry.html">Password Entries</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/message_dialog.html">Messages</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/file_dialog.html">File Dialogs</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/spinner.html">Spinners</a></li>
|
||
<li class="toctree-l4"><a class="reference internal" href="../../tutorials/beginners/components/level_bar.html">Level Bars</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/application-id.html">Application ID</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/application.html">Using GtkApplication</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/save-state.html">Saving and Loading Window State</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/notifications.html">Using Notifications</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/themed-icons.html">Themed Icons</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/deprecations.html">Dealing With Deprecations</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/actions.html">Actions</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/menus.html">Menus</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/search-provider.html">Writing a Search Provider</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/pre-and-post-conditions.html">Pre- and Post-Conditions</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/main-contexts.html">Main Contexts</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/lists.html">Using GLib Lists</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/threading.html">Threading</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/asynchronous-programming.html">Asynchronous Programming</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/drag-and-drop.html">Drag and Drop</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="../../tutorials/widget-templates.html">Widget Templates</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</aside>
|
||
<main class="main">
|
||
<div class="content">
|
||
<article role="main">
|
||
<label class="toc-overlay-icon toc-content-icon" for="__toc">
|
||
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
|
||
</label>
|
||
<section id="integrating-with-gnome">
|
||
<h1>Integrating with GNOME<a class="headerlink" href="#integrating-with-gnome" title="Permalink to this headline">#</a></h1>
|
||
<p>GNOME is a project to build a complete desktop and development platform based
|
||
entirely on free software. Many companies, governments, schools, institutions,
|
||
and individuals have deployed the GNOME desktop on their systems. If you are a
|
||
developer of third-party software (“Independent Software Vendor” or ISV, or
|
||
“Independent Software Developer” (ISD) if you don’t do it commercially), you
|
||
may want to ensure that your existing software runs properly under GNOME. This
|
||
guide explains how to integrate existing software with GNOME, without actually
|
||
rewriting that software to explicitly use the GNOME platform libraries and
|
||
development tools.</p>
|
||
<p>This guide will be useful in the following situations:</p>
|
||
<ul class="simple">
|
||
<li><p>You are a software developer or distributor who has an application that is not
|
||
explicitly designed to work with GNOME, but you want to ensure that it runs
|
||
comfortably within a GNOME desktop.</p></li>
|
||
<li><p>You are a system administrator for an institution that has deployed GNOME
|
||
desktops to its users. You also have legacy or in-house applications, and you
|
||
want your users of GNOME to be able to access those applications comfortably.</p></li>
|
||
<li><p>You are writing a GNOME application proper and you need a checklist of basic
|
||
things to do to ensure that your application integrates well with the rest of
|
||
the GNOME desktop.</p></li>
|
||
</ul>
|
||
<p>In general, this guide is about integrating existing software into a GNOME
|
||
desktop. On the other hand, if you are considering writing new software, we
|
||
encourage you to develop it completely with GNOME as your target platform;
|
||
please refer to the GNOME Developer’s Site for more information.</p>
|
||
<p>One of the main concerns of GNOME is the user experience. Users should have a
|
||
comfortable computing environment: this means having a complete desktop and a
|
||
set of applications which operate together in a consistent way. With relatively
|
||
little work, applications which are not written explicitly with GNOME in mind
|
||
can be made to run comfortably within a GNOME desktop.</p>
|
||
<section id="basic-integration">
|
||
<h2>Basic integration<a class="headerlink" href="#basic-integration" title="Permalink to this headline">#</a></h2>
|
||
<section id="desktop-files">
|
||
<h3>Desktop files<a class="headerlink" href="#desktop-files" title="Permalink to this headline">#</a></h3>
|
||
<p>To run applications from GNOME, users click on icons on their desktops or they
|
||
select the applications which they want to run from the applications grid.
|
||
Therefore, the first step in integrating an existing program with GNOME is to
|
||
register it with the set of applications that users can run.</p>
|
||
<p>The applications grid is automatically constructed from the list of registered
|
||
applications.</p>
|
||
<p>In GNOME and other freedesktop.org-compliant desktops, an application gets
|
||
registered into the desktop’s menus through a desktop entry, which is a text
|
||
file with <code class="docutils literal notranslate"><span class="pre">.desktop</span></code> extension. This desktop file contains a listing of the
|
||
configurations for your application. The desktop takes the information in this
|
||
file and uses it to:</p>
|
||
<ul class="simple">
|
||
<li><p>associate the name, description, and icon of the application</p></li>
|
||
<li><p>associate each window created by the application with the same name and icon</p></li>
|
||
<li><p>recognize the MIME types it supports for opening files</p></li>
|
||
</ul>
|
||
<p>To register your application, create a desktop file using the same
|
||
application identifier you chose for your application and the <code class="docutils literal notranslate"><span class="pre">.desktop</span></code> file
|
||
extension.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>For more information about the application identifier, please see the
|
||
<a class="reference internal" href="../../tutorials/application-id.html"><span class="doc">Application ID</span></a> tutorial.</p>
|
||
</div>
|
||
<p>A typical desktop file will have the following structure:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">Desktop</span> <span class="n">Entry</span><span class="p">]</span>
|
||
<span class="n">Name</span><span class="o">=</span><span class="n">Your</span> <span class="n">Application</span>
|
||
<span class="n">Comment</span><span class="o">=</span><span class="n">An</span> <span class="n">amazing</span> <span class="n">application</span>
|
||
<span class="n">Exec</span><span class="o">=</span><span class="n">your</span><span class="o">-</span><span class="n">application</span>
|
||
<span class="n">Icon</span><span class="o">=</span><span class="n">com</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">YourApplication</span>
|
||
<span class="n">Keywords</span><span class="o">=</span><span class="n">various</span><span class="p">;</span><span class="n">keywords</span><span class="p">;</span><span class="n">describing</span><span class="p">;</span><span class="n">your</span><span class="p">;</span><span class="n">application</span><span class="p">;</span>
|
||
<span class="n">StartupNotify</span><span class="o">=</span><span class="n">true</span>
|
||
<span class="n">Terminal</span><span class="o">=</span><span class="n">false</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Some keys in your desktop files can be localized in different languages, like
|
||
the <code class="docutils literal notranslate"><span class="pre">Name</span></code>, <code class="docutils literal notranslate"><span class="pre">Comment</span></code>, <code class="docutils literal notranslate"><span class="pre">GenericName</span></code>, and <code class="docutils literal notranslate"><span class="pre">Keywords</span></code> keys. By localizing
|
||
your desktop file you allow users from different parts of the world to find your
|
||
application more easily.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>For more information about the format of the desktop files, please visit
|
||
the <a class="reference external" href="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">Freedesktop.org Desktop Entry specification</a>.</p>
|
||
</div>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>You should ensure that your desktop file is valid as part of your project’s
|
||
test suite. You can use the <code class="docutils literal notranslate"><span class="pre">desktop-file-validate</span></code> utility provided by the
|
||
<a class="reference external" href="https://www.freedesktop.org/wiki/Software/desktop-file-utils/">desktop-file-utils project</a></p>
|
||
</div>
|
||
<p>Your desktop file should be installed under one of the <code class="docutils literal notranslate"><span class="pre">applications</span></code>
|
||
directories of the <code class="docutils literal notranslate"><span class="pre">XDG_DATA_DIRS</span></code> or <code class="docutils literal notranslate"><span class="pre">XDG_DATA_HOME</span></code> environment variables,
|
||
depending on the installation prefix. For system installations, the former
|
||
typically means <code class="docutils literal notranslate"><span class="pre">/usr/share/applications</span></code>; for user installations, the latter
|
||
is typically <code class="docutils literal notranslate"><span class="pre">$HOME/.local/share/applications</span></code>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>For more information about the XDG directories, please visit the
|
||
<a class="reference external" href="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">Freedesktop.org Base Directories specification</a></p>
|
||
</div>
|
||
</section>
|
||
<section id="icons">
|
||
<h3>Icons<a class="headerlink" href="#icons" title="Permalink to this headline">#</a></h3>
|
||
<p>Application icons should be installed following the <a class="reference external" href="https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html">Freedesktop.org Icon Theme
|
||
specification</a>.
|
||
For GNOME applications, you should provide</p>
|
||
<ul class="simple">
|
||
<li><p>a full color scalable icon using the SVG format</p></li>
|
||
</ul>
|
||
<p><strong>OR</strong></p>
|
||
<ul class="simple">
|
||
<li><p>a full color, 256×256 pixels raster icon using the PNG format</p></li>
|
||
</ul>
|
||
<p>You should also, optionally, provide a symbolic icon using the SVG format.</p>
|
||
<p>You should install your icon under the <code class="docutils literal notranslate"><span class="pre">hicolor</span></code> icon theme namespace, using
|
||
the application identifier as the base name for the icon; for instance:</p>
|
||
<ol class="arabic simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/share/icons/hicolor/256x256/apps/com.example.YourApplication.png</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/share/icons/hicolor/scalable/apps/com.example.YourApplication.svg</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/share/icons/hicolor/symbolic/apps/com.example.YourApplication-symbolic.svg</span></code></p></li>
|
||
</ol>
|
||
</section>
|
||
</section>
|
||
<section id="advanced-integration">
|
||
<h2>Advanced integration<a class="headerlink" href="#advanced-integration" title="Permalink to this headline">#</a></h2>
|
||
<section id="d-bus-activation">
|
||
<h3>D-Bus activation<a class="headerlink" href="#d-bus-activation" title="Permalink to this headline">#</a></h3>
|
||
<p>Instead of the typical UNIX-style <code class="docutils literal notranslate"><span class="pre">fork()</span></code>/<code class="docutils literal notranslate"><span class="pre">exec()</span></code> approach to process
|
||
creation, launching an application in GNOME is preferably done by sending a
|
||
D-Bus message to the well-known name of that application, causing a D-Bus
|
||
activation. In the case that the application is already running, it can respond
|
||
to the message by opening a new window or raising its existing window, instead
|
||
of launching a new instance.</p>
|
||
<p>Starting processes with D-Bus activation ensures that each application gets
|
||
started in its own pristine environment, as a direct descendent of the
|
||
session, not in the environment of whatever its parent happened to be. This is
|
||
important for ensuring the app ends up in the correct <code class="docutils literal notranslate"><span class="pre">cgroup</span></code>, for example.</p>
|
||
<p>Another reason is that being D-Bus activatable is a prerequisite for using
|
||
persistent notifications.</p>
|
||
<p>In order for D-Bus to know how to activate your service, you need to install a
|
||
D-Bus service file under <code class="docutils literal notranslate"><span class="pre">/usr/share/dbus-1/services</span></code>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">D</span><span class="o">-</span><span class="n">BUS</span> <span class="n">Service</span><span class="p">]</span>
|
||
<span class="n">Name</span><span class="o">=</span><span class="n">com</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">YourApplication</span>
|
||
<span class="n">Exec</span><span class="o">=/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">your</span><span class="o">-</span><span class="n">app</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>You will also need to add the following key to your application’s desktop file:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">DBusActivatable</span><span class="o">=</span><span class="n">true</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If <code class="docutils literal notranslate"><span class="pre">DBusActivatable</span></code> is true and the desktop file name looks like a valid
|
||
application ID, then the <code class="docutils literal notranslate"><span class="pre">Exec</span></code> line will be ignored and your application will
|
||
be started by way of D-Bus activation instead (using the name of the desktop
|
||
file minus the <code class="docutils literal notranslate"><span class="pre">.desktop</span></code> extension as the application ID).</p>
|
||
</section>
|
||
<section id="mime-types">
|
||
<h3>MIME types<a class="headerlink" href="#mime-types" title="Permalink to this headline">#</a></h3>
|
||
<p>If your application can open specific MIME types, you need to let the desktop
|
||
know in the desktop file. For example, if your application can accept PNG files,
|
||
add the following line into your desktop file:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">MimeType</span><span class="o">=</span><span class="n">image</span><span class="o">/</span><span class="n">png</span><span class="p">;</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Additional MIME types can be added by separating the different types with
|
||
semicolons.</p>
|
||
</div>
|
||
<p>You will also need to add <code class="docutils literal notranslate"><span class="pre">%F</span></code> as argument to your <code class="docutils literal notranslate"><span class="pre">Exec</span></code> line if your
|
||
application supports opening multiple files at once, or <code class="docutils literal notranslate"><span class="pre">%f</span></code> if it only
|
||
supports opening one file at a time, which will open multiple instances of
|
||
your application when opening a selection of files that your application
|
||
supports.</p>
|
||
<p>The system already knows of a large number of MIME types. However, if you are
|
||
creating one of your own, you need to register your MIME type into the MIME
|
||
database, by creating an XML file in the <code class="docutils literal notranslate"><span class="pre">/usr/share/mime/packages</span></code> directory:</p>
|
||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
|
||
<span class="nt"><mime-info</span> <span class="na">xmlns=</span><span class="s">"http://www.freedesktop.org/standards/shared-mime-info"</span><span class="nt">></span>
|
||
<span class="nt"><mime-type</span> <span class="na">type=</span><span class="s">"application/x-example"</span><span class="nt">></span>
|
||
<span class="nt"><comment></span>Example file type <span class="nt"></comment></span>
|
||
<span class="nt"><magic</span> <span class="na">priority=</span><span class="s">"50"</span><span class="nt">></span>
|
||
<span class="nt"><match</span> <span class="na">value=</span><span class="s">"search-string"</span> <span class="na">type=</span><span class="s">"string"</span> <span class="na">offset=</span><span class="s">"10:140"</span><span class="nt">/></span>
|
||
<span class="nt"></magic></span>
|
||
<span class="nt"><glob</span> <span class="na">pattern=</span><span class="s">"*.newextension"</span><span class="nt">/></span>
|
||
<span class="nt"></mime-type></span>
|
||
<span class="nt"></mime-info></span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>To avoid collisions with files added by other applications, you should use
|
||
your application’s ID as the basename for the file, e.g.
|
||
<code class="docutils literal notranslate"><span class="pre">com.example.YourApplication.xml</span></code></p>
|
||
</div>
|
||
<p>In this example, replace the example MIME type with the name of your MIME type.
|
||
The <code class="docutils literal notranslate"><span class="pre">magic</span></code> rule searches the contents of the file for the given string for
|
||
identification. The <code class="docutils literal notranslate"><span class="pre">glob</span></code> rule uses the suffix of file names for
|
||
identification.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Because the <code class="docutils literal notranslate"><span class="pre">magic</span></code> rule forces the computer to open the files to search
|
||
for the string, the <code class="docutils literal notranslate"><span class="pre">glob</span></code> rule is preferable.</p>
|
||
</div>
|
||
<p>Once your new MIME type is adequately described in the file, run the following
|
||
in a shell:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">update</span><span class="o">-</span><span class="n">mime</span><span class="o">-</span><span class="n">database</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">share</span><span class="o">/</span><span class="n">mime</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition tip">
|
||
<p class="admonition-title">Tip</p>
|
||
<p>For more information on choosing a good MIME extension and to register your
|
||
MIME type, go to the <a class="reference external" href="http://www.iana.org/form/media-types">IANA website</a>.</p>
|
||
</div>
|
||
</section>
|
||
<section id="uri-schemes-handling">
|
||
<h3>URI schemes handling<a class="headerlink" href="#uri-schemes-handling" title="Permalink to this headline">#</a></h3>
|
||
<p>If your application can open specific URI schemes, you need to let the desktop
|
||
know in the desktop file. For example, if your application can accept mailto: URIs,
|
||
you need to add the corresponding x-scheme-handler/mailto to the MIME types in the
|
||
desktop file, as done in the previous section. You can use any URI scheme you want,
|
||
not just the common ones like mailto/http/https/ftp, for example the gemini:// URI
|
||
scheme.</p>
|
||
<p>You also need to use %u or %U for respectively one or several URIs, the same way it
|
||
was done with %f and %F in the previous section. If your app handles MIME types in
|
||
addition to URIs, you only need to use the %u or %U version, no need to use %f and %F.</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
</article>
|
||
<footer>
|
||
|
||
<div class="related-pages">
|
||
<a class="next-page" href="../devel-docs.html">
|
||
<div class="page-info">
|
||
<div class="context">
|
||
<span>Next</span>
|
||
</div>
|
||
<div class="title">Developer Documentation Style Guidelines</div>
|
||
</div>
|
||
<svg><use href="#svg-arrow-right"></use></svg>
|
||
</a>
|
||
<a class="prev-page" href="parallel-installability.html">
|
||
<svg><use href="#svg-arrow-right"></use></svg>
|
||
<div class="page-info">
|
||
<div class="context">
|
||
<span>Previous</span>
|
||
</div>
|
||
|
||
<div class="title">Parallel Installability</div>
|
||
|
||
</div>
|
||
</a>
|
||
</div>
|
||
|
||
</footer>
|
||
|
||
</div>
|
||
<aside class="toc-drawer">
|
||
|
||
|
||
<div class="toc-sticky toc-scroll">
|
||
<div class="toc-title-container">
|
||
<span class="toc-title">
|
||
Contents
|
||
</span>
|
||
</div>
|
||
<div class="toc-tree-container">
|
||
<div class="toc-tree">
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Integrating with GNOME</a><ul>
|
||
<li><a class="reference internal" href="#basic-integration">Basic integration</a><ul>
|
||
<li><a class="reference internal" href="#desktop-files">Desktop files</a></li>
|
||
<li><a class="reference internal" href="#icons">Icons</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#advanced-integration">Advanced integration</a><ul>
|
||
<li><a class="reference internal" href="#d-bus-activation">D-Bus activation</a></li>
|
||
<li><a class="reference internal" href="#mime-types">MIME types</a></li>
|
||
<li><a class="reference internal" href="#uri-schemes-handling">URI schemes handling</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</aside>
|
||
</main>
|
||
</div><script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
|
||
<script src="../../_static/jquery.js"></script>
|
||
<script src="../../_static/underscore.js"></script>
|
||
<script src="../../_static/doctools.js"></script>
|
||
<script src="../../_static/scripts/furo.js"></script>
|
||
</body>
|
||
</html> |