ValuedText – это объект ( форматированная строка с подстановочным значением ), задача которого получение, хранение и использование ФОРМАТИРОВАННОГО текста.
Форматированный текст представляет собой
форматную строку с тэгами подстановки. Это WString, содержащий правильно форматированную строку XHTML, возможно, с CSS-тэгами и с тэгами подстановки значений:
подстановка текстовых значений <r name="..."/>
подстановка CSS-класса <rs class="...">...</rs>
и какие-либо подстановочные значения, подставляемый в тэги <r/> и </rs>
Поддерживаются:
базовые тэги
<default/>
<span/>
<p/>
CSS-тэги.
Полный список см. в common.GetCSSList()
В скриптах ValuedText - это специальный вариант userdata.
Перегруженные операции
# - взятие длины ValuedText. Важно! Считается по числу отображаемых символов, длина тегов оформления не учитывается
ValuedText создаётся с помощью common.CreateValuedText( values )
Замечание. Lua работает с userdata по ссылке, а не по значению. Поэтому, в частности, для создания отдельной копии ValuedText нужно пользоваться специальной функцией (CreateCopy).
Подставляются новые значения с помощью интерфейсного методов SetTextValues( self, values ), SetVal( self, key, value ).
Так же допустимо использовние:
SetClassVal( self, key, value ), SetTagAttributes( self, isRTag, tagName, tagAttributes ).
Не рекомендуется использовать:
SetFormat( self, format ), SetPlainText( self, text ).
Для подстановки используются только тэги <r/> и <rs>...</rs>.
В качестве подстановочных значений для тэга <r/> можно использовать WString, объекты ValuedText или ValuedObject.
В тэг <rs>...</rs> можно подставлять только имеющиеся CSS-классы (их названия типа string).
Поиск тэга подстановки производится по значению аттрибута "name" для тэга <r/> или значению аттрибута "class" тэга <rs>...</rs>. Эти тэги не должны содержать нетребующихся для форматирования аттрибутов. Если необходимый тэг <r/> не найден, то подстановочное значение сохраняется и потом будет подставлено, если у ValuedText появится такой подстановочный тэг после установки каких-либо других подстановочных значений.
Форматирующий текст, являющийся related-текстом аддона "FormatText":
<html> <header> text1 </header> <rs class="class01"> text2 <r name="value01"/> </rs> </html>
Скрипт:
local valuedText = common.CreateValuedText{
format = common.GetAddonRelatedText( "FormatText" ),
value01 = common.FormatInt( 2, "%d" ),
class01 = "header"
}
Для изменения текста используется функция SetTextValues().
Использование SetTextValues крайне рекомендовано в случаях подставления 3 и более значений, чтобы сделать это за один раз.
Также текстовики можно заводить ресурсно, создав и подключив его в необходимом аддоне, при создании текстовиков через ресурсы требуется учитывать кодировку текста, она СТРОГО должна быть UTF-16LE.
Отдельно стоит отметить, что при переопределять поле format не рекомендуется, после его изначального определения.
<r> - тэг подстановки текстовых значений.
<rs> - тэг подстановки стиля оформления.
<t> - тэг для повторного использования текстов в ресурсе
<object> - тэг объявления ValuedObject в ресурсе
<span> - тэг подстановки стилей текста
<f> - тэг подстановки текста для женских персонажей игроков
<m> - тэг подстановки текста для мужских персонажей игроков
<race> - тэг подстановки текста в зависимости от расы персонажа
<kania> - тэг подстановки текста если персонаж игрока каниец
<hadagan> - тэг подстановки текста если персонаж игрока хадаганец
<gibberling> - тэг подстановки текста если персонаж игрока гибберлинг
<elf> - тэг подстановки текста если персонаж игрока эльф
<orc> - тэг подстановки текста если персонаж игрока орк
<undead> - тэг подстановки текста если персонаж игрока зэм
<priden> - тэг подстановки текста если персонаж игрока прайден
<aed> - тэг подстановки текста если персонаж игрока аэд
<not_kania> - тэг подстановки текста если персонаж игрока не каниец
<not_hadagan> - тэг подстановки текста если персонаж игрока не хадаганец
<not_gibberling> - тэг подстановки текста если персонаж игрока не гибберлинг
<not_elf> - тэг подстановки текста если персонаж игрока не эльф
<not_orc> - тэг подстановки текста если персонаж игрока не орк
<not_undead> - тэг подстановки текста если персонаж игрока не зэм
<not_priden> - тэг подстановки текста если персонаж игрока не прайден
<not_aed> - тэг подстановки текста если персонаж игрока не аэд
<empire> - тэг подстановки текста если персонаж игрока входит в империю
<league> - тэг подстановки текста если персонаж игрока входит в лигу
<p2p> - тэг подстановки текста если персонаж на подписочном сервере
<f2p> - тэг подстановки текста если персонаж на бесплатном сервере
<username> - тэг подстановки имени текущего персонажа игрока в текст
<classname> - тэг подстановки класса текущего персонажа игрока в текст
Структура:
<r name="value" [parsing="no/yes/smart"]></r>
Является тэгом подстановки для динамической части текста.
Атрибуты:
name – ОБЯЗАТЕЛЬНЫЙ параметр, является именем подстановочной переменной в виде строки
parsing – тип разбора значения переменной, если не указан, то smart. Рекомендуется ставить “no” если известно, что в тег НЕ БУДУТ подставляться ValuedText. НЕ ИМЕЕТ и НЕ ПОДДЕРЖИВАЕТ атрибуты оформления в текстовиках (однако поддерживает в рантайме), стиль оформления задается родительским тэгом, например:
<h1 class="red"><r name="mob1"/r><h1>
Примеры использования:
Простая замена текста:
<r name="text1"/>
Тут атрибут name задает значение переменной, которое заменит тэг <r>.
В общем случае текст может содержать произвольное количество подстановочных значений. Сами подстановочные значения так-же могут, в свою очередь, являться сложно форматированным текстом со своими подстановочными значениями. Аттрибут 'parsing' определяет механизм разбора. Допускаются следующие значения:
parsing="no" - подстановочное значение не является Xhtml текстом
parsing="yes" - подстановочное значение является Xhtml текстом и подлежит рекурсивному разбору
parsing="smart" - делается попытка разобрать подстановочное значение как Xhtml без вывода сообщений о ошибках и предупреждений
не указано – работает как parsing="smart"
Данный тэг служит для изменения стиля текстовиков, сам по себе не выполняет никакую функцию кроме ХРАНЕНИЯ атрибутов стиля.
Структура:
<span atribute1=”value”…atributeN=”value”>Text</span>
Вместо Text можно вставить либо любой текст, либо тэг, например тэг <r>.
Тэг <rs> служит для динамической смены стиля оформления текста после разбора xhtml. Параметры подстановки описываются аттрибутами тэга.
Структура:
<rs class="name"></rs>
Атрибуты:
class - идентификатор стиля в таблице стилей
Правильное использование:
<rs class="tagstyle"><r name="text"/></rs> - верно(значение параметра 'class' отличается от значения параметра 'name') <r name="text" parsing="yes"> , где text='<rs class="tagstyle">Текст со сменой стиля</rs>'
Неправильное использование:
<rs class="text"><r name="text"/></rs> - не верно("text" и "text")
...
<r name="text" parsing="yes"> , где text='<rs class="text">Текст со сменой стиля</rs>' - конфликт имен переменных получается в момент подстановки
Описание тэга:
<t href="FilePath.txt"/>
Тэг следует использовать в случаях наличия одинаковых кусков текста в разных текстовых файлах.
Пример:
<html>Сегодня встало красное Солнце</html> <header>Вчера была необычайно яркое Солнце</header>
В данном случае “Солнце” можно вынести в отдельный файл, допустим с путем:
/Planets/Sun/text1.txt
Тогда тэг будет иметь вид -
<t href=”/Planets/Sun/text1.txt”>
и исходные файлы можно будет заменить на:
<html>Сегодня встало красное <t href=”/Planets/Sun/text1.txt”> </html> <header>Вчера была необычайно яркое <t href=”/Planets/Sun/text1.txt”> </header>
Меняется на имя текущего персонажа игрока.
Пример:
<html><p>Добро пожаловать в Новоград, <username/>!</p></html>
Результат:
Добро пожаловать в Новоград, Вася!
Меняется на название класса текущего персонажа игрока.
Пример:
<html>Мой друг, тоже <classname/>, как и ты...</html>
Результат:
Мой друг, тоже Паладин, как и ты...
Позволяют отображать только те фрагменты текста, которые соответствуют полу текущего персонажа игрока.
Тэг <m> для персонажей мужского пола.
Тэг <f> для персонажей женского пола.
Пример:
<html>Ты <m>мой лучший друг</m><f>моя лучшая подруга</f>!</html>
Результат для мужских персонажей:
Ты мой лучший друг!
Результат для женских персонажей:
Ты моя лучшая подруга!
Позволяют отображать определенный текст, соответствующий текущей расе персонажа игрока.
Пример:
<html><elf>Добро пожаловать домой</elf><ork>Вы в прекрасной форме</ork><not_elf>Эта земля принадлежит эльфам, тебе здесь не рады</not_elf>!</html>
Результат для персонажа-эльфа:
Добро пожаловать домой!
Результат для персонажа-орка:
Вы в прекрасной форме!
Результат для персонажа игрока-не эльфа:
Эта земля принадлежит эльфам, тебе здесь не рады!
Допускается вложение тэгов друг в друга например:
<html><not_elf>Эта земля принадлежит эльфам, тебе здесь не рады <not_ork>Чужеземец<not_ork></not_elf>!<html>
Результат для персонажа игрока-не эльфа и не орка:
Эта земля принадлежит эльфам, тебе здесь не рады Чужеземец!
Составные тэги позволяют комбинировать условия показа текста в зависимости от расы/рас. Имеет два аргумента:
name – ОБЯЗАТЕЛЬНЫЙ АРГУМЕНТ, в нем через разделитель перечисляются расы, для которых требуется отобразить текст, завернутый в тэг. Разделителем может быть пробел, табуляция, перенос строки или один из символов: . , : |
not = true – задает отрицание для аргумента в name
Пример использования:
<html><race name="elf">Только истинный эльф увидит эту надпись</race></html>
Примечание: в данному случаи в использовании тега <race> нету смысла, следует сразу применять тег <elf>.
<html><race name="elf,aed">Только истинный эльф ИЛИ аэд увидит эту надпись</race></html>
Пример использования аргумента 'not="true"':
<html><race name="elf" not="true">Только истинный эльф НЕ увидит эту надпись</race></html>
Примеры избыточности условий которые могут привести к неожиданному поведению:
<html><race name="not_elf">Только истинный НЕ эльф увидит эту надпись</race></html>
Пояснение: в данному случаи в использовании тега <race> нету смысла, следует сразу применять тег <not_elf>.
<html><race name="not_elf;not_orс">Только НЕ орки ИЛИ НЕ эльфы(т.е. все) увидят эту надпись</race></html>
Пояснение: в данному случаи текст будет показан ВСЕМ расам так как любые две разные группы 'not_*' в совокупности образуют полную группу.
<html><race name="not_elf;not_orс" not="true">Только НЕ орки ИЛИ НЕ эльфы(т.е. все) НЕ увидят эту надпись</race></html>
Пояснение: в данному случаи текст будет ВСЕГДА скрыт ото всех. Это не имеет смысла и является грубой ошибкой.
В целом, not_* не стоит использовать в качестве аргумента в теге <race>. Используйте их только в виде самостоятельных обособленных тегов <not_*>.
В целом, составные и простые фракционные тэги взаимозаменяемы, однако в случае комплексных фраз или фраз, которые необходимо показывать нескольким расам, старайтесь делать выбор в пользу составных тэгов.
Позволяют отображать определенный текст, соответствующий принадлежности персонажа игрока к той или иной расе.
Пример:
<html><empire>Слава империи</empire><league>Да здравствует лига</league></html>
Результат для персонажей из империи:
Слава империи!
Результат для персонажей из лиги:
Да здравствует лига!
Позволяют отображать определенный текст, соответствующий принадлежности персонажа игрока к бесплатному или подписочному серверу.
Пример:
<html>Приветствуем игрока на <f2p>бесплатном</f2p><p2p>подписочном</2p> сервере!</html>
color – цвет текста: (int)/(hexint)
outline – толщина обводки: int[0-2]
outlinecolor – цвет обводки: (int)/(hexint)
shadow – есть ли у текста тень: int[0-10]
alignx – выравнивание по горизонтали: ”center”/”left”/0
alignY – выравнивание по вертикали: ”top”/”middle”/”bottom”
shadowcolor – цвет тени: (int)/(hexint)
fontsize – размер шрифта: int[>0]
paragraph – есть ли обрамление текста переносами строки: ”false”/”true”
before – отступ абзаца сверху (работает только при paragraph=”true”): int[>=0]
worldWrap – имеется ли перенос по словам: ”false”/”true”
fontname – имя шрифта: (string)
linespacing: (float)
right to left – нужно ли перевернуть текст наоборот: “0”; “1”
offset: (int)
Данные атрибуты можно использовать в любом существующем тэге, однако следует учесть, что их не стоит их использовать в тэгах подстановки.
Основное достоинство применение Css в Xhtml - разделение данных (Xhtml) от оформления (Css). Для дизайнеров - это возможность использования множество различных вариантов оформления без изменения документа. Подробнее в CssParsing.
Создать свой стиль можно несколькими способами:
Создав новый CSS файл:
Через самостоятельное создание файла – создать файл с расширением .xdb, в название ЖЕЛАТЕЛЬНО включить .(WidgetCss). Далее в файле, имеющем структуру XML документа необходимо реализовать шапку/пролог ( <?xml version="1.0" encoding="UTF-8" ?> ), и создать корневой тэг <WidgetCss> и его закрывающий тэг </WidgetCss>, в нем необходимо задать тэг <Id> и <Selectors>, внутри же тэга Selectors и задаются стили под тегом <item>, свойства стилей задаются через перечисление пар ключ-значения в тэге <item> тэга <items> каждого стиля.
Каждый стиль должен иметь следующую структуру:
<item>
<Name>Имя_стиля</Name>
<items>
<Item>
<Key>имя_свойства</Key>
<Value>значение своства</Value>
</Item>
…………………….
<Item>
<Key>имя_свойства</Key>
<Value>значение своства</Value>
</Item>
</items>
</item>
Пример такого файла:
<?xml version="1.0" encoding="UTF-8" ?>
<WidgetCss>
<Id>Sample</Id>
<Selectors>
<Item>
<Name>header_sample</Name>
<Items>
<Item>
<Key>fontsize</Key>
<Value>50</Value>
</Item>
<Item>
<Key>color</Key>
<Value>0xffffe65e</Value>
</Item>
<Item>
<Key>fontname</Key>
<Value>AllodsFantasy</Value>
</Item>
<Item>
<Key>alignx</Key>
<Value>left</Value>
</Item>
</Items>
</Item>
</Selectors>
</WidgetCss>
После завершение начального редактирования файла его необходимо подключить в аддон, для этого необходимо найти файл, содержащий тип (UIAddon) и расширение xdb, найти в нем тэг styleSheets (если нет – задать в конце файла) и в нем указать путь к файлу со стилями относительно папки аддона.
Все создаваемые стили должны удовлетворять следующим условиям:
Обязательное указание атрибута Name в виде строки (например <Name>Simple</Name>).
Имя создаваемого стиля ДОЛЖНО БЫТЬ ГЛОБАЛЬНО УНИКАЛЬНЫМ, переопределять существующие стили НЕЛЬЗЯ.
Отдельно стоит отметить, что стиль, созданный в аддоне виден всем аддонам, до тех пор пока загружен его создатель, а также может быть использован в любых других аддонах.
При работе с ValuedText в скриптах, следует учитывать, что ValuedText является неиндексируемой userdata, а значит Lua видит его как ссылку.
Переопределенные операции для ValuedText. Следующие операции были переопределены для валидной работы с ValuedText:
Сравнение ( сравнивается по лексологической массе слов)
Длина
Равенство ( сравнивается по значению, а не ссылке )