=== УСТРАНОВКА ===

1. Копировать в дополнение папку MenuZ.
2. В AddonDesc.(UIAddon).xdb в тег ScriptFileRefs добавить ссылки на элементы "MenuZ/MenuScript.lua".
3. В AddonDesc.(UIAddon).xdb в тег textsGroups добавить группы локализаций MenuZ_eng_eu (MenuZ/Texts/eng_eu/Texts.(UIRelatedTexts).xdb), MenuZ_rus (MenuZ/Texts/rus/Texts.(UIRelatedTexts).xdb) и прочие имеющиеся локализации.
4. В AddonDesc.(UIAddon).xdb в тег widgetGroups добавить группу виджетов MenuZ_Widgets (MenuZ/Widgets/Widgets.(UIRelatedWidgets).xdb).
5. Инициализировать в скрипте с помощью MenuZ.Init.
6. Построить меню в скрипте с помощью MenuZ.BuildMenu, передав как минимум таблицу настроек или таблицу параметров.


=== ИСПОЛЬЗОВАНИЕ ===

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

=== ОПИСАНИЕ ГЛОБАЛЬНЫХ ФУНКЦИЙ ===

MenuZ.Init(changesHandler, menuSettings, messagesHandler) - инициализирует меню, пытается прикрепить кнопку входа в меню, подписывается на нужные реакции. Допускается повторный запуск для изменения свойств меню.
	changesHandler function|nil - обработчик изменений (будет вызываться при изменении каких-либо настроек в меню, передаваться будет таблица с изменениями).
	menuSettings table|nil - настройки меню (см. ниже).
	messagesHandler function|nil - обработчик сообщений (будет вызываться при различных действиях в меню, первым параметром передаваться будет строка с сообщением, а вторым число с уровнем сообщения).

		Настройки меню (menuSettings):
			sizeX: number|nil - задают размер окна меню по X в диапазоне от 429 до 1300 (по умолчанию 650).
			sizeY: number|nil - задают размер окна меню по Y в диапазоне от 255 до 1100 (по умолчанию 800).
			lang: string|nil - строка с названием локализации, которая будет использована принудительно, если такая есть в наличии, а если нет, то будет использовано автоопределение или "eng_eu" (по умолчанию локализация клиента игры).
			messagesLevel: number|nil - уровень сообщений для вызова обработчика сообщений: 0 - отладочный, 1 - информационный (по умолчанию 0).

MenuZ.BuildMenu(menuTable, paramsTable, header, buildNow) - строит меню или ставит его постройку в очередь, включает кнопку вызова меню. Обязательно должно быть передано menuTable или paramsTable. Если меню уже было построено, то для перестройки необходимо сначала его очистить.
	menuTable: table|nil - таблица настроек, где ключи - имена настроек, а значения - значения настроек. Если отсутствуют параметры в таблице параметров, то выбирается соответствующий тип элемента меню по типу значения. Поддерживаемые типы:
		- boolean - логическое значение (true/false), выбирается элемент CheckBox;
		- number - реальные (с плавающей запятой) числа, выбирается элемент InputLineNumber;
		- WString - локализуемая строка (является userdata) выбирается элемент InputLine;
		- string - встроенная строка Lua (не путать с WString) выбирается элемент InputLine;
		- table - Lua таблица, поддерживаются отдельные типы Color (таблица особого вида для задания цвета) и List (индексированная таблица строк) или общая DynamicTable. Выбирается элемент ColorTable (таблица с параметрами r, g, b, a) или List (таблица с числовыми индексами содержащими number или string), если определяется соответствие с ними, иначе DynamicTable.
	paramsTable: table|nil - индексированная таблица таблиц параметров для постройки меню. Меню строится в порядке индексов, пропуски индексов не допускаются, а пропуски параметров допускаются. Для каждого типа элементов меню можно задать различные параметры, поле type указывает на тип параметра.
	header: WString|string|nil - строка с заголовком окна меню (по умолчанию название дополнения).
	buildNow: boolean|nil - логическое значение (true/false) с требованием построить меню немедленно, иначе меню строится при первом вызове (экономит ресурс на постройку и память, если меню не вызывалось ни разу за игровую сессию).

