Next Previous Table of Contents

### 14. Использование файловой системы в проектах KDevelop

Предыдущая глава описывала стандарт файловой системы KDE, эта глава описывает, как использовать файловую систему. Проект KDE использует файловую систему по крайней мере при инсталляции; поэтому мы обсудим правила установки инсталляционных свойств файлов вашего проекта. Поскольку ваше приложение будет использовать все установленные файлы, ему важно знать, как получить к ним стандартные относительные пути. Это позволит вашему приложению работать независимо от того, где располагается корневой каталог файловой системы KDE, и, таким образом, избежать жесткого задания путей файлов.

### 14.1 Доступ к файлам в процессе выполнения

После инсталляции вашего проекта конечным пользователем, вашему приложению может потребоваться файл в процессе выполнения. В ходе разработки вы наверняка натыкались на одну ошибку при запуске приложения из IDE KDevelop - при вызове помощи через "Help"-"Contents" или нажатием F1. В результате вам выдавалось сообщение, что файл index.html не найден - если вы не установили перед этим приложение в локальной файловой системе KDE. Ваше приложение запрашивает KDEHelp, чтобы он открыл индексную страницу, предварительно определяя каталог инсталляции методами `KApplication`, осуществляющими доступ к файловой системе; поэтому рассмотрим, что предлагает `KApplication`, и приведем несколько примеров использования. Другие классы `KDE-Core` также используют файловую систему KDE, например, `KIconLoader` и `KLocale`, которые будут рассмотрены позже.

### 14.2 Методы KApplication

Класс KApplication предоставляет следующие методы доступа к файловой системе KDE:

> `

>     void invokeHTMLHelp ( QString aFilename, QString aTopic ) const
>     static const QString& kde_htmldir ()
>     static const QString& kde_appsdir ()
>     static const QString& kde_icondir ()
>     static const QString& kde_datadir ()
>     static const QString& kde_localedir ()
>     static const QString& kde_cgidir ()
>     static const QString& kde_sounddir ()
>     static const QString& kde_toolbardir ()
>     static const QString& kde_wallpaperdir ()
>     static const QString& kde_bindir ()
>     static const QString& kde_configdir ()
>     static const QString& kde_mimedir ()
>     static QString localkdedir ()
>     static QString localconfigdir ()
>     static QString findFile ( const char *file )

> `

Методы обычно используются с объектом `KApplication` вашего приложения, где `KApplication` предоставляет макрос `kapp`, возвращающий указатель на него:

#define kapp KApplication::getKApplication()

Поэтому обычно методы используются так:

> `

>     QString sounddir=kapp->kde_sounddir();

> `

В этом примере путь к каталогу KDE с звуковыми файлами заносится в `QString`, к которому вы должны добавить, например, имя файла. Затем вы можете обработать эту информацию и проиграть файл. Всегда проверяйте существование файла, используя метод `exists()` объекта `QFileInfo`.

Среди этих методов,

> `

>     void invokeHTMLHelp( QString aFilename, QString aTopic ) const [public]

> `

занимает специальное положение; он запускает помощь KDE. Вы должны использовать его везде, где пользователю требуется доступ к информации, например, когда открыт модальный диалог. Клавиша F1 не будет работать для вызова помощи в этой ситуации, хотя пользователь должен быть обеспечен соответствующей страницей помощи. Чтобы обеспечить ее использование, добавьте кнопку "Help" в ваш диалог и создайте слот, к которому подсоедините кнопку по сигналу `pressed()`. В этом слоте используйте `invokeHTMLHelp()` со ссылкой на соответствующую страницу и раздел; в случае, если документация еще не написана, оставьте вопрос открытым, чтобы решить его при синхронизации документации с приложением.

В документации по `KApplication` говорится:

Вызов просмотрщика HTML файлов помощи KDE.

Параметры: aTopic - Это позволяет реализовать контекстно-зависимую помощь. Его значение добавляется к имени файла после хеш-символа "#".

aFilename - Имя файла, который будет загружен. Его расположение определяется автоматически в соответствии с KFSSTND. Если aFilename пусто, используется логическое имя приложения с добавленным к нему расширением .html.

Методы `KApplication` возвращают следующие пути:

> `

>     kde_htmldir()         kdedir()/share/doc/HTML         Возвращает каталог, в котором KDE хранит
>                                                           свои файлы HTML документации

>     kde_appsdir()         kdedir()/share/applnk           Возвращает каталог, в котором приложения
>                                                           KDE хранят файл .kdelnk

>     kde_icondir()         kdedir()/share/icons            Возвращает каталог иконок KDE

>     kde_datadir()         kdedir()/share/apps             Возвращает каталог, в котором приложения
>                                                           KDE хранят свои специальные данные

>     kde_localedir()       kdedir()/share/locale           Возвращает каталог, в котором хранятся файлы с информацией
>                                                           о локализации (например, перевод экранных сообщений)

>     kde_cgidir()          kdedir()/cgi-bin                Возвращает каталог с cgi-скриптами

>     kde_sounddir()        kdedir()/share/sounds           Возвращает каталог со звуковыми файлами.
>                                                           Это каталог специальных звуков KDE.
>                                                           Звуки приложения хранятся в
>                                                           kde_datadir()

>     kde_toolbardir()      kdedir()/share/toolbar          Возвращает каталог с иконками кнопок панели инструментов

>     kde_wallpaperdir()    kdedir()/share/wallpapers       Возвращает каталог с обоями

>     kde_bindir()          kdedir()/bin                    Возвращает каталог с бинарными файлами приложений KDE

>     kde_configdir()       kdedir()/share/config           Возвращает каталог с конфигурационными файлами

>     kde_mimedir()         kdedir()/share/mimelnk          Возвращает каталог с информацией о mime-типах

>     localkdedir()         $HOME/.kde                      Возвращает локальный корневой каталог KDE (KDE base dir)

>     localconfigdir()      $HOME/.kde/share/config         Возвращает локальный каталог KDE с конфигурационными файлами

> `

Для поиска определенного файла, используйте `findFile(const char *file)`, который просматривает следующие пути файловой системы KDE:

1. $KDEDIR,
2. $KDEPATH,
3. "[KDE Setup]:Path=" вход в конфигурационном файле.

Если файл не найден, метод QString isEmpty() возвращает True

### 14.3 Методы KIconLoader

QPixmap loadIcon ( const QString &name, int w = 0, int h = 0 )

QPixmap reloadIcon ( const QString &name, int w = 0, int h = 0)

QPixmap loadMiniIcon ( const QString &name , int w = 0, int h = 0 )

QPixmap loadApplicationIcon ( const QString &name, int w = 0, int h = 0 )

QPixmap loadApplicationMiniIcon ( const QString &name, int w = 0, int h = 0 )

bool insertDirectory ( int index, const QString &dir_name )

### 14.4 Установка инсталляционных свойств файлов

Выше было объяснено, где приложение KDE должно располагать свои файлы и как получить к ним доступ при выполнении. Теперь объясним, как правильно установить свойства файлов, чтобы они записались в нужные места при инсталляции. Файлы Makefiles поддерживают набор макросов для инсталляции ваших файлов в файловую систему KDE, которые должны быть использованы при установке значений инсталляционных свойств файлов.

Для установки свойств откройте проект и выберите "Project"-"File Properties", что откроет диалог свойств файла. Свойства файла отображаются, если вы выберите файл, включенный в проект. Во-первых, файл имеет свойство "тип" ("type"), которое может принимать такие значения:

- HEADER: файл заголовка
- SOURCE: файл исходника
- SCRIPT: файл сценария (script-файл)
- DATA: файл данных, обычно картинка или файл документации HTML
- PO: файл перевода
- KDEV_DIALOG: файл диалога, обрабатываемый библиотекой диалогов

Далее, файл включен в проект, если выбрана опция "Include in Distribution". Ее установка приведет к включению файла в дистрибутив приложения.

Если файл должен быть инсталлирован, вы должны разрешить опцию "Install". Это сделает доступным свойство Installation path (путь инсталляции) для выбранного файла, куда уже вставлено имя файла.

Как уже говорилось, Makefile содержит набор макросов для путей файловой системы KDE. Они используются для установки путей инсталляции, и дают гарантию, что файл будет действительно записан в соответствующее место файловой системы, а не куда-нибудь еще. Используемые макросы должны быть взяты в круглые скобки и отмечены символом доллара перед макросом. Когда configure создает файлы Makefile на машине конечного пользователя, то определяются значения этих макросов, соответствующие реальному каталогу, и в файлы Makefile.am заносится действительная информация о путях.

Если посмотреть на стандартный проект KDE, то можно увидеть, что свойство файла `index.html` уже использует макрос для определения пути:

$(kde_htmldir)/en/kscribble/index.html

Это значит, что make запишет файл index.html в kde-html каталог, подкаталог en для английского языка, подкаталог приложения в файл с именем index.html. Вы можете использовать другое имя файла, если вы хотите переименовать файл при инсталляции.

Для определения положения файлов приложения в структуре kpanel вы должны отредактировать файл проекта Makefile.am, если место назначения отличается от секции "Приложения" ("Applications") kpanel:

APPSDIR = $(kde_appsdir)/Applications

Возможные значения (как говорит стандарт файловой системы KDE):

- Applications
- Games
- Graphics
- Internet
- Multimedia
- Settings
- System
- Utilities

Установка пустого пути добавит линк вашего приложения непосредственно в корень kpanel.

Следующий список содержит макросы, которые могут использоваться для указания путей файлов:

> `

>     kde_htmldir       - для документации (содержит подкаталоги для языков),
>     kde_appsdir       - для файла (.kdelnk),
>     kde_icondir       - для иконок,
>     kde_minidir       - для мини-иконок,
>     kde_datadir       - для данных приложения (используйте подкаталог),
>     kde_locale        - для файлов перевода (содержит подкаталоги для языков),
>     kde_cgidir        - для cgi-bin исполнимых файлов,
>     kde_confdir       - для конфигурационных файлов,
>     kde_mimedir       - для mime-типов,
>     kde_toolbardir    - для общих иконок панелей инструментов,
>     kde_wallpaperdir  - для общих обоев.

> `

Используйте эти макросы с необходимыми подкаталогами и именами файлов для установки инсталляционных свойств. По умолчанию, текущая версия HTML документации, файл kdelnk, иконка и мини-иконка, файлы перевода (даже новые) уже имеют установленными пути инсталляции; поэтому вы не должны вносить никаких изменений в конфигурацию по умолчанию шаблона, сгенерированного KDevelop.

### 14.5 Организация данных проекта

Другая проблема, с которой часто сталкиваются разработчики, это когда они включают в свой проект дополнительные файлы с данными, которые необходимо инсталлировать вместе с проектом. Вы уже знаете, куда их инсталлировать, но как организовать их в исходном дереве?

Хорошим советом будет собрать данные в каталоги, которые более-менее соответствуют стандарту файловой системы KDE, например, ваше приложение требует дополнительных иконок панели инструментов. Создание этих иконок в главном каталоге проекта - не очень хорошая идея, поскольку их будет тяжело найти в просмотрщике файлов, и их удаление превращается в долгую работу с каждой иконкой. Создайте свой каталог для иконок с помощью "File"- "New" и выберите подкаталог `toolbar`; если он не существует, то его можно легко создать через диалог "выбор каталога" ("select directory"). Существующие иконки можно скопировать и добавить в проект командой "добавить существующие файлы" ("Project"-"Add existing file(s)"), в которой необходимо выбрать файлы и каталог назначения. При выборе каталога назначения, вы можете вначале создать каталог `toolbar` в диалоге. По окончании нажмите OK, и файлы будут скопированы и включены в проект.

Как пример, иконки панели инструментов должны инсталлироваться в:

$(kde_datadir)/<appname>/toolbar/<ваша_иконка>.xpm

Картинки и другие иконки, которые не используются на панелях инструментов, лучше положить в подкаталог pics вместо toolbar.

### 14.6 Файл `kdelnk`

Файл <appname>.kdelnk, включенный в ваш проект, будет проинсталлирован в структуру меню kpanel. Он полностью заполнен, и в общем случае не требует доработки. Но, несмотря на способности KDevelop помогать вам в разработке проекта, он не может определить конечных целей вашего приложения, а эту информацию можно включить в файл kdelnk. Поскольку это текстовый файл, выберите его из RFV или LFV; он откроется в окне Header/Resource.

Перед вами пример файла kdelnk:

> `

>     # KDE Config File
>     [KDE Desktop Entry]
>     Type=Application
>     Exec=kscribble
>     Icon=kscribble.xpm
>     DocPath=kscribble/index.html
>     Comment=
>     Comment[de]=
>     Terminal=0
>     Name=kscribble
>     Name[de]=kscribble

> `

Это уже содержит базовую конфигурацию нашего приложения (иконки, имя исполнимого файла, название приложения и т.п.). Но секция комментариев Comment остается пустой. Сюда вы можете вставить всплывающую подсказку, которая будет отображаться, когда курсор мыши будет находиться над иконкой файла на рабочем столе или в меню kpanel. Если scribble будет небольшой графической программой, то введите, например,

> `

>     Comment=A simple drawing program

> `

Каждая последующая строка комментариев содержит перевод этого описания на указанный в квадратных скобках язык. Попросите переводчиков вставить правильный перевод на их родной язык или включите файл kdelnk, когда будете просить о переводе файла po приложения; то же самое касается и названия приложения в строке Name файла.

> Более подробную информацию о файле .kdelnk, особенно о его использовании при обработке командной строки, см. The KDE Library Reference Guide

Next Previous Table of Contents