# Integrace existujícího software s GNOME

## Předmluva

GNOME je projekt, jehož cílem je vytvořit kompletní prostředí pracovní plochy a vývojovou platformu, obojí založené na svobodném software. Mnoho společností, vlád, škol, institucí a jednotlivců používá pracovní prostředí GNOME na svých počítačích. Pokud jste vývojářem software v pozici třetí strany ("Nezávislý dodavatel software" alias ISV nebo "Nezávislý vývojář software" alias ISD), jistě chcete mít jistotu, že váš software pracuje s GNOME správně. Tato příručka vysvětluje, jak integrovat existující software do prostředí GNOME, aniž by bylo nutno software přímo upravovat za účelem použití knihoven s vývojářských nástrojů platformy GNOME.

Tuto příručku využijete v těchto případech:

- Jste vývojář nebo distributor software, který není přímo určen pro běh v prostředí GNOME, ale chcete mít jistotu, že vaše aplikace budou v pořádku v GNOME fungovat.

- Jste správce v instituci, která pro své uživatele zvolila pracovní prostředí GNOME. Zároveň používáte specifické aplikace a chcete, aby uživatelé GNOME byli schopni s těmito aplikacemi pohodlně pracovat.

- Píšete novou aplikaci pro GNOME a potřebujete vědět, jaké základní věci je potřeba udělat, aby se váš software v pořádku integroval se zbytkem pracovního prostředí GNOME.

Obecně je tato příručka věnována integraci existujícího software do pracovního prostředí GNOME. Na druhou stranu, pokud uvažujete o napsání nového software, podporujeme vás ve volbě GNOME jako cílové platformy; Více informací naleznete v dokumentu GNOME Developer's Site.

Jedním z nejdůležitějších zájmů GNOME je zážitek uživatele, který by měl mít komfortní počítačové prostředí: to znamená mít komplexní pracovní prostředí a sadu aplikací, které vzájemně konzistentně spolupracují. S vynaložením relativně malého úsilí mohou být aplikace, které nejsou původně napsány s ohledem na GNOME, pohodlně provozovány v prostředí GNOME.

### Struktura příručky

Tato příručka je koncipována jako seznam úkonů, které je nutné provést, aby se existující software integroval s GNOME. Jednotlivé body jsou uspořádány dle důležitosti, například přidání aplikace do hlavní nabídky GNOME je uvedeno před přidáním podpory pro přetahování. Také je připojen dodatek se seznamem úkonů, který vám má pomoci se zhodnocením integrace na integraci.

### Standardy a freedesktop.org

Mnoho úkonů integrace z této příručky souvisí se standardy, které se nevztahují jen ke GNOME. Jiná pracovní prostředí, například K Desktop Environment, tyto standardy také využívají: pokud integrujete svoji aplikaci s GNOME, budete později muset udělat jen málo, nebo dokonce nic, abyste zajistili bezproblémový běh i v ostatních prostředích.

Vytvoření dokonalé aplikace přináší úžasný pocit. Ať je malá nebo velká, chcete, aby vaši aplikaci pracovní prostředí rozpoznalo a fungovalo s ní bez problémů. V situaci, kdy existuje několik pracovních prostředí je nejlepší, aby se vaše aplikace dokázala integrovat s co možná největším počtem. I když nebyla zatím přijata žádná oficiální pravidla, zde je seznam dostupných specifikací projektu freedesktop.org.

I když se formálně nejedná o standard, snaží se freedesktop.org udržovat seznam neoficiálních ale obecně přijatých doporučení. Pokud se jimi budete řídit, zajistí to vaší aplikaci integraci s pracovními prostředími, která jsou na těchto zásadách založena.

## Základní integrace

Tato kapitola vás poučí o základních krocích, které byste měli provést za účelem integrace s pracovním prostředím GNOME. Tyto kroky mají za cíl:

- Umožnit uživateli spouštět aplikaci tím, že zařídíte její zobrazení v hlavní nabídce nebo jiném mechanismu spouštění, které pracovní prostředí nabízí.

- Umožnit pracovnímu prostředí zjistit, pro jaké typy souborů vytvořené uživatelem je potřeba spustit jakou aplikaci.

- Umožnit pracovnímu prostředí zjistit, jaké ikony náležející programu zobrazit a jaké soubory váš program vytváří.

