插件钩子
钩子是您的插件与 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.PAUSEDstarted_at:作业开始时的墙上时钟时间(自纪元起的秒数)elapsed_seconds:作业开始以来经过的秒数total_distance和traveled_distance:路径的总长度和已完成的长度(毫米)progress_fraction:作业已完成的占比,介于0.0到1.0eta_seconds:预计剩余秒数,未知时为Noneestimated_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 集成的核心钩子。