Хуки аддонів
Хуки — це точки з'єднання між вашим аддоном та Rayforge. Коли в додатку щось відбувається — створюється крок, відкривається діалог або ініціалізується вікно — Rayforge викликає всі зареєстровані хуки, щоб ваш аддон міг відреагувати.
Як працюють хуки
Rayforge використовує pluggy для своєї системи хуків. Щоб
реалізувати хук, декоруйте функцію за допомогою @pluggy.HookimplMarker("rayforge"):
import pluggy
hookimpl = pluggy.HookimplMarker("rayforge")
@hookimpl
def rayforge_init(context):
# Your code runs when Rayforge finishes initializing
pass
Вам не потрібно реалізовувати кожен хук — лише ті, які вам потрібні. Всі хуки опціональні.
Хуки життєвого циклу
Ці хуки обробляють загальний життєвий цикл вашого аддону.
rayforge_init(context)
Це ваша головна точка входу. Rayforge викликає цей хук після повної ініціалізації контексту додатку, що означає, що всі менеджери, конфігурації та обладнання готові. Використовуйте це для загального налаштування, логування або впровадження UI-елементів.
Параметр context — це екземпляр RayforgeContext, який дає вам доступ до всього в Rayforge.
Дивіться Доступ до даних Rayforge для деталей.
@hookimpl
def rayforge_init(context):
logger.info("My addon is starting up!")
machine = context.machine
if machine:
logger.info(f"Running on machine: {machine.id}")
on_unload()
Rayforge викликає це, коли ваш аддон відключається або вивантажується. Використовуйте це для очищення ресурсів, закриття з'єднань або скасування реєстрації обробників.
@hookimpl
def on_unload():
logger.info("My addon is shutting down")
# Clean up any resources here
main_window_ready(main_window)
Цей хук спрацьовує, коли головне вікно повністю ініціалізоване. Він корисний для реєстрації UI-сторінок, команд або інших компонентів, які потребують, щоб головне вікно вже існувало.
Параметр main_window — це екземпляр MainWindow.
@hookimpl
def main_window_ready(main_window):
# Add a custom page to the main window
from .my_page import MyCustomPage
main_window.add_page("my-page", MyCustomPage())
Хуки моніторингу завдань
Ці хуки повідомляють про життєвий цикл і поступ завдань, що виконуються на машині, щоб addons могли реагувати, коли завдання стартує, поступає, призупиняється, відновлюється чи завершується — наприклад, для запуску зовнішніх команд або оновлення системи розумного дому.
Усі вони отримують знімок JobStatus (rayforge.machine.job_status.JobStatus) — незмінний об'єкт
із такими полями:
machine_idтаmachine_name: ідентифікують машину, що виконує завданняkind:JobKind.SENDдля завдань випалювання,JobKind.FRAMEдля трасування контуруphase:JobPhase.RUNNINGабоJobPhase.PAUSEDstarted_at: час запуску завдання (секунди з початку епохи)elapsed_seconds: секунди, що минули з початку завданняtotal_distanceтаtraveled_distance: повна та пройдена довжина шляху в міліметрахprogress_fraction: виконана частка завдання, від0.0до1.0eta_seconds: оцінка секунд, що залишилися, абоNone, якщо невідомоestimated_seconds: модельна повна тривалість завдання в секундах, абоNone, якщо невідомо
Обробники виконуються в головному потоці й мають швидко повертатися; тривалу роботу (запуск підпроцесів, мережеві виклики) передавайте фоновому потоку.
on_job_started(status)
Викликається, коли завдання починає виконуватися на машині.
@hookimpl
def on_job_started(status):
logger.info(f"Job on {status.machine_name} started")
on_job_updated(status)
Викликається з оновленнями поступу під час виконання завдання, щонайбільше приблизно раз на секунду.
@hookimpl
def on_job_updated(status):
print(
f"Progress: {status.progress_fraction:.0%}, "
f"ETA {status.eta_seconds}s"
)
on_job_paused(status) / on_job_resumed(status)
Викликається, коли виконуване завдання входить у паузу подачі (feed hold) або виходить із неї.
on_job_finished(status, outcome, message="")
Викликається, коли завдання завершується, незалежно від того, як саме. Аргумент outcome — член
JobOutcome (COMPLETED, CANCELLED або FAILED), а message містить деталі помилки, коли
результат — FAILED. Для виконаних завдань progress_fraction знімка дорівнює 1.0.
@hookimpl
def on_job_finished(status, outcome, message=""):
if outcome == JobOutcome.FAILED:
notify(f"Job failed: {message}")
else:
notify(f"Job {outcome.name.lower()} on {status.machine_name}")
Останній знімок можна також опитувати між подіями: під час виконання завдання machine.current_job
повертає його JobStatus, або None, коли жодне завдання не виконується.
Ось повний addon, що запускає команду оболонки при кожній зміні стану завдання:
import subprocess
import pluggy
from rayforge.machine.job_status import JobOutcome
hookimpl = pluggy.HookimplMarker("rayforge")
@hookimpl
def on_job_started(status):
subprocess.Popen(["/usr/local/bin/notify-ha", "started"])
@hookimpl
def on_job_paused(status):
subprocess.Popen(["/usr/local/bin/notify-ha", "paused"])
@hookimpl
def on_job_resumed(status):
subprocess.Popen(["/usr/local/bin/notify-ha", "resumed"])
@hookimpl
def on_job_finished(status, outcome, message=""):
subprocess.Popen(["/usr/local/bin/notify-ha", outcome.name.lower()])
Хуки реєстрації
Ці хуки дозволяють реєструвати власні компоненти в різних реєстрах Rayforge.
register_machines(machine_manager)
Використовуйте це для реєстрації нових драйверів пристроїв. machine_manager — це екземпляр
MachineManager, який керує всіма конфігураціями пристроїв.
@hookimpl
def register_machines(machine_manager):
from .my_driver import MyCustomMachine
machine_manager.register("my_custom_machine", MyCustomMachine)
register_steps(step_registry)
Реєструє власні типи кроків, які з'являються в панелі операцій. step_registry — це екземпляр
StepRegistry.
@hookimpl
def register_steps(step_registry):
from .my_step import MyCustomStep
step_registry.register(MyCustomStep)
register_producers(producer_registry)
Реєструє власних продюсерів операцій, які генерують траєкторії інструменту. producer_registry — це
екземпляр ProducerRegistry.
@hookimpl
def register_producers(producer_registry):
from .my_producer import MyProducer
producer_registry.register(MyProducer)
register_transformers(transformer_registry)
Реєструє власні трансформери операцій для постобробки. Трансформери модифікують операції після того,
як продюсери їх згенерували. transformer_registry — це екземпляр TransformerRegistry.
@hookimpl
def register_transformers(transformer_registry):
from .my_transformer import MyTransformer
transformer_registry.register(MyTransformer)
register_commands(command_registry)
Реєструє команди редактора, які розширюють функціональність редактора документів. command_registry
— це екземпляр CommandRegistry.
@hookimpl
def register_commands(command_registry):
from .commands import MyCustomCommand
command_registry.register("my_command", MyCustomCommand)
register_actions(action_registry)
Реєструє дії вікна з опціональним розміщенням у меню та панелі інструментів. Дії — це спосіб
додавання кнопок, пунктів меню та клавіатурних скорочень. action_registry — це екземпляр
ActionRegistry.
from gi.repository import Gio
from rayforge.ui_gtk.action_registry import MenuPlacement, ToolbarPlacement
@hookimpl
def register_actions(action_registry):
action = Gio.SimpleAction.new("my-action", None)
action.connect("activate", on_my_action_activated)
action_registry.register(
action_name="my-action",
action=action,
addon_name="my_addon",
label="My Action",
icon_name="document-new-symbolic",
shortcut="<Ctrl><Alt>m",
menu=MenuPlacement(menu_id="tools", priority=50),
toolbar=ToolbarPlacement(group="main", priority=50),
)
register_layout_strategies(layout_registry)
Реєструє власні стратегії компонування для розміщення контенту в документі. layout_registry — це
екземпляр LayoutStrategyRegistry. Зауважте, що UI-метадані, такі як мітки та скорочення, мають
реєструватися через register_actions, а не тут.
@hookimpl
def register_layout_strategies(layout_registry):
from .my_layout import MyLayoutStrategy
layout_registry.register(MyLayoutStrategy, name="my_layout")
register_asset_types(asset_type_registry)
Реєструє власні типи ресурсів, які можуть зберігатися в документах. Це забезпечує динамічну
десеріалізацію ресурсів, наданих аддонами. asset_type_registry — це екземпляр AssetTypeRegistry.
@hookimpl
def register_asset_types(asset_type_registry):
from .my_asset import MyCustomAsset
asset_type_registry.register(MyCustomAsset, type_name="my_asset")
register_renderers(renderer_registry)
Реєструє власні рендерери для відображення ваших типів ресурсів в UI. renderer_registry — це
екземпляр RendererRegistry.
@hookimpl
def register_renderers(renderer_registry):
from .my_renderer import MyAssetRenderer
renderer_registry.register(MyAssetRenderer())
register_exporters(exporter_registry)
Реєструє експортери файлів для власних форматів експорту. exporter_registry — це екземпляр
ExporterRegistry.
@hookimpl
def register_exporters(exporter_registry):
from .my_exporter import MyCustomExporter
exporter_registry.register(MyCustomExporter)
register_importers(importer_registry)
Реєструє імпортери файлів для власних форматів імпорту. importer_registry — це екземпляр
ImporterRegistry.
@hookimpl
def register_importers(importer_registry):
from .my_importer import MyCustomImporter
importer_registry.register(MyCustomImporter)
register_material_libraries(library_manager)
Реєструє додаткові бібліотеки матеріалів. Викличте library_manager.add_library_from_path(path),
щоб зареєструвати директорії, що містять YAML-файли матеріалів. За замовчуванням зареєстровані
бібліотеки доступні лише для читання.
@hookimpl
def register_material_libraries(library_manager):
from pathlib import Path
lib_path = Path(__file__).parent / "materials"
library_manager.add_library_from_path(lib_path)
Хуки розширення UI
Ці хуки дозволяють розширювати існуючі UI-компоненти.
step_settings_loaded(dialog, step, producer)
Rayforge викликає це, коли діалог налаштувань кроку заповнюється. Ви можете додати власні віджети до діалогу на основі типу продюсера кроку.
dialog — це екземпляр GeneralStepSettingsView. step — це Step, що налаштовується. producer
— це екземпляр OpsProducer або None, якщо недоступний.
@hookimpl
def step_settings_loaded(dialog, step, producer):
# Only add widgets for specific producer types
if producer and producer.__class__.__name__ == "MyCustomProducer":
from .my_widget import create_custom_widget
dialog.add_widget(create_custom_widget(step))
transformer_settings_loaded(dialog, step, transformer)
Викликається при заповненні налаштувань постобробки. Додавайте власні віджети для ваших трансформерів тут.
dialog — це екземпляр PostProcessingSettingsView. step — це Step, що налаштовується.
transformer — це екземпляр OpsTransformer.
@hookimpl
def transformer_settings_loaded(dialog, step, transformer):
if transformer.__class__.__name__ == "MyCustomTransformer":
from .my_widget import create_transformer_widget
dialog.add_widget(create_transformer_widget(transformer))
Історія версій API
Хуки версіонуються для підтримки зворотної сумісності. Коли додаються нові хуки або змінюються
існуючі, версія API збільшується. Поле api_version вашого аддону має бути не менше мінімальної
підтримуваної версії.
Поточна версія API — 24. Ось що змінилося в останніх версіях:
Версія 24 додала хуки моніторингу завдань on_job_started, on_job_updated, on_job_paused,
on_job_resumed і on_job_finished, а також API опитування Machine.current_job.
Версія 9 додала main_window_ready, register_exporters, register_importers та
register_renderers.
Версія 8 додала register_asset_types для власних типів ресурсів.
Версія 7 додала register_material_libraries.
Версія 6 додала register_transformers.
Версія 5 замінила register_step_widgets на step_settings_loaded та
transformer_settings_loaded.
Версія 4 видалила register_menu_items та консолідувала реєстрацію дій у register_actions.
Версія 2 додала register_layout_strategies.
Версія 1 була початковим релізом з базовими хуками для життєвого циклу аддону, реєстрації ресурсів та UI-інтеграції.