### Soubory plochy: vložení aplikace do hlavní nabídky prostředí

Aplikace v GNOME uživatelé klepnou na ikonu na pracovní ploše nebo zvolí požadovanou aplikaci z hlavní nabídky. Proto je prvním krokem integrace existujícího programu s GNOME jeho registrace v sadě aplikací, které uživatelé mohou spustit.

Na rozdíl od Windows nebo MacOS jsou v GNOME nabídky sestavovány automaticky ze seznamu registrovaných aplikací. Každá takto publikovaná aplikace uvádí sadu kategorií, do kterých patří, a při sestavování nabídky jej systém zatřídí a umístí. Mechanismus pracuje dle standardu freedesktop.org pro položky plochy a nabídky.

Vzhledem ke zvyku ostatních prostředí se nedoporučuje vytvářet pro aplikaci vlastní podnabídku. Namísto toho vytvořte pro každou dodávanou aplikaci jednu položku. Další věci jako nápověda, soubory README nebo odkazy na WWW stránky by měly být dostupné ze samotné aplikace.

V GNOME a jiných prostředích vycházejících ze standardů freedesktop.org jsou aplikace registrovány do hlavní nabídky pomocí položky plochy, což je textový soubor s příponou `.desktop`. Tento soubor plochy obsahuje potřebnou konfiguraci pro integraci aplikace. Pracovní prostředí přebírá informace z tohoto souboru a používá je k:

- vložení aplikace do hlavní nabídky.

- uvedení aplikace v seznamu okna Spustit aplikaci...

- vytvoření příslušných spouštěčů v nabídce a na pracovní ploše

- asociování jména a popisu aplikace

- použití příslušné ikony.

- rozpoznání typů MIME, které aplikace podporuje, při otevírání souborů.

Pokud chcete přidat záznam v nabídce pro svoji aplikaci, vytvořte soubor plochy. Ten by měl mít unikátní název a vzhledem k tomu, že délka názvu není omezena, vyvarujte se zkratek a klidně použijte název celý. V žádném případě však do názvu nevkládejte mezery nebo znaky specifické pro jiný jazyk. Název "foocorp-painter-pro.desktop" je dobrý na rozdíl od "fcpp.desktop" nebo "FooCorp Painter Pro.desktop". Soubor by měl být v kódování UTF-8 a měl by být založen na následujícím vzoru:

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

Soubory plochy obsahují metadata o aplikaci a hrají hlavní roli v integraci programu v GNOME a obdobných pracovních prostředích, které pracují dle stejného standardu. Zde uvedený vzor je tím úplně základním. Soubor může být lokalizován, takže uživateli se názvy aplikací zobrazují v jeho rodném jazyce.

Tento soubor umístěte do adresáře `/usr/share/applications`, kde bude dostupný pro každého uživatele, nebo do adresáře `~/.local/share/applications`, pokud si přejete, aby aplikace byla dostupná jen konkrétnímu uživateli. Umístění bude použito v závislosti na tom, zda je aplikace nainstalována v systému nebo v domácím adresáři uživatele. GNOME sleduje tato umístění, takže prosté nakopírování souboru plochy do jednoho z nich stačí k registraci v pracovním prostředí.

Mějte na paměti, že adresář `~/.local/share/applications` je sledován v GNOME od verze 2.10 (v distribuci Fedora od verze 2.8). Dřívější verze GNOME pracovali na dnes již zastaralou technologii vfolder a proto musely být soubory plochy instalovány do `~/.gnome2/vfolders/applications`. Toto umístění není podporováno od GNOME 2.10 (v distribuci Fedora od GNOME 2.8) a proto, pro zajištění maximální kompatibility, umístěte soubor do obou adresářů.

Mějte také na paměti, že pracovní prostředí KDE vyžaduje spuštění `kbuildsycoca`, aby byla nabídka aktualizována.

Každý funkční soubor plochy musí používat tento formát. Příklad takového souboru ukazuje ex-sample-desktop-file. Soubor je rozdělen na části, každá začíná popisem sekce v hranatých závorkách. Ve zmiňovaném příkladu je jen jedna část, která je základem integrace aplikace do pracovního prostředí. V každé části je obsah každého řádku před znamínkem rovnosti ('=') klíč a vše za ním pak hodnota klíče. Vysvětlení jednotlivých klíčů popisuje tb-desktop-file.

