跳转到主要内容

插件钩子

钩子是您的插件与 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())

作业监控钩子​

这些钩子报告机器上运行的作业的生命周期和进度,让插件能够在作业开始、推进、暂停、恢复或结束时作出反应——例如执行外部命令或更新智能家居系统。

所有钩子都会收到一个 JobStatus 快照(rayforge.machine.job_status.JobStatus),这是一个不可变对象,包含以下字段:

  • machine_id 和 machine_name:标识正在运行作业的机器
  • kind:JobKind.SEND 表示烧刻作业,JobKind.FRAME 表示轮廓描迹
  • phase:JobPhase.RUNNING 或 JobPhase.PAUSED
  • started_at:作业开始时的墙上时钟时间(自纪元起的秒数)
  • elapsed_seconds:作业开始以来经过的秒数
  • total_distance 和 traveled_distance:路径的总长度和已完成的长度(毫米)
  • progress_fraction:作业已完成的占比,介于 0.0 到 1.0
  • eta_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)​

在正在运行的作业进入或离开进给保持(暂停)时调用。

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

在作业结束时调用,无论其如何结束。outcome 参数是 JobOutcome 成员——COMPLETED、CANCELLED 或 FAILED——当结果为 FAILED 时,message 包含错误详情。对于已完成的作业,快照的 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。

下面是一个完整的插件,它在每次作业状态变化时运行一条 shell 命令:

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

注册生成刀具路径的自定义 ops 生成器。producer_registry 是 ProducerRegistry 实例。

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

register_transformers(transformer_registry)​

注册用于后处理操作的自定义 ops 转换器。转换器在生成器生成操作后修改操作。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,以及 Machine.current_job 轮询 API。

版本 9 添加了 main_window_ready、register_exporters、register_importers 和 register_renderers。

版本 8 添加了 register_asset_types 用于自定义资源类型。

版本 7 添加了 register_material_libraries。

版本 6 添加了 register_transformers。

版本 5 用 step_settings_loaded 和 transformer_settings_loaded 替换了 register_step_widgets。

版本 4 移除了 register_menu_items 并将操作注册整合到 register_actions 中。

版本 2 添加了 register_layout_strategies。

版本 1 是初始版本,包含插件生命周期、资源注册和 UI 集成的核心钩子。