resources/gui_and_objects/trassir_objects

This module is used to create custom classes or to use ready-made classes for creating objects and events in Trassir.

Available classes and objects

  • BaseObject - Base class for object creating.
  • Event - Class for object events description.
  • State - Class for object states description.
  • State.Value - Class for describing the possible values of the object states.
  • icons - Contains possible icons that can be used to create object states.

icons.zip

All available icons can be downloaded from the archive. For convenience, the archive contains the icons.html file that displays all the icons. By clicking on the icon, the corresponding path will be copied to the clipboard, which must be indicated in the description.

After the class registration, it will be possible to change it only after restarting Trassir

BaseObject class attributes

  • name (str, optional): Name of created object.
  • guid (str, optional): Guid of created object.
  • parent (str, optional): Guid of parent object.
  • folder (str, optional): Folder where created object will be placed in the object tree.
  • associated_channel (str, optional): Channel associated with an object.

Class attributes

These attributes must be set when creating your own class for objects.

  • classname (str): Class name for created object.
  • events (Tuple[Event]): Object events list.
  • states (Tuple[State]): Object states list.

For each object, you can specify a list of events and states, which can be then generated and changed. Each event is described using an Event object. And each state - using a State object.

Code examples

ExampleObject

Creating a new class of objects named Example.

Let's add events to a class:

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

And events:

  • health - Object's health
    Available values:
    • OK
    • ERROR
    • Unknown
  • fire - "Fire" state
    Available values
    • Fire
    • No Fire

Then let's create class object

For each state of the class, you can set a corresponding icon.
The first set state will be displayed as the main object icon.


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


class ExampleObject(BaseObject):
    classname = "Example"  # Setting the class name
    
    # Events setting that the object can generate
    events = (
        Event("Winter is coming"),
        Event("Vacations is coming"),
        Event("Birthday %1 is coming"),
    )
    
    # Available object states setting
    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())

After that, the created object will appear in the object tree

Changing the object state

For all states that were specified during the description of the object, the corresponding parameters are created, using them you can change states.

# Class description
# ...

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

# health state change to 'ERROR' value
obj.health = "ERROR"

# fire state change to 'No Fire' value
obj.fire = "No Fire"

Event generating

You can use method fire_event(event_type, p1, p2, p3) to generate events

# Class description
# ...

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

# 'Winter is coming' event creation
obj.fire_event("Winter is coming", "", "", "")

# 'Birthday %1 is coming' event creation
obj.fire_event("Birthday %1 is coming", "Ivan", "", "")

In the event, we can use parameters %1, %2, %3 for the place of which the corresponding arguments   p1, p2, p3 will be substituted in Trassir interface

Also, these events can be "caught" using the host.activate_on_events method, incl. in the other scripts.

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)

Instead of the fire_event method, you can use fire_event_ which allows to give parameters p1, p2, p3 as an empty string. Sample code below:

# Class description
# ...

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

# 'Winter is coming' event creation
obj.fire_event_("Winter is coming")

# 'Birthday %1 is coming' event creation
obj.fire_event_("Birthday %1 is coming", "Ivan")

You can get a list of all created objects using the method host.objects_list(filter) , where filter - is a class name, like 'Example'

import host

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

Method host.objects_list returns List[Tuple[str, str, str, str]] , where each object is described using a tuple consisting of:

  • Name
  • Guid
  • Classname
  • Parent

For the convenience of simultaneously changing the state of an object along with the setting of the corresponding states, let's create necessary methods in the ExampleObject class. F10, F11 keys will change the state.

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


class ExampleObject(BaseObject):
    classname = "Example"  # Class name setting

    # Задаем события которые сможет генирировать объект Setting the events which object will be able to generate
    events = (
        Event("Winter is coming"),
        Event("Vacations is coming"),
        Event("Birthday %1 is coming"),
    )

    # Setting the possible object states
    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

An example of a description of an existing script object class.

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)

An example of using this class is provided in the article Creating events



  • Нет меток