MenuZ.ClearMenu() - безусловно очищает меню, отключает кнопку вызова меню. Обязательно используется перед новым построением меню.

MenuZ.Version - версия скрипта (7.02)

=== ТИПЫ ЭЛЕМЕНТОВ МЕНЮ ===

CheckBox - это элемент меню в виде галочки. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "CheckBox".
	- setting: string - ключ настройки. При изменении меню значение этого параметра возвращается под этим ключом. Это обязательное поле. Для корректной работы ключ должен быть уникальным.
	- value: boolean - значение настройки. Используется это значение или значение ключа из таблицы настроек или false.
	- name: WString|string - имя настройки, которое будет отображаться в меню. Используется это значение или ключ настройки.
	- description: WString|string - описание настройки, которое будет отображаться в меню. Используется это значение или пустая строка.
	- default: boolean - значение по умолчанию, которое будет отображаться в меню после описания и устанавливаться по нажатию на кнопку сброса. Используется это значение или значение настройки. Если не задан ни разу, то кнопка сброса будет недоступна.
Пример: { type = "CheckBox", setting = "TestCheckBox", value = false, name = "Тест галочки", description = "Описание теста галочки.", default = true }

ColorTable - это элемент меню в виде регулировки цвета RGB с прозрачностью и предпросмотром. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "ColorTable".
	- setting: string - ключ настройки. При изменении меню значение этого параметра возвращается под этим ключом. Это обязательное поле. Для корректной работы ключ должен быть уникальным.
	- value: table - значение настройки. Используется это значение или значение ключа из таблицы настроек или { r = 0, g = 0, b = 0, a = 0 }.
	- name: WString|string - имя настройки, которое будет отображаться в меню. Используется это значение или ключ настройки.
	- description: WString|string - описание настройки, которое будет отображаться в меню. Используется это значение или пустая строка.
	- default: table - значение по умолчанию, которое будет отображаться в меню после описания и устанавливаться по нажатию на кнопку сброса. Используется это значение или значение настройки. Если не задан ни разу, то кнопка сброса будет недоступна.
Пример: { type = "ColorTable", setting = "TestColorTable", value = { r = 0.5, g = 0.5, b = 0.5, a = 0.75 }, name = "Тест таблицы цвета", description = "Описание теста таблицы цвета.", default = { r = 0.1, g = 0.1, b = 0.1, a = 0.95 } }

DynamicTable - это элемент меню в виде таблицы, где используется автоопределение типов значений и возможно изменение индексов. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "DynamicTable".
	- setting: string - ключ настройки. При изменении меню значение этого параметра возвращается под этим ключом. Это обязательное поле. Для корректной работы ключ должен быть уникальным.
	- value: table - значение настройки. Используется это значение или значение ключа из таблицы настроек или пустая таблица.
	- name: WString|string - имя настройки, которое будет отображаться в меню. Используется это значение или ключ настройки.
	- description: WString|string - описание настройки, которое будет отображаться в меню. Используется это значение или пустая строка.
	- default: table - значение по умолчанию, которое будет отображаться в меню после описания и устанавливаться по нажатию на кнопку сброса. Используется это значение или значение настройки. Если не задан ни разу, то кнопка сброса будет недоступна.
	- sort: string - сортировка таблицы по ключам/значениям ("byKey"/"byValue") и возрастанию/убыванию("byKeyAscending"/"byKeyDescending"/"byValueAscending"/"byValueDescending"). Таблица сортируется по этому значению или по ключам.
Пример: { type = "DynamicTable", setting = "TestDynamicTable", value = { first = 1, second = "second", third = {[1] = true}, forth = false}, name = "Тест динамической таблицы", description = "Описание теста динамической таблицы.", sort = "byKey", default = { first = 1, second = "two", third = {[1] = true}, forth = false} }