Krom prvního řádku, který identifikuje soubor plochy, není pořadí důležité. Řádek `Type=Application`, který obsahuje ex-sample-desktop-file, může být na druhém, pátém nebo posledním řádku a výsledek bude stejný.

Každopádně názvy klíčů rozlišují malá a velký písmena a proto `Type=Application` není to samé jako `type=Application` nebo `TYPE=Application`.

#### Nějaký soubor plochy

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

### Vysvětlení řádek po řádku

Řádek | Popis
`[Desktop Entry]` | První řádek každého souboru plochy a hlavička každé části, sloužící k identifikaci bloku asociovaných klíčů s hodnotami a pracovního prostředí. Nezbytné pro prostředí ke správnému rozpoznání souboru.
`Type=Application` | Říká pracovnímu prostředí, že soubor náleží aplikaci. Další platné hodnoty tohoto klíče jsou `Link` a `Directory`.
`Encoding=UTF-8` | Uvádí kódování znaků v souboru plochy.
`Name=Sample Application Name` | Název vaší aplikace, který bude použit v nabídce a pro spouštěč.
`Comment=A sample application` | Popisuje aplikaci, používá se jako bublinová nápověda.
`Exec=application` | Příkaz, který spustí aplikaci z příkazové řádky. Může obsahovat parametry.
`Icon=aplikace.png` | Název ikony asociovaný s aplikací
`Terminal=false` | Určuje, jestli se aplikace má spustit v terminálu.

#### Spuštění aplikace

Pokud vaše aplikace podporuje parametry z příkazového řádku, můžete je uvést v tak, jak ukazuje tb-exec-params.

#### Proměnné při spouštění

Přidat... | Akceptuje...
`%f` | jeden název souboru
`%F` | více jmen souborů
`%u` | jedna adresa URL
`%U` | více adres URL
`%d` | jeden adresář. Využívá se spolu s `%f` k určení umístění souboru.
`%D` | více adresářů. Využívá se spolu s `%F` k určení umístění souborů.
`%n` | jeden název souboru bez cesty
`%N` | více názvů souborů bez cest
`%k` | adresa URI nebo cesta k souboru, kde se nachází soubor plochy.
`%v` | název zařízení.

#### Cizí jazyky

Pokud chcete lokalizovat názvy a popisy, musíte pro každý překlad uvést další řádek. Například, pokud chcete přidat český překlad popisu, přidáte následující řádek:

`Comment[cs]=Ukázková aplikace`

Neexistuje limit, kolik lze maximálně uvádět překladů v jednom souboru.

Protože je správa dlouhého seznamu překladů v jednom souboru nešikovný, lepším způsobem je vytvořit tyto překlady pomocí balíku nástrojů intltool. Další informace se dozvíte z manuálových stránek popisujících intltool-extract a intltool-merge.

#### Reference

Desktop Entry Specification — Specifikace pro vytváření souborů plochy

### Instalace ikon

Ukázka ex-sample-desktop-file má nastavenu ikonu aplikace jako ``aplikace.png``. Aby to ale fungovalo, musíte také umístit soubor s ikonou do správného adresáře.

Pracovní prostředí hledá ikony zvoleného motivu v adresáři `/usr/share/icons/`. Ikony aplikací by měly být dostupné nejméně v rozlišení 48x48 pixelů a umístěny v adresáři `/usr/share/icons/hicolor/48x48/apps/`. Sem se prostředí podívá, pokud zvolený motiv danou ikonu aplikace neobsahuje. Pokud máte ikony pro různé motivy, vložte je do příslušných adresářů.

Aby byla integrace vzhledu s pracovním prostředím GNOME lepší, při udržení nativního vzhledu, když je spuštěna pod KDE, Windows XP nebo Mac OS X, řiďte se při vytváření grafiky dokumentem Tango Style guidelines. Ten popisuje různé aspekty tvorby ikon včetně barev, nasvícení a rozměrů. Přiloženy jsou i popis tvorby a videa s tutoriály.

#### Reference

Icon Theme Specification — Popisuje instalaci a vzhled z pohledu změn motivu.

