Next Previous Table of Contents
Предыдущая глава описывала стандарт файловой системы KDE, эта глава описывает, как использовать файловую систему. Проект KDE использует файловую систему по крайней мере при инсталляции; поэтому мы обсудим правила установки инсталляционных свойств файлов вашего проекта. Поскольку ваше приложение будет использовать все установленные файлы, ему важно знать, как получить к ним стандартные относительные пути. Это позволит вашему приложению работать независимо от того, где располагается корневой каталог файловой системы KDE, и, таким образом, избежать жесткого задания путей файлов.
После инсталляции вашего проекта конечным пользователем, вашему приложению может потребоваться файл в процессе выполнения. В ходе
разработки вы наверняка натыкались на одну ошибку при запуске приложения из IDE KDevelop - при вызове
помощи через "Help"-"Contents" или нажатием F1. В результате вам выдавалось сообщение, что
файл index.html не найден - если вы не установили перед этим приложение в локальной файловой системе KDE. Ваше приложение запрашивает
KDEHelp, чтобы он открыл индексную страницу, предварительно определяя каталог инсталляции методами KApplication
, осуществляющими доступ
к файловой системе; поэтому рассмотрим, что предлагает KApplication
, и приведем несколько примеров использования. Другие классы
KDE-Core
также используют файловую систему KDE, например, KIconLoader
и KLocale
, которые будут рассмотрены позже.
Класс 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:
Если файл не найден, метод QString isEmpty() возвращает True
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 )
Выше было объяснено, где приложение KDE должно располагать свои файлы и как получить к ним доступ при выполнении. Теперь объясним, как правильно установить свойства файлов, чтобы они записались в нужные места при инсталляции. Файлы Makefiles поддерживают набор макросов для инсталляции ваших файлов в файловую систему KDE, которые должны быть использованы при установке значений инсталляционных свойств файлов.
Для установки свойств откройте проект и выберите "Project"-"File Properties", что откроет диалог свойств файла. Свойства файла отображаются, если вы выберите файл, включенный в проект. Во-первых, файл имеет свойство "тип" ("type"), которое может принимать такие значения:
Далее, файл включен в проект, если выбрана опция "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):
Установка пустого пути добавит линк вашего приложения непосредственно в корень 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.
Другая проблема, с которой часто сталкиваются разработчики, это когда они включают в свой проект дополнительные файлы с данными, которые необходимо инсталлировать вместе с проектом. Вы уже знаете, куда их инсталлировать, но как организовать их в исходном дереве?
Хорошим советом будет собрать данные в каталоги, которые более-менее соответствуют стандарту файловой системы KDE, например,
ваше приложение требует дополнительных иконок панели инструментов. Создание этих иконок в главном каталоге проекта - не очень хорошая идея,
поскольку их будет тяжело найти в просмотрщике файлов, и их удаление превращается в долгую работу с каждой иконкой. Создайте свой каталог для иконок
с помощью "File"- "New" и выберите подкаталог toolbar
; если он не существует, то его можно легко создать через диалог "выбор каталога" ("select directory").
Существующие иконки можно скопировать и добавить в проект командой "добавить существующие файлы" ("Project"-"Add existing file(s)"), в которой необходимо выбрать
файлы и каталог назначения. При выборе каталога назначения, вы можете вначале создать каталог toolbar
в диалоге.
По окончании нажмите OK, и файлы будут скопированы и включены в проект.
Как пример, иконки панели инструментов должны инсталлироваться в:
$(kde_datadir)/<appname>/toolbar/<ваша_иконка>.xpm
Картинки и другие иконки, которые не используются на панелях инструментов, лучше положить в подкаталог pics вместо toolbar.
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