Pular para o conteúdo principal

Hooks de Addons

Hooks são os pontos de conexão entre seu addon e o Rayforge. Quando algo acontece na aplicação—um passo é criado, um diálogo abre, ou a janela inicializa—o Rayforge chama quaisquer hooks registrados para que seu addon possa responder.

Como os Hooks Funcionam​

O Rayforge usa pluggy para seu sistema de hooks. Para implementar um hook, decore uma função com @pluggy.HookimplMarker("rayforge"):

import pluggy

hookimpl = pluggy.HookimplMarker("rayforge")

@hookimpl
def rayforge_init(context):
# Seu código executa quando o Rayforge termina de inicializar
pass

Você não precisa implementar todos os hooks—apenas aqueles que precisa. Todos os hooks são opcionais.

Hooks de Ciclo de Vida​

Estes hooks gerenciam o ciclo de vida geral do seu addon.

rayforge_init(context)​

Este é seu ponto de entrada principal. O Rayforge chama este hook depois que o contexto da aplicação está totalmente inicializado, significando que todos os gerenciadores, configurações e hardware estão prontos. Use-o para configuração geral, logging ou injeção de elementos de interface.

O parâmetro context é uma instância de RayforgeContext que dá acesso a tudo no Rayforge. Veja Acessando Dados do Rayforge para detalhes.

@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()​

O Rayforge chama isto quando seu addon está sendo desabilitado ou descarregado. Use-o para limpar recursos, fechar conexões ou remover handlers registrados.

@hookimpl
def on_unload():
logger.info("My addon is shutting down")
# Limpe quaisquer recursos aqui

main_window_ready(main_window)​

Este hook é disparado quando a janela principal está totalmente inicializada. É útil para registrar páginas de interface, comandos ou outros componentes que precisam que a janela principal exista primeiro.

O parâmetro main_window é a instância de MainWindow.

@hookimpl
def main_window_ready(main_window):
# Adiciona uma página personalizada à janela principal
from .my_page import MyCustomPage
main_window.add_page("my-page", MyCustomPage())

Hooks de Monitoramento de Trabalho​

Esses hooks informam o ciclo de vida e o progresso dos trabalhos executados em uma máquina, para que os addons possam reagir quando um trabalho inicia, avança, é pausado, retomado ou finalizado — por exemplo, para executar comandos externos ou atualizar um sistema de casa inteligente.

Todos recebem um instantâneo JobStatus (rayforge.machine.job_status.JobStatus), um objeto imutável com estes campos:

  • machine_id e machine_name: identificam a máquina que executa o trabalho
  • kind: JobKind.SEND para trabalhos de gravação, JobKind.FRAME para traçados de contorno
  • phase: JobPhase.RUNNING ou JobPhase.PAUSED
  • started_at: hora do relógio (segundos desde a época) em que o trabalho iniciou
  • elapsed_seconds: segundos decorridos desde o início do trabalho
  • total_distance e traveled_distance: comprimento total e percorrido do trajeto, em milímetros
  • progress_fraction: fração concluída do trabalho, de 0.0 a 1.0
  • eta_seconds: segundos restantes estimados, ou None quando desconhecido
  • estimated_seconds: duração total modelada do trabalho em segundos, ou None quando desconhecido

Os handlers rodam na thread principal e devem retornar rapidamente; entregue trabalhos longos (como iniciar subprocessos ou chamadas de rede) a uma thread em segundo plano.

on_job_started(status)​

Chamado quando um trabalho começa a ser executado em uma máquina.

@hookimpl
def on_job_started(status):
logger.info(f"Job on {status.machine_name} started")

on_job_updated(status)​

Chamado com atualizações de progresso enquanto o trabalho roda, no máximo cerca de uma vez por segundo.

@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)​

Chamado quando o trabalho em execução entra ou sai de uma pausa de alimentação (feed hold).

on_job_finished(status, outcome, message="")​

Chamado quando um trabalho termina, independentemente de como terminou. O argumento outcome é um membro de JobOutcome — COMPLETED, CANCELLED ou FAILED — e message contém detalhes do erro quando o resultado é FAILED. Para trabalhos concluídos, o progress_fraction do instantâneo é 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}")

O instantâneo mais recente também pode ser consultado entre os eventos: enquanto um trabalho roda, machine.current_job retorna o JobStatus dele, ou None quando nenhum trabalho está em execução.

Aqui está um addon completo que executa um comando de shell a cada mudança de estado do trabalho:

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()])

Hooks de Registro​

Estes hooks permitem que você registre componentes personalizados nos vários registros do Rayforge.

register_machines(machine_manager)​

Use isto para registrar novos drivers de máquinas. O machine_manager é uma instância de MachineManager que gerencia todas as configurações de máquinas.

@hookimpl
def register_machines(machine_manager):
from .my_driver import MyCustomMachine
machine_manager.register("my_custom_machine", MyCustomMachine)