Icon Naming Specification — Poskytuje informace o schématu pojmenovávání souborů.

Tango Style Guidelines — Popisuje způsob, jak vytvářet čisté a 'multiplatformní' ikony.

### Přidávání typů MIME

Pokud vaše aplikace umí otevírat nějaký specifický typ MIME, musíte o tom pracovnímu prostředí dát vědět v souboru plochy. Pokud Vaše aplikace například umí pracovat se soubory PNG, přidejte do jejího souboru plochy tento řádek:

    MimeType=image/png

Další typy MIME mohou být přidány oddělené středníkem.

Systém sám o sobě zná mnoho typů MIME, ale pokud chcete vytvořit nějaký vlastní, musíte jej registrovat do databáze typů MIME. V adresáři `/usr/share/mime/packages/` vytvořte soubor typu XML ve formátu, jaký ukazuje ex-mime-xml.

#### Příklad souboru registrujícího nový typ MIME

    <?xml version="1.0" encoding="UTF-8"?>
    <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
       <mime-type type="application/x-example">
         <comment>Example file type </comment>
         <magic priority="50">
           <match value="search-string" type="string" offset="10:140"/>
         </magic>
         <glob pattern="*.newextension"/>
       </mime-type>
    </mime-info>

V uvedeném příkladu nahraďte typ MIME svým vlastním názvem. Příkaz magic prohledává kvůli identifikaci soubory za účelem nalezení řetězce. Řádek s glob využívá k identifikaci příponu názvu souboru.

Protože příkaz `magic` zapříčiní otevírání souborů za účelem vyhledání řetězce, je příkaz `glob` vhodnější.

Když je váš typ MIME řádně popsán v souboru, spusťte následující příkaz z řádky:

    update-mime-database /usr/share/mime

Více informací o výběru správné přípony typu MIME a registraci typu naleznete na WWW stránkách IANA.

#### Reference

Shared MIME Info Specification — Popisuje podrobnosti o registraci typů MIME.

## Hlubší integrace s pracovním prostředím

Tato kapitola obsahuje seznam věcí, které můžete dále udělat pro lepší integraci s GNOME, než je naprosté minimum. Například GNOME umožňuje sdělit uživateli, že je aplikace spouštěna: jak povolit tuto zpětnou vazbu popisuje startup-notification. Také, pokud vaše aplikace vytváří dokumenty nebo jiná "tisknutelná" data, můžete nainstalovat nástroj pro vytváření náhledů a umožnit tak správci souborů GNOME vytvářet náhledy přímo pro váš program.

### Oznámení při spuštění

Krom položek, které zobrazuje desktop-files, poskytují dostatek informací, aby bylo pracovní prostředí schopno rozpoznat vaši aplikaci, existují další, které se hodí pro různé účely. Jedním z nich je oznámení o spuštění.

Pokud je oznámení nastaveno, panel a kurzor informují změnou vzhledu uživatele o spouštění aplikace. Když se aplikace následně objeví na obrazovce, vzhled obou prvků se vrátí do normálu.

Pokud chcete ve spouštěči uvést, že vaše aplikace podporuje oznámení o spuštění, přidejte následující řádek do jejího souboru plochy:

`StartupNotify=true`

Tento příkaz v souboru plochy povoluje pracovnímu prostředí využití oznámení o spuštění, které je součástí aplikace nebo toolkitu. Většina moderních toolkitů pracuje s oznámením o spuštění transparentně. Pokud nepoužíváte jeden z těch moderních, dokument Startup Notification Spec popisuje, co budete muset sami implementovat.

Bez ohledu na toolkit, v jednom případě budete muset zařídit zpětnou vazbu ručně. Aplikace se schopnostmi vzdáleného ovládání (když sdělíte procesu, aby otevřel nové okno namísto spuštění procesu nového) nemohou využít zabudovaný mechanismus. Hodnota prostředí DESKTOP_LAUNCH_ID musí být vaší aplikací předána a upozornit spouštěcí mechanismus na nové okno. Pokud používáte GTK+, naleznete o něco více informací v dokumentaci funkce `gdk_notify_startup_complete()`.

#### Reference

Startup Notification Protocol — Popis nízkoúrovňových podrobností o implementaci oznamování spuštění v systému X Window.

### Instalace nástroje pro vytváření náhledů

