linkcad.controller

高层转换流程控制器。当你需要完整的转换向导状态机（选择格式、设置选项、读取、应用工具、写入），而不是直接驱动 linkcad.conv 时，请使用它。

from linkcad.v1.controller import (
    ConversionController, ConversionState,
    ControllerEvent, IControllerListener, ProgressInfo,
)

类

ConversionController

统筹 LinkCAD 转换向导使用的多步骤转换流程。

from linkcad.v1.controller import ConversionController

ctrl = ConversionController()
ConversionController.import_format = "GDSII"
ConversionController.export_format = "DXF"
ctrl.selected_input_files = ["/data/design.gds"]
ConversionController.output_file = "/data/design.dxf"

ctrl.start_read()
dwg = ctrl.current_drawing
if dwg is None:
    raise RuntimeError("Import produced no drawing")

ctrl.start_write()
print(ctrl.current_state)

格式选择和输出路径在引擎中是进程级状态，因此 import_format、export_format 和 output_file 是静态属性：请在类上赋值。通过实例读取同样有效，得到的是同一个值。

属性 / 方法	说明
`ConversionController()`	创建新的控制器实例
`ConversionController.import_format` / `.export_format`	格式名称（例如 `"GDSII"`）；静态，可赋值
`ConversionController.output_file`	输出文件路径；静态，可赋值
`ctrl.selected_input_files`	输入文件路径列表；可赋值
`ctrl.set_import_options(options_json)` / `ctrl.set_export_options(options_json)`	以 JSON 字符串应用选项
`ctrl.tools_enabled`	是否在读取与写入之间运行工具；可赋值
`ctrl.configure_tools(tools_config)`	用 JSON 配置工具阶段
`ctrl.batch_mode`	批量转换模式；可赋值
`ctrl.start_read()`	开始读取输入文件
`ctrl.start_write()`	开始写入输出文件
`ctrl.start_batch()`	开始批量转换
`ctrl.finish_operation(success)`	将当前操作标记为完成
`ctrl.cancel_current_operation()`	取消正在进行的操作
`ctrl.operation_in_progress`	操作运行期间为 `True`
`ctrl.next()` / `ctrl.back()` / `ctrl.reset()`	在流程状态之间移动
`ctrl.can_go_next` / `ctrl.can_go_back`	是否可以导航
`ctrl.current_state`	当前的 `ConversionState`
`ctrl.current_drawing`	已加载的 `Drawing`，或 `None`
`ctrl.current_progress`	当前的 `ProgressInfo`
`ctrl.import_log`	导入日志，类型为 `IEventLogReader`
`ctrl.export_log`	导出日志，类型为 `IEventLog`
`ctrl.conversions`	底层的 `Conversions` 集合——参见 linkcad.conv
`ctrl.add_listener(listener)` / `ctrl.remove_listener(listener)`	添加或移除 `IControllerListener`

set_import_options() 和 set_export_options() 仍是方法：控制器把 JSON 直接交给插件，自己不保留任何可回读的内容，而没有读取器的属性不是属性。

ConversionState

标识转换向导每个页面的枚举。

值	说明
`ConversionState.Begin`	初始状态
`ConversionState.SelectFormat`	选择导入和导出格式
`ConversionState.ImportOptions`	导入选项页面
`ConversionState.ExportOptionsPre`	读取前显示的导出选项
`ConversionState.ReadFile`	读取输入文件
`ConversionState.ApplyTools`	应用几何工具
`ConversionState.ReadLog`	查看导入日志
`ConversionState.OpenPolys`	处理开放折线
`ConversionState.BatchTools`	批处理运行的工具配置
`ConversionState.Structure`	单元/图层结构页面
`ConversionState.ExportOptionsPost`	读取后显示的导出选项
`ConversionState.SelectBatchFiles`	选择批处理文件
`ConversionState.ConvertBatchFiles`	批量转换进行中
`ConversionState.WriteFile`	写入输出文件
`ConversionState.WriteLog`	查看导出日志
`ConversionState.Summary`	摘要页面
`ConversionState.End`	流程完成

ControllerEvent

控制器发出的通知枚举。

值	说明
`ControllerEvent.StateChanged`	流程切换到了另一个状态
`ControllerEvent.PageActivated`	某个向导页面被激活
`ControllerEvent.ProgressUpdated`	进度信息发生变化
`ControllerEvent.LogUpdated`	日志新增了条目
`ControllerEvent.DrawingChanged`	当前图纸被替换
`ControllerEvent.OperationFinished`	某个操作已完成
`ControllerEvent.OperationCancelled`	某个操作被取消
`ControllerEvent.ErrorOccurred`	报告了一个错误

ProgressInfo

由 ctrl.current_progress 返回的进度快照。

属性	说明
`percentage`	进度百分比（0-100）
`current_operation`	当前步骤的描述
`current_file`	正在处理的文件
`current_file_index`	当前文件的索引
`total_files`	作业中的文件数

IControllerListener

继承它以接收控制器通知。每个方法都必须重写。

from linkcad.v1.controller import ConversionController, IControllerListener

class Watcher(IControllerListener):
    def on_state_changed(self, new_state): print(f"state: {new_state}")
    def on_page_activated(self, page): pass
    def on_progress_updated(self, progress): print(f"{progress.percentage}%")
    def on_log_updated(self): pass
    def on_drawing_about_to_be_cleared(self, drawing): pass
    def on_drawing_changed(self, drawing): pass
    def on_operation_finished(self, success): print(f"finished: {success}")
    def on_operation_cancelled(self): pass
    def on_error_occurred(self, message): print(f"error: {message}")

ctrl = ConversionController()
watcher = Watcher()
ctrl.add_listener(watcher)

方法	调用时机
`on_state_changed(new_state)`	流程状态发生变化时
`on_page_activated(page)`	向导页面被激活时
`on_progress_updated(progress)`	进度更新时
`on_log_updated()`	日志更新时
`on_drawing_about_to_be_cleared(drawing)`	当前图纸即将被丢弃之前
`on_drawing_changed(drawing)`	图纸发生变化时
`on_operation_finished(success)`	操作完成时
`on_operation_cancelled()`	操作被取消时
`on_error_occurred(message)`	发生错误时