register_steps(step_registry)​

Registre tipos de passos personalizados que aparecem no painel de operações. O step_registry é uma instância de StepRegistry.

@hookimpl
def register_steps(step_registry):
from .my_step import MyCustomStep
step_registry.register(MyCustomStep)

register_producers(producer_registry)​

Registre produtores de ops personalizados que geram trajetórias. O producer_registry é uma instância de ProducerRegistry.

@hookimpl
def register_producers(producer_registry):
from .my_producer import MyProducer
producer_registry.register(MyProducer)

register_transformers(transformer_registry)​

Registre transformadores de ops personalizados para operações de pós-processamento. Transformadores modificam operações depois que os produtores as geram. O transformer_registry é uma instância de TransformerRegistry.

@hookimpl
def register_transformers(transformer_registry):
from .my_transformer import MyTransformer
transformer_registry.register(MyTransformer)

register_commands(command_registry)​

Registre comandos de editor que estendem a funcionalidade do editor de documentos. O command_registry é uma instância de CommandRegistry.

@hookimpl
def register_commands(command_registry):
from .commands import MyCustomCommand
command_registry.register("my_command", MyCustomCommand)

register_actions(action_registry)​

Registre ações de janela com posicionamento opcional em menu e barra de ferramentas. Ações são como você adiciona botões, itens de menu e atalhos de teclado. O action_registry é uma instância de 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)​

Registre estratégias de layout personalizadas para organizar conteúdo no documento. O layout_registry é uma instância de LayoutStrategyRegistry. Note que metadados de interface como rótulos e atalhos devem ser registrados via register_actions, não aqui.

@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)​

Registre tipos de assets personalizados que podem ser armazenados em documentos. Isso habilita desserialização dinâmica de assets fornecidos por addons. O asset_type_registry é uma instância de 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)​

Registre renderizadores personalizados para exibir seus tipos de assets na interface. O renderer_registry é uma instância de RendererRegistry.

@hookimpl
def register_renderers(renderer_registry):
from .my_renderer import MyAssetRenderer
renderer_registry.register(MyAssetRenderer())

register_exporters(exporter_registry)​

Registre exportadores de arquivos para formatos de exportação personalizados. O exporter_registry é uma instância de ExporterRegistry.

@hookimpl
def register_exporters(exporter_registry):
from .my_exporter import MyCustomExporter
exporter_registry.register(MyCustomExporter)

register_importers(importer_registry)​

Registre importadores de arquivos para formatos de importação personalizados. O importer_registry é uma instância de ImporterRegistry.

@hookimpl
def register_importers(importer_registry):
from .my_importer import MyCustomImporter
importer_registry.register(MyCustomImporter)

register_material_libraries(library_manager)​

Registre bibliotecas de materiais adicionais. Chame library_manager.add_library_from_path(path) para registrar diretórios contendo arquivos YAML de materiais. Por padrão, bibliotecas registradas são somente leitura.

@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)

Hooks de Extensão de Interface​

Estes hooks permitem que você estenda componentes de interface existentes.

step_settings_loaded(dialog, step, producer)​

O Rayforge chama isto quando um diálogo de configurações de passo está sendo populado. Você pode adicionar widgets personalizados ao diálogo baseado no tipo de produtor do passo.

O dialog é uma instância de GeneralStepSettingsView. O step é o Step sendo configurado. O producer é a instância de OpsProducer, ou None se não estiver disponível.

@hookimpl
def step_settings_loaded(dialog, step, producer):
# Só adiciona widgets para tipos específicos de produtor
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)​

Chamado quando as configurações de pós-processamento estão sendo populadas. Adicione widgets personalizados para seus transformadores aqui.

O dialog é uma instância de PostProcessingSettingsView. O step é o Step sendo configurado. O transformer é a instância de 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))

Histórico de Versões da API​

Os hooks são versionados para manter compatibilidade retroativa. Quando novos hooks são adicionados ou existentes mudam, a versão da API é incrementada. O campo api_version do seu addon deve ser pelo menos a versão mínima suportada.

A versão atual da API é 24. Aqui está o que mudou nas versões recentes:

A versão 24 adicionou os hooks de monitoramento de trabalho on_job_started, on_job_updated, on_job_paused, on_job_resumed e on_job_finished, além da API de consulta Machine.current_job.

Versão 9 adicionou main_window_ready, register_exporters, register_importers e register_renderers.

Versão 8 adicionou register_asset_types para tipos de assets personalizados.

Versão 7 adicionou register_material_libraries.

Versão 6 adicionou register_transformers.

Versão 5 substituiu register_step_widgets por step_settings_loaded e transformer_settings_loaded.

Versão 4 removeu register_menu_items e consolidou o registro de ações em register_actions.

Versão 2 adicionou register_layout_strategies.

Versão 1 foi o lançamento inicial com hooks principais para ciclo de vida de addons, registro de recursos e integração de interface.