Správce souborů GNOME, Nautilus, může zobrazovat malé náhledy každého souboru namísto obecné ikony jeho typu. Například dokument kancelářského balíku se zobrazí jako malý náhled první strany dokumentu. To je užitečné, protože uživatelé vidí malé náhledy dat ve svých souborech, které jim pomáhají se orientovat. Vaše aplikace může vytvářet náhledy, pokud provedete těchto několik jednoduchých kroků:

thumbnailer, nástroj pro vytváření náhledů, je program bez uživatelského rozhraní, který má jako vstup název souboru a velikost v pixelech a vytváří pro daný soubor náhled. GNOME zjišťuje, jaký thumbnailer použít, na základě typu MIME souboru, pro který chceme náhled vytvořit. Mapa mezi typy MIME a příslušnými thumbnailery je uložena jako série klíčů GConf.

Pro každý typ MIME, který chcete zpracovávat, musíte vytvořit pár klíčů GConf:

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

- Typ: boolean. Určuje, zda bude thumbnailer spuštěn. Můžete tak zvlášť povolit každý z existujících. Pokud tedy nainstalujete nový thumbnailer, měli byste nastavit tento klíč na hodnotu true.

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

- Typ: string. Příkaz, který GNOME použije, pokud je potřeba vytvořit náhled souboru s typem `application@x-foo`. Uvedeno může být například něco jako "`application-x-foo-thumbnailer %i %o %s`". Níže je popsáno vysvětlení položek uvozených znakem procento ('%').

Každý typ MIME vyžaduje dva klíče GConf (`enable` a `command`) uvedené pod stejnou cestou. Cestu lze odvodit pomocí názvu typu MIME nahrazením "`/`" za "`@`". Například thumbnailer pro `image/x-my-format` bude mít dva klíče: `/desktop/gnome/thumbnailers/image@x-my-format/enable` a `/desktop/gnome/thumbnailers/image@x-my-format/command`.

V klíči `command` nahradí GNOME položky uvozené znakem procent těmito hodnotami:

`%i` | Název vstupního souboru. To je soubor, který má thumbnailer zpracovat.
`%u` | Vstupní adresa URI. Pokud umí váš thumbnailer obsluhovat adresy URI namísto prostého názvu souboru, použijte `%u` namísto `%i`.
`%o` | Název výstupního souboru. To je místo, kam má thumbnailer uložit náhled jako obrázek ve formátu PNG.
`%s` | Velikost náhledu, uvedeno jako prostý integer. Například, pokud bude řetězec nahrazen za `128`, znamená to, že při vytváření náhledů by neměl být výsledek větší než 128x128 pixelů.

Jeden z řetězců `%i` nebo `%u` musí být u příkazu uveden a `%o` je také povinné. Řetězec `%s` je volitelný, ale doporučujeme, aby jej thumbnailer neignoroval.

#### Dodatečné informace

Další parametr nastavení je booleanovský klíč `/desktop/gnome/thumbnailers/disable_all`, pomocí kterého můžete zakázat vytváření jakýchkoliv náhledů.

## Seznam úkonů integrace

Tento dodatek obsahuje seznam různých úkonů uvedených v této příručce. Použijte jej ke kontrole, zda je váš software integrován s GNOME alespoň na základní úrovni a také jako zdroj při plánování další integrace.

1. Zobrazuje se vaše aplikace v nabídkách panelu GNOME?

2. Má vaše aplikace ikonu pro nabídku a odkaz na ploše? Pokud ano, existuje několik předvytvořených rozměrů a vektorová verze ve formátu SVG?

3. Pokud vaše aplikace umožňuje nahrávat a ukládat soubory, jsou jejich typy MIME registrovány?

4. Poskytuje vaše aplikace ikony typů MIME pro správce souborů?

5. Podporuje vaše aplikace oznámení o spuštění, aby se v GNOME mohla zobrazovat zpětná vazba uživateli, když je aplikace spouštěna?

6. Pokud vaše aplikace vytváří "tisknutelné" dokumenty, instaluje pro ně thumbnailer, nástroj pro vytváření náhledů, který může správce souborů použít?

## Uznání

Mnoho díků patří Jakubovi Steinerovi za vytvoření krásného stylu CSS pro HTML verzi této příručky!