Как написать аддон для ВоВ. API. XML. Фреймы и События.

Данная статья является продолжением цикла статей об аддонах. Предыдущая часть: Как написать аддон для ВоВ. Введение.

Элементы XML

Для проектирования интерфейса вашего аддона, вам понадобятся стандартные элементы - окна, кнопки и т.п. Они могут быть определены в XML файле с помощью стандартных элементов. Список элементов можно найти здесь: XML

По мере написания статей, буду переводить описание различных элементов на русский язык.

Так же XML файлы могут содержать код на языке LUA, описывающий реакцию элементов интерфейса на те или иные события. См. ниже.

Для проектирования интерфейса через XML, можно воспользоваться простым текстовым редактором, а можно воспользоваться визуальным средством проектирования, как, например, Wow UI Designer: http://www.wowinterface.com/downloads/info4222 (tnx. antidote)

Я, пока что, буду пользоваться редактором, чтобы лучше понять суть вопроса.

API

World of Warcraft предоставляет гибкий интерфейс для взаимодействия с игровым клиентом. На самом деле, клиент ВоВ предоставляет 3 API, помимо стандартных функций LUA. Более подробно можно прочитать здесь: API

По мере использования буду переводить API на русский язык для удобства пользователей. Если вы поможете мне в этом - будет замечательно.

Фреймы

Фрейм является основополагающей частью любого аддона. Если он должен взаимодействовать или реагировать на то, что происходит в игре, а не просто выводить текст. Фрейм не обязательно является видимой панелью. Можно рассматривать его просто, как объект класса Frame.

Среда World of Warcraft имеет определенную иериархию фреймов, с которой можно ознакомиться здесь: XML.

Будем называть типы XML объектов - классами или xml классами, для удобства. Из иериархии XML элементов видно, что класс Frame является прародителем практически всех стандартных элементов интерфейса.

Определить фрейм для вашего аддона можно двумя путями:

Задать фрейм в XML:

<Ui xmlns="http://www.blizzard.com/wow/ui/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.blizzard.com/wow/ui/ ..\..\FrameXML\UI.xsd"> <Frame name="HelloWorldFrame"> </Frame> </Ui>

В данном файле мы создали фрейм класса Frame с именем HelloWorldFrame.

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

Помимо определения элементов интерфейса в XML файлах, его можно создавать динамически с помощью API:

local frame = CreateFrame("FRAME", "FooAddonFrame");

Этот код создает простейший фрейм класса Frame с именем FooAddonFrame и помещает ссылку на него в переменную frame.

События

Создание окошек с кнопочками, это только половина дела. Ведь надо, чтобы аддон выполнял какие-то функции, т.е. взаимодействовал с игровым клиентом. Для этого используется система событий.

События

-

это служебные сообщения, которые клиент World of Warcraft посылает пользовательскому аддону, большая часть событий это реакция на вещи, происходящие в игровом мире.

Интерфейс World of Warcraft целиком построен на событиях: весь код, запускаемый в аддонах, запускается в ответ на то или иное событие. Выполнение кода должно быть закончено до того, как фрейм отрисовывается. Если обработка события занимает слишком много времени, или содержит бесконечный цикл, то клиент зависнет.

По существу, события в World of Warcraft можно разделить на два типа - События виджетов и Игровые события. На самом деле, события виджетов, это те же игровые события, но их обработка заранее зарегистрирована для любого фрейма. Но, обо всём по порядку.

Игровые события

Будем называть игровым событием то, что происходит внутри клиента World of Warcraft, будь то действия пользователя, или действия окружающего мира, например, использование заклинания.

В ответ на каждое событие, ваш аддон может предпринимать то или иное действие.

Для того, чтобы ваш аддон реагировал на игровое событие в World of Warcraft, вам нужно сделать несколько вещей:

1. Зарегистрировать событие, как "интересующее" ваш аддон. Делается это с помощью функции RegisterEvent:

   local frame = CreateFrame("FRAME", "FooAddonFrame"); frame:RegisterEvent("PLAYER_ENTERING_WORLD");

   Данный фрагмент кода создает фрейм класса Frame и регистрирует для него событие PLAYER_ENTERING_WORLD, срабатывающее, когда игрок входит в игровой мир.

   После выполнения данного кода, когда вы войдете в игровой мир, клиент World of Warcraft попытается найти обработчик события OnEvent для фрейма frame (который мы пока не задали).

2. Необходимо задать обработчик события OnEvent:

   local function eventHandler(self, event, ...) print("Hello World! Hello " .. event); end frame:SetScript("OnEvent", eventHandler);

   Данный фрагмент кода создает функцию с именем eventHandler, печатающую текст "Hello World! Hello" и назначает её обработчиком события OnEvent с помощью функции SetScript.

Обработчик события может быть создан динамически с помощью LUA, как указано в последнем примере, а может быть задан в XML файле в разделе Scripts с помощью элемента OnEvent:

<Frame name="FooAddonFrame"> <OnEvent> print("Hello World! Hello " .. event); </OnEvent> </Frame>

В качестве параметров в обработчик события подаются:

• self - ссылка на фрейм, который получает событие.
• event - имя события
• ... - дополнительные аргументы, значение и количество которых варьируется от события к событию.

Все игровые события, кроме событий виджетов, обрабатываются хендлером OnEvent. Если ваш аддон обрабатывает несколько событий, вы должны сами сделать ветвление внутри обработчика, в зависимости от переменной event. Подробнее об этом в одном из следующих выпусков.

Список игровых событий вы можете найти здесь: Список событий игрового клиента

События виджетов

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

• События виджетов по умолчанию зарегистрированы для вашего фрейма (в зависимости от класса фрейма)
• События виджетов обрабатываются отдельными элементами, а не OnEvent. Например, событие OnClick обрабатывается с помощью элемента <OnClick> и т.п.

Список событий можно найти здесь: Список событий виджетов

Продолжение: Как написать аддон для ВоВ. Сохранение настроек. Значения по умолчанию. Слэш команды.