resources/gui_and_objects/trassir_objects

Модуль используется для создания кастомных/использования готовых классов для создания объектов и событий в трассире.

Доступные классы и объекты

  • BaseObject - Базовый класс для создания объектов. 
  • Event - Класс для описания событий объекта.
  • State - Класс для описания состояний объекта
  • State.Value - Класс для описания возможных значений состояний объекта.
  • icons - Содержит возможные иконки, который можно использовать для создания состояний объектов.

icons.zip

Все доступные иконки можно скачать в архиве. Для удобства в архиве находится файл icons.html которы отображает все иконки. При клике по иконке в буфер обмена скопируется соотвестующий путь, который необходимо указать в описании.

После регистрации класса изменить его можно будет только после перезапуска Trassir

Аргументы класса BaseObject

  • name (str, optional): Имя созданного объекта.
  • guid (str, optional): Guid созданного объекта.
  • parent (str, optional): Guid родительского объекта.
  • folder (str, optional): Папка, куда будет помещен созданный объект в дереве объектов.
  • associated_channel (str, optional): Ассоциированный канал, связанный с объектом.

Атрибуты класса

Данные атрибуты необходимо задавать при создании собственного класса для объектов.

  • classname (str): Имя класса для созданного объекта. Если не задано - используется имя класса.
  • events (Tuple[Event]): Список событий для объекта.
  • states (Tuple[State]): Список состояний объекта.

Для каждого объекта можно задать список событий и состояний, которые в последствии можно будет генерировать и изменять. Каждое событие описывается с помощью объекта Event. А каждое состояний с помощью объекта State.

Примеры кода

ExampleObject

Создаем новый класс объектов Example.

Добавим классу события:

  • Winter is coming
  • Vacations is coming
  • Birthday %1 is coming

И состояния:

  • health - Здоровье объекта
    Список возможных значений:
    • OK
    • ERROR
    • Unknown
  • fire - Состояние "Пожар"
    Возможные значения:
    • Fire
    • No Fire

После чего создадим объект созданного класса.

Для каждого состояния класса можно задать соответствующую иконку. 
Первое, заданное состояние будет отображаться как главная иконка объекта.


import host
from base_object import BaseObject, Event, State, icons


class ExampleObject(BaseObject):
    classname = "Example"  # Задаем название класса
    
    # Задаем события которые сможет генерировать объект
    events = (
        Event("Winter is coming"),
        Event("Vacations is coming"),
        Event("Birthday %1 is coming"),
    )
    
    # Задаем возможные состояния объекта
    states = (
        State(
            "health",
            (
                State.Value("OK", icon=icons.Facer.face_recognizer),
                State.Value("ERROR", icon=icons.Settings.dead),
                State.Value("Unknown", icon=icons.Merge.edit_channel)
            )
        ),
        State(
            "fire",
            (
                State.Value("Fire", icon=icons.Archer.firedetector),
                State.Value("No Fire", icon=icons.Paradox.area_ready),
            )
        )
    )

obj = ExampleObject(name="Example 1", guid=host.random_guid())

После чего в дереве объектов у Вас появится созданной объект

Изменяем состояние объекта

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

# Описание класса
# ...

obj = ExampleObject(name="Example 1", guid=host.random_guid())

# Смена состояния health на значение 'ERROR'
obj.health = "ERROR"

# Смена состояния fire на значение 'No Fire'
obj.fire = "No Fire"

Генерируем события

Для генерации событий можно воспользоваться методом fire_event(event_type, p1, p2, p3)

# Описание класса
# ...

obj = ExampleObject(name="Example 1", guid=host.random_guid())

# Создадим событие 'Winter is coming'
obj.fire_event("Winter is coming", "", "", "")

# Создадим событие 'Birthday %1 is coming'
obj.fire_event("Birthday %1 is coming", "Ivan", "", "")

В событии можно пользоваться параметрами %1, %2, %3 за место которых в интерфейсе трассира будет подставляться соответствующие аргументы p1, p2, p3

Также данные события можно "отловить" с помощью метода host.activate_on_events в т.ч. в других скриптах.

import host


def handler(ev):
    host.message(
        "<b>%s</b><br>"
        "p1 = %r<br>"
        "p2 = %r<br>"
        "p3 = %r" % (ev.type, ev.p1, ev.p2, ev.p3)
    )


host.activate_on_events("Birthday %1 is coming", "", handler)

Вместо метода fire_event можно воспользоваться методом fire_event_ который позволяет передать стандартные параметры p1, p2, p3 в виде пустой строки. Пример кода ниже:

# Описание класса
# ...

obj = ExampleObject(name="Example 1", guid=host.random_guid())

# Создадим событие 'Winter is coming'
obj.fire_event_("Winter is coming")

# Создадим событие 'Birthday %1 is coming'
obj.fire_event_("Birthday %1 is coming", "Ivan")

Получить список всех созданных объектов можно с помощью метода host.objects_list(filter) где filter - название класса, например 'Example'

import host

host.message(host.objects_list("Example"))

Метод host.objects_list возвращает List[Tuple[str, str, str, str]] где каждый объект описывается с помощью кортежа, состоящего из:

  • Название
  • Guid
  • Classname
  • Parent

Для удобства одновременного изменения состояния объекта вместе с установкой соответствующих состояний создадим необходимые методы в класс ExampleObject. Изменять состояние будем с помощью нажатия клавиш F10, F11

import host
from base_object import BaseObject, Event, State, icons


class ExampleObject(BaseObject):
    classname = "Example"  # Задаем название класса

    # Задаем события которые сможет генирировать объект
    events = (
        Event("Winter is coming"),
        Event("Vacations is coming"),
        Event("Birthday %1 is coming"),
    )

    # Задаем возможные состояния объекта
    states = (
        State(
            "health",
            (
                State.Value("OK", icon=icons.Facer.face_recognizer),
                State.Value("ERROR", icon=icons.Settings.dead),
                State.Value("Unknown", icon=icons.Merge.edit_channel)
            )
        ),
        State(
            "fire",
            (
                State.Value("Fire", icon=icons.Archer.firedetector),
                State.Value("No Fire", icon=icons.Paradox.area_ready),
            )
        )
    )

    def vacations_is_coming(self):
        self.health = "OK"
        self.fire = "No Fire"
        self.fire_event_("Vacations is coming")

    def winter_is_coming(self):
        self.health = "Unknown"
        self.fire = "No Fire"
        self.fire_event_("Winter is coming")

    def birthday_is_coming(self, name):
        self.health = "ERROR"
        self.fire = "Fire"
        self.fire_event_("Birthday %1 is coming", name)


obj = ExampleObject(name="Example 1", guid=host.random_guid())


host.activate_on_shortcut("F10", obj.vacations_is_coming)
host.activate_on_shortcut("F11", obj.winter_is_coming)

ScriptObject

Пример описания существующего класса объекта скрипта.

from base_object import BaseObject, State


class ScriptObject(BaseObject):
    classname = "Script"
    states = (
        State("health", (State.Value("OK"), State.Value("Error"))),
        State("check_me", (State.Value("1"), State.Value("0"))),
    )

    def fire_event_v2(self, message, channel="", data=""):
        """Generate trassir script event

        Args:
            message (str): Event message (p1)
            channel (str, optional): Event associated channel (p2)
            data (str, optional): Event data (p3)
        """
        self.fire_event_("Script: %1", message, channel, data)

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