KVIrc → Основы KVS: Структура дополнений.
Введение
Дополнение — это ряд скриптов KVS, мультимедиа, документация и файлы вспомогательных программ, которые реализуют дополнительные возможности KVIrc. Это может быть простая автоматическая подсистема, графический интерфейс пользователя или сложная служба совместного использования файлов (обычно называющаяся «fserve»). Дополнения иногда называют «скриптами». Обычно дополнение KVIrc имеет в своём составе больше чем один скрипт KVS.
KVIrc имеет встроенную систему управления дополнениями, которая позволяет пользователям устанавливать, конфигурировать и удалять дополнения с хорошим графическим интерфейсом. Система управления позволяет дополнениям иметь документацию, объединенную в справке KVIrc и переведённую на несколько языков.
Установка дополнений
Дополнения обычно распространяются в сжатых архивах типа tar.gz(tarballs) или zip-файлах. После распаковки они должны содержать файл скрипта KVS, названный «install.kvs». KVIrc будет искать и выполнять этот файл, когда пользователь вызовет Ваше дополнение для установки. install.kvs обычно содержит код для регистрации вашего дополнения и включает все другие необходимые исходные файлы.
Минимальное дополнение
Наименьшее дополнение, которое Вы можете написать, — тот, который не делает ничего. Это только должно быть, пишут в файле, названном install.kvs и содержат код, подобный следующему:
Код выше выполняет только регистрацию дополнения «myaddon».
Первый параметр — внутреннее дополненительный идентификатор, который может использоваться, чтобы идентифицировать ваше дополнение внутри KVIrc. Идентификатор должен быть уникальным: два дополнения, которые совместно используют то же самое название, не могут быть установлены. Второй параметр — дополнительная версия. Это должно быть выражено в классическом формате [major]. [minor]. [pathlevel] или чём-нибудь действительно подобном (фактически KVIrc только ожидает, что строка версии составлена из чисел отделенных точками). Третий параметр — видимое название вашего дополнения: это будет отображено пользователю в дополнительном диалоге управления. Может содержать функцию $tr(), так чтобы Вы могли перевести это на несколько языков. Четвертый параметр — короткое описание особенностей, которые дополнение осуществляет. Он может также содержать функцию $tr(). Пятый параметр — минимальная версия KVIrc, требуемая для выполнения дополнения. Есть также шестой параметр (значок).
Следующая команда, которая следует за командой регистрации — команда удаления дополнения. KVIrc вызовет её, когда пользователь удаляет ваше дополнение. Не предполагайте, что ваше дополнение никогда не будет удаляться. Рано или поздно это произойдёт. Например, модернизируя дополнения KVIrc сначала удаляет существующую версию и после этого установливает новый. Процесс удаления — очень важен и необходим для любой программы (в любом языке программирования). В примере выше нет ничего что надо удалять, таким образом код команды пуст, но если Вы продолжите читать, то мы скоро заполним это.
Типичная структура дополнения
Как указано выше, дополнения обычно поставляются сжатыми в архив. После распаковки архив развернётся в маленькое дерево каталогов, содержащее дополнительный код и все связанные файлы. Чтобы унифицировать всё предлагается использовать следующую структуру каталога.
Отмеченное жирным — каталоги, остальное — файлы. Пожалуйста отметьте, что это — общее размещение для огромного и довольно сложного дополнения. Вы можете не нуждаться во всех этих каталогах. Помните: минимальное дополнение имеет только install.kvs файл. Так или иначе, действительно нормальное дополнение будет вероятно иметь все эт файлы и возможно еще некоторые.
Каталог верхнего уровня нужно назвать вашим addonId(идентификатор дополнения) и версией. Пробуйте не использовать никаких пробелов в название каталога (это поможет людям, которые хотят использовать ваше дополнение). Каталог верхнего уровня должен содержать ваш install.kvs скрипт и файл с маленьким описанием и основными установочными командами. Этот файл можно назвать INSTALL или README.
Основной исходный каталог для вашего дополнения нужно назвать «src» и должен содержать код выполнения особенностей, которые Вы собираетесь обеспечивать. Эти файлы должны выполняться посредством синтаксического анализа install.kvs.
Каталоги «pics» и «audio» (если нужны) должны содержать ваши файлы мультимедиа. Будет хорошей идеей задать префикс имени файла в виде идентификатора вашего дополнения, чтобы избежать конфликтов с другими дополнениями. Скрипт install.kvs должен скопировать эти файлы в соответствующие места размещения локального каталога KVIrc, возвращенного функцией $file.localdir().
Каталог «help» должен содержать подкаталоги для каждого языка, в котором ваши файлы справки написаны. Языковые каталоги нужно назвать в соответствии с языковым кодом, также используемые для файлов переводов (как «en», «it» и т.д ...). Пожалуйста отметьте, что английский язык — язык значения по умолчанию, и KVIrc будет переходить в аварийном режиме в подкаталог «en», когда остальные языки будут недоступны… Файлы справки (и подкаталоги) должны быть скопированы в подкаталог «help» локального каталога KVIrc, возвращенного функцией $file.localdir(). Возможно со временем у Вас будет много файлов справки в языковых папках, будет хорошей идеей задать префикс имени файла в виде идентификатора вашего дополнения или лучше создать ещё и подкаталог названный именем идентификатора Вашего дополнения в языковом каталоге справки.
Каталог «locale» должен содержать *.mo файлы для ваших переводов. Процесс локализации скрипта объясняется в этом документе. *.mo файлы должны быть скопированы в подкаталог «locale» локального каталога KVIrc, возвращенного функцией $file.localdir(). Названия Ваших *.mo файлов должны быть представлены в виде идентификатора Вашего дополнения, чтобы избежать конфликтов.
Вызов справки и конфигурации
Каждое дополнение может иметь справку и вызов конфигурации. Они устанавливаются соответственно addon.sethelpcallback и addon.setconfigurecallback.
Справка будет вызвана KVIrc, когда пользователь запросит у неё ваше дополнение (главным образом из диалога управления дополнениями, но не обязательно). Вызвается это командой help.open с названием вашего индексного файла документов в формате html (относительно языкового каталога справки: help.open myaddon/index.html будет автоматически найден правильный язык). Если Вы не обеспечиваете никакого вызова справки, кнопки вызова будут заблокированы. Польза от этого в том что относительно сложное дополнение имеет по крайней мере минимальный файл справки, объясняющий особенности использования.
Конфигурация будет вызвана, когда пользователь будет пробовать конфигурировать ваше дополнение из диалога управления дополнениями. Этот вызов полезен главным образом для графических скриптов, которые могут вызвать диалог, который позволяет конфигурировать все обенности дополнения. Чтобы использовать это, Вы будете вероятно нуждаться в некоторых знаниях по созданию объектов.
Реальная работа дополнений
Реальная работа дополнений выполняется скриптами, которые содержатся в каталоге src. Они добавляют псевдонимы (возможно в пространство имён названное идентификатором вашего дополнения), регистрируют обработчики событий, создают действия, таймеры, инструментальные панели и классы объектов. Вы должны установить весь этот материал из ваших дополнительных исходных файлов. Помните, что ваши исходные файлы не будут анализироваться каждый раз, при запуске KVIrc. Ваш скрипт должен быть зарегистрирован в KVIrc и быть в состоянии готовности к запуску постоянно, если это нужно. Помните, что Вы должны очистить всё при вызове удаления дополнения. Это означает, что Вы должны удалить псевдонимы, обработчики событий, уничтожить действия, таймеры и классы объектов, которые Вы создали.
Эта статья является куском перевода встроенной помощи KVIrc и не претендует на оригинальность.
Дополнение — это ряд скриптов KVS, мультимедиа, документация и файлы вспомогательных программ, которые реализуют дополнительные возможности KVIrc. Это может быть простая автоматическая подсистема, графический интерфейс пользователя или сложная служба совместного использования файлов (обычно называющаяся «fserve»). Дополнения иногда называют «скриптами». Обычно дополнение KVIrc имеет в своём составе больше чем один скрипт KVS.
KVIrc имеет встроенную систему управления дополнениями, которая позволяет пользователям устанавливать, конфигурировать и удалять дополнения с хорошим графическим интерфейсом. Система управления позволяет дополнениям иметь документацию, объединенную в справке KVIrc и переведённую на несколько языков.
Установка дополнений
Дополнения обычно распространяются в сжатых архивах типа tar.gz(tarballs) или zip-файлах. После распаковки они должны содержать файл скрипта KVS, названный «install.kvs». KVIrc будет искать и выполнять этот файл, когда пользователь вызовет Ваше дополнение для установки. install.kvs обычно содержит код для регистрации вашего дополнения и включает все другие необходимые исходные файлы.
Минимальное дополнение
Наименьшее дополнение, которое Вы можете написать, — тот, который не делает ничего. Это только должно быть, пишут в файле, названном install.kvs и содержат код, подобный следующему:
addon.register ("myaddon","1.0.0",\
"Мое Первое Дополнение",\
"Дополнение, которое является действительно крутым, но не делает просто ничего",\
3.2.0.99.20051230")
{
}Код выше выполняет только регистрацию дополнения «myaddon».
Первый параметр — внутреннее дополненительный идентификатор, который может использоваться, чтобы идентифицировать ваше дополнение внутри KVIrc. Идентификатор должен быть уникальным: два дополнения, которые совместно используют то же самое название, не могут быть установлены. Второй параметр — дополнительная версия. Это должно быть выражено в классическом формате [major]. [minor]. [pathlevel] или чём-нибудь действительно подобном (фактически KVIrc только ожидает, что строка версии составлена из чисел отделенных точками). Третий параметр — видимое название вашего дополнения: это будет отображено пользователю в дополнительном диалоге управления. Может содержать функцию $tr(), так чтобы Вы могли перевести это на несколько языков. Четвертый параметр — короткое описание особенностей, которые дополнение осуществляет. Он может также содержать функцию $tr(). Пятый параметр — минимальная версия KVIrc, требуемая для выполнения дополнения. Есть также шестой параметр (значок).
Следующая команда, которая следует за командой регистрации — команда удаления дополнения. KVIrc вызовет её, когда пользователь удаляет ваше дополнение. Не предполагайте, что ваше дополнение никогда не будет удаляться. Рано или поздно это произойдёт. Например, модернизируя дополнения KVIrc сначала удаляет существующую версию и после этого установливает новый. Процесс удаления — очень важен и необходим для любой программы (в любом языке программирования). В примере выше нет ничего что надо удалять, таким образом код команды пуст, но если Вы продолжите читать, то мы скоро заполним это.
Типичная структура дополнения
Как указано выше, дополнения обычно поставляются сжатыми в архив. После распаковки архив развернётся в маленькое дерево каталогов, содержащее дополнительный код и все связанные файлы. Чтобы унифицировать всё предлагается использовать следующую структуру каталога.
<b>addonId-version</b>/
install.kvs
INSTALL
<b>src</b>
source1.kvs
source2.kvs
source3.kvs
...
<b>pics</b>
addonId_pic1.png
addonId_pic2.png
addonId_pic3.png
...
<b>audio</b>
addonId_audio1.png
addonId_audio2.png
addonId_audio3.png
...
<b>help</b>
<b>en</b>
index.html
hints.html
...
<b>it</b>
index.html
hints.html
...
...
<b>locale</b>
addonId_it.mo
addonId_ru.mo
addonId_de.mo
...
...
...
...
...
...
Отмеченное жирным — каталоги, остальное — файлы. Пожалуйста отметьте, что это — общее размещение для огромного и довольно сложного дополнения. Вы можете не нуждаться во всех этих каталогах. Помните: минимальное дополнение имеет только install.kvs файл. Так или иначе, действительно нормальное дополнение будет вероятно иметь все эт файлы и возможно еще некоторые.
Каталог верхнего уровня нужно назвать вашим addonId(идентификатор дополнения) и версией. Пробуйте не использовать никаких пробелов в название каталога (это поможет людям, которые хотят использовать ваше дополнение). Каталог верхнего уровня должен содержать ваш install.kvs скрипт и файл с маленьким описанием и основными установочными командами. Этот файл можно назвать INSTALL или README.
Основной исходный каталог для вашего дополнения нужно назвать «src» и должен содержать код выполнения особенностей, которые Вы собираетесь обеспечивать. Эти файлы должны выполняться посредством синтаксического анализа install.kvs.
Каталоги «pics» и «audio» (если нужны) должны содержать ваши файлы мультимедиа. Будет хорошей идеей задать префикс имени файла в виде идентификатора вашего дополнения, чтобы избежать конфликтов с другими дополнениями. Скрипт install.kvs должен скопировать эти файлы в соответствующие места размещения локального каталога KVIrc, возвращенного функцией $file.localdir().
Каталог «help» должен содержать подкаталоги для каждого языка, в котором ваши файлы справки написаны. Языковые каталоги нужно назвать в соответствии с языковым кодом, также используемые для файлов переводов (как «en», «it» и т.д ...). Пожалуйста отметьте, что английский язык — язык значения по умолчанию, и KVIrc будет переходить в аварийном режиме в подкаталог «en», когда остальные языки будут недоступны… Файлы справки (и подкаталоги) должны быть скопированы в подкаталог «help» локального каталога KVIrc, возвращенного функцией $file.localdir(). Возможно со временем у Вас будет много файлов справки в языковых папках, будет хорошей идеей задать префикс имени файла в виде идентификатора вашего дополнения или лучше создать ещё и подкаталог названный именем идентификатора Вашего дополнения в языковом каталоге справки.
file.copy index.html $file.localdir("help/en/myaddon")Каталог «locale» должен содержать *.mo файлы для ваших переводов. Процесс локализации скрипта объясняется в этом документе. *.mo файлы должны быть скопированы в подкаталог «locale» локального каталога KVIrc, возвращенного функцией $file.localdir(). Названия Ваших *.mo файлов должны быть представлены в виде идентификатора Вашего дополнения, чтобы избежать конфликтов.
Вызов справки и конфигурации
Каждое дополнение может иметь справку и вызов конфигурации. Они устанавливаются соответственно addon.sethelpcallback и addon.setconfigurecallback.
Справка будет вызвана KVIrc, когда пользователь запросит у неё ваше дополнение (главным образом из диалога управления дополнениями, но не обязательно). Вызвается это командой help.open с названием вашего индексного файла документов в формате html (относительно языкового каталога справки: help.open myaddon/index.html будет автоматически найден правильный язык). Если Вы не обеспечиваете никакого вызова справки, кнопки вызова будут заблокированы. Польза от этого в том что относительно сложное дополнение имеет по крайней мере минимальный файл справки, объясняющий особенности использования.
Конфигурация будет вызвана, когда пользователь будет пробовать конфигурировать ваше дополнение из диалога управления дополнениями. Этот вызов полезен главным образом для графических скриптов, которые могут вызвать диалог, который позволяет конфигурировать все обенности дополнения. Чтобы использовать это, Вы будете вероятно нуждаться в некоторых знаниях по созданию объектов.
Реальная работа дополнений
Реальная работа дополнений выполняется скриптами, которые содержатся в каталоге src. Они добавляют псевдонимы (возможно в пространство имён названное идентификатором вашего дополнения), регистрируют обработчики событий, создают действия, таймеры, инструментальные панели и классы объектов. Вы должны установить весь этот материал из ваших дополнительных исходных файлов. Помните, что ваши исходные файлы не будут анализироваться каждый раз, при запуске KVIrc. Ваш скрипт должен быть зарегистрирован в KVIrc и быть в состоянии готовности к запуску постоянно, если это нужно. Помните, что Вы должны очистить всё при вызове удаления дополнения. Это означает, что Вы должны удалить псевдонимы, обработчики событий, уничтожить действия, таймеры и классы объектов, которые Вы создали.
Эта статья является куском перевода встроенной помощи KVIrc и не претендует на оригинальность.
- +8
- alexzulu
- 13 июня 2009, 01:46