Header - это элемент меню в виде статичного заголовка. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "Header".
	- name: WString|string - имя настройки, которое будет отображаться в меню. Используется это значение или пустая строка.
Пример: { type = "Header", name = "Тест заголовка" }

InputLine - это элемент меню в виде строки ввода. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "InputLine".
	- setting: string - ключ настройки. При изменении меню значение этого параметра возвращается под этим ключом. Это обязательное поле. Для корректной работы ключ должен быть уникальным.
	- value: WString|string - значение настройки. Используется это значение или значение ключа из таблицы настроек преобразованные в строку.
	- name: WString|string - имя настройки, которое будет отображаться в меню. Используется это значение или ключ настройки.
	- description: WString|string - описание настройки, которое будет отображаться в меню. Используется это значение или пустая строка.
	- default: WString|string - значение по умолчанию, которое будет отображаться в меню после описания и устанавливаться по нажатию на кнопку сброса. Используется это значение или значение настройки. Если не задан ни разу, то кнопка сброса будет недоступна.
Пример: { type = "InputLine", setting = "TestInputLine", value = "Тест строки.", name = "Тест строки ввода", description = "Описание теста строки ввода.", default = "Тест строки ввода." },

InputLineNumber - это элемент меню в виде строки ввода принимающей только числа. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "InputLineNumber".
	- setting: string - ключ настройки. При изменении меню значение этого параметра возвращается под этим ключом. Это обязательное поле. Для корректной работы ключ должен быть уникальным.
	- value: number - значение настройки. Используется это значение или значение ключа из таблицы настроек преобразованные в число, которое не меньше заданного в поле min, не больше заданного в поле max, или 0.
	- name: WString|string - имя настройки, которое будет отображаться в меню. Используется это значение или ключ настройки.
	- description: WString|string - описание настройки, которое будет отображаться в меню. Используется это значение или пустая строка.
	- default: number - значение по умолчанию, которое будет отображаться в меню после описания и устанавливаться по нажатию на кнопку сброса. Используется это значение или значение настройки. Если не задан ни разу, то кнопка сброса будет недоступна.
	- min: number - минимальное значение, значения ниже которого заменяются минимальным.
	- max: number - максимальное значение, значения выше которого заменяются максимальным.
Пример: { type = "InputLineNumber", setting = "TestInputLineNumber", value = 6000, name = "Тест строки ввода числа", description = "Описание теста строки ввода числа.", default = 12000, min = 500, max = 20000 }

List - это элемент меню в виде строго нумерованного редактируемого списка строк. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "List".
	- setting: string - ключ настройки. При изменении меню значение этого параметра возвращается под этим ключом. Это обязательное поле. Для корректной работы ключ должен быть уникальным.
	- value: table - значение настройки. Используется это значение или значение ключа из таблицы настроек или пустая таблица.
	- name: string - имя настройки, которое будет отображаться в меню. Используется это значение или ключ настройки.
	- description: string - описание настройки, которое будет отображаться в меню. Используется это значение или пустая строка.
	- default: table - значение по умолчанию, которое будет отображаться в меню после описания и устанавливаться по нажатию на кнопку сброса. Используется это значение или значение настройки. Если не задан ни разу, то кнопка сброса будет недоступна.
Пример: { type = "List", setting = "TestList", value = {"Раз","Два"}, name = "Пробный список", description = "Описание пробного списка", default = {"Раз","Два","Три"} }

Separator - это элемент меню в виде статичного разделителя. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "Separator".
	- height: number - высота отступа. По умолчанию 30.
Пример: { type = "Separator", height = 30 }

Slider - это элемент меню в виде строки ввода принимающей только числа со слайдером, который двигается между минимальным и максимальным значениями с заданным количеством шагов. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "Slider".
	- setting: string - ключ настройки. При изменении меню значение этого параметра возвращается под этим ключом. Это обязательное поле. Для корректной работы ключ должен быть уникальным.
	- value: number - значение настройки. Используется это значение или значение ключа из таблицы настроек преобразованные в число, которое не меньше заданного в поле min, не больше заданного в поле max, или 0.
	- name: WString|string - имя настройки, которое будет отображаться в меню. Используется это значение или ключ настройки.
	- description: WString|string - описание настройки, которое будет отображаться в меню. Используется это значение или пустая строка.
	- default: number - значение по умолчанию, которое будет отображаться в меню после описания и устанавливаться по нажатию на кнопку сброса. Используется это значение или значение настройки. Если не задан ни разу, то кнопка сброса будет недоступна.
	- min: number - минимальное значение, значения ниже которого заменяются минимальным. Это обязательное поле.
	- max: number - максимальное значение, значения выше которого заменяются максимальным. Это обязательное поле.
	- steps: number - количество шагов слайдера. По умолчанию 100.
Пример: { type = "Slider", setting = "TestSlider", value = 10000, name = "Тест слайдера", description = "Описание теста слайдера.", default = 12000, min = 0, max = 20000, steps = 40 }

StaticTable - это элемент меню в виде таблицы, где используется автоопределение типов значений и невозможно изменение индексов. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "StaticTable".
	- setting: string - ключ настройки. При изменении меню значение этого параметра возвращается под этим ключом. Это обязательное поле. Для корректной работы ключ должен быть уникальным.
	- value: table - значение настройки. Используется это значение или значение ключа из таблицы настроек или пустая таблица.
	- name: WString|string - имя настройки, которое будет отображаться в меню. Используется это значение или ключ настройки.
	- description: WString|string - описание настройки, которое будет отображаться в меню. Используется это значение или пустая строка.
	- default: table - значение по умолчанию, которое будет отображаться в меню после описания и устанавливаться по нажатию на кнопку сброса. Используется это значение или значение настройки. Если не задан ни разу, то кнопка сброса будет недоступна.
	- sort: string - сортировка таблицы по ключам/значениям ("byKey"/"byValue") и возрастанию/убыванию("byKeyAscending"/"byKeyDescending"/"byValueAscending"/"byValueDescending"). Таблица сортируется по этому значению или по ключам.
	- order: table - позволяет задать строгий порядок ключей в таблице в виде индексированной таблицы, где ключи - порядковый номер, а значения - ключ в таблице, если задан, выводятся только указанные ключи строго по порядку до первого nil.
	- valuesNames: table - позволяет задать видимые имена для ключей в виде таблицы, где ключи - ключ в таблице, а значения - строка с произвольным именем ключа, которое будет отображаться в интерфейсе для этого ключа в таблице.
Пример: { type = "StaticTable", setting = "TestStaticTable", value = { first = 2, second = "two", third = {[1] = true}, forth = false}, name = "Тест статичной таблицы", description = "Описание теста статичной таблицы.", order = {"first","second","third","forth"}, sort = "byKey", valuesNames = { first = "Первый", second = "Второй" }, default = { first = 1, second = "two", third = {[1] = true}, forth = false} }

Switch - это элемент меню в виде последовательного переключателя вариантов, где variants - это список вариантов, каждый из которых является строкой, а value - это один из таких вариантов. Поля таблицы параметров:
	- type: string - тип настройки. В данном случае "Switch".
	- setting: string - ключ настройки. При изменении меню значение этого параметра возвращается под этим ключом. Это обязательное поле. Для корректной работы ключ должен быть уникальным.
	- value: WString|string - значение настройки. Используется это значение или значение ключа из таблицы настроек, если они есть в вариантах, преобразованные в строку.
	- name: WString|string - имя настройки, которое будет отображаться в меню. Используется это значение или ключ настройки.
	- description: WString|string - описание настройки, которое будет отображаться в меню. Используется это значение или пустая строка.
	- default: WString|string - значение по умолчанию, которое будет отображаться в меню после описания и устанавливаться по нажатию на кнопку сброса. Используется это значение или значение настройки. Если не задан ни разу, то кнопка сброса будет недоступна.
	- variants: table - варианты переключателя. Индексированная таблица строк или локализованных строк. Это обязательное поле.
	- styleSwitch: boolean - true, если надо применять одноименные стили текста к тексту вариантов.
Пример: { type = "Switch", setting = "TestSwitch", value = "Второй", name = "Тест переключателя", description = "Описание теста переключателя.", variants = {"Первый", "Второй", "Третий", "CombatRed"}, default = "Первый", styleSwitch = true }


=== ПРИМЕРЫ ===

Пример заполнения AddonDesc.(UIAddon).xdb:
	<ScriptFileRefs>
		<Item href="MenuZ/MenuScript.lua" />
	</ScriptFileRefs>
	<textsGroups>
		<Item>
			<groupName>MenuZ_eng_eu</groupName>
			<texts href="MenuZ/Texts/eng_eu/Texts.(UIRelatedTexts).xdb"/>
		</Item>
		<Item>
			<groupName>MenuZ_rus</groupName>
			<texts href="MenuZ/Texts/rus/Texts.(UIRelatedTexts).xdb"/>
		</Item>
	</textsGroups>
	<widgetGroups>
		<Item>
			<groupName>MenuZ_Widgets</groupName>
			<widgets href="MenuZ/Widgets/Widgets.(UIRelatedWidgets).xdb" />
		</Item>
	</widgetGroups>

Пример таблицы menuTable:
{
		TestCheckBox = true,
		TestColorTable = { r = 0.1, g = 0.1, b = 0.1, a = 0.95 },
		TestDynamicTable = { first = 1, second = "two", third = {[1] = true}, forth = false},
		TestInputLine = "Тест строки ввода.",
		TestInputLineNumber = 12000,
		TestList = {"Один","Два","Три","Четыре","Пять","Шесть","Семь","Восемь","Девять","Десять"},
		TestSlider = 12000,
		TestStaticTable = { first = 1, second = "two", third = {[1] = true}, forth = false},
		TestSwitch = "Первый"
}

Пример таблицы paramsTable:
{
		{ setting = "TestCheckBox",
		  type = "CheckBox",
		  name = "Тест галочки",
		  description = "Описание теста галочки.",
		  default = true },
		{ setting = "TestColorTable",
		  type = "ColorTable",
		  name = "Тест таблицы цвета",
		  description = "Описание теста таблицы цвета.",
		  default = { r = 0.1, g = 0.1, b = 0.1, a = 0.95 } },
		{ setting = "TestDynamicTable",
          type = "DynamicTable",
          name = "Тест динамической таблицы",
          description = "Описание теста динамической таблицы.",
          sort = "byKey",
          default = { first = 1, second = "two", third = {[1] = true}, forth = false} },
		{ type = "Header",
		  name = "Тест заголовка" },
		{ setting = "TestInputLine",
		  type = "InputLine",
		  name = "Тест строки ввода",
		  description = "Описание теста строки ввода.",
		  default = "Тест строки ввода." },
		{ setting = "TestInputLineNumber",
		  type = "InputLineNumber",
		  name = "Тест строки ввода числа",
		  description = "Описание теста строки ввода числа.",
		  default = 12000,
		  min = 500,
		  max = 20000 },
		{ setting = "TestList",
		  type = "List",
		  name = "Пробный список",
		  description = "Описание пробного списка",
		  default = {"Раз","Два","Три"} },
		{ setting = "TestSlider",
		  type = "Slider",
		  name = "Тест слайдера",
		  description = "Описание теста слайдера.",
		  default = 12000,
		  min = 0,
		  max = 20000,
		  steps = 40 },
		{ type = "Separator",
		  height = 30 },
		{ setting = "TestStaticTable",
		  type = "StaticTable",
		  name = "Тест статичной таблицы",
		  description = "Описание теста статичной таблицы.",
		  order = {"first","second","third","forth"},
		  sort = "byKey",
		  default = { first = 1, second = "two", third = {[1] = true}, forth = false} },
		{ setting = "TestSwitch",
		  type = "Switch",
		  name = "Тест переключателя",
		  description = "Описание теста переключателя.",
		  variants = {"Первый", "Второй", "Третий", "CombatRed"},
		  default = "Первый",
		  styleSwitch = true },
}