建模语言核心（Modeling Language Core）

核心建模语言（Core Modeling Language）是所有其他建模语言的基础。

Base 类作为所有 Gaphor 领域类的根类。Diagram 和 Presentation 则构成了图表中所有可见内容的基础。

Gaphor中的所有数据模型均从其实际的模型文件生成，这一机制使我们能够为您提供Gaphor内部模型的清晰图表展示。

核心模型（含呈现类）

Base 基类

Base 类提供事件通知功能并与模型仓库（内部称为 ElementFactory）集成。模型中所有类都应继承自该基类。若模型中未显式指定元素的基类，则默认继承自 Base。此外，该模型还支持双向关系及派生关系。

RepositoryProtocol 和 EventWatcherProtocol 协议对于将模型连接到仓库及事件处理机制至关重要。

Base 类是 Gaphor 数据模型的核心。

class gaphor.core.modeling.Base(id: str | None = None, model: RepositoryProtocol | None = None)

所有模型数据类的基类。

property id: str

id（只读属性），在模型中具有唯一性。

property model: RepositoryProtocol

所属模型（未设置时会抛出 TypeError 异常）。

unlink() → None

解链元素。

所有元素引用均被销毁。对于组合关联（composite associations），其关联元素也将被解链。

执行解链操作时将获取解链锁，以避免对此元素属性解链时出现递归问题。

事件处理（Event Handling）

handle(event: object) → None

传播传入事件（Propagate Incoming Events）。

只有当元素是由 ElementFactory 创建时，这才有效

watcher(default_handler: Callable[[ElementUpdated], None] | None = None) → EventWatcherProtocol

为该元素创建一个新的观察者。

当与 self 相关的属性发生更改时，监视器（Watchers）提供了一种便捷的方式来接收通知。

要使用监视器（Watcher），该元素必须由正确配置的 ElementFactory` 创建。

此示例仅作说明用途：

>>> element = Base()
>>> watcher = element.watcher(default_handler=print)
>>> watcher.watch("note")  # Watch for changed on element.note

加载与保存

load(name: str, value: str | bool | int | Base | collection[Base]) → None

加载名为（name）的值。

请确保所有元素加载完成后调用 postload() 方法。

postload() → None

修复遗留问题。

此操作将在所有元素加载完成后执行。

save(save_func: Callable[[str, str | bool | int | Base | collection[Base]], None]) → None

通过调用 save_func(name, value) 保存状态。

OCL 风格方法

isKindOf(class_: type[Base]) → bool

如果该对象是 class_ 的实例，则返回 True。

isTypeOf(other: Base) → bool

当该对象与 other 类型相同时返回 True。

Presentation 呈现类

class gaphor.core.modeling.Presentation(diagram: Diagram, id: Id | None = None)

一种特殊的 Base 派生类型，可在 Diagram 上显示。

Presentation 实例仅可由图表（Diagram）持有。

Presentation 的子类型应实现 gaphas.item.Item 协议。

request_update() → None

将此呈现对象标记为待更新。

更新操作由图表统一协调。

watch(path: str, handler: Callable[[ElementUpdated], None] | None = None) → Self

监控以 self 为起点的特定元素路径。

该处理器（Handler）为可选配置，默认使用简单的 request_update 方法。

监视器（Watchers）应在构造函数中设置，以便一次性完成注册和注销操作。

self.watch("subject.name")

该接口采用流式设计：返回 self 以实现链式调用。

change_parent(new_parent: Presentation | None) → None

更改父级对象并更新该项目的矩阵变换，使其在视觉上保持原位。

Diagram 类

class gaphor.core.modeling.Diagram(id: str | None = None, model: RepositoryProtocol | None = None)

图表（Diagram）可以包含 Presentation 呈现元素。

若需为图表（Diagram）设置所有权关系，建模语言（如UML）应继承`` Diagram`` 类，并添加所有权关联规则。

create(type_: type[P], parent: Presentation | None = None, subject: Base | None = None) → P

在图表上创建新的图表项。

该元素创建时将分配唯一ID，并挂载至图表根项（root item）。参数type指定要创建的元素类，新元素还可选包含父级关联（parent）和主题对象（subject）。

lookup(id: str) → Presentation | None

按ID查找呈现项。

返回此图表中的呈现项，若未找到则返回 None。

select(expression: Callable[[Presentation], bool]) → Iterator[Presentation]

select(expression: type[P]) → Iterator[P]

select(expression: None) → Iterator[Presentation]

返回匹配表达式的所有画布项（canvas items）的迭代器。

request_update(item: Item) → None

将项目标记为待更新状态。

此处不会立即执行更新，仅将项目添加至待更新集合中。

This method is part of the gaphas.model.Model protocol.

update(dirty_items: Collection[Presentation] = ()) → None

Update the diagram.

All items that requested an update via request_update() are now updates. If an item has an update(context: UpdateContext) method, it's invoked. Constraints are solved.

Protocols

class gaphor.core.modeling.base.RepositoryProtocol(*args, **kwargs)

create(type: type[T]) → T

Create a new element in the repository.

select(self, expression: Callable[[Base], bool]) → Iterator[Base]

Select elements from the repository that fulfill expression.

select(self, type_: type[T]) → Iterator[T]

Select all elements from the repository of type type_.

select(self, expression: None) → Iterator[Base]

Select all elements from the repository.

lookup(id: str) → Base | None

Get an element by id from the repository.

Returns None if no such element exists.

class gaphor.core.modeling.base.EventWatcherProtocol(*args, **kwargs)

watch(path: str, handler: Callable[[ElementUpdated], None] | None = None) → EventWatcherProtocol

Add a watch for a specific path. The path is relative to the element that created the watcher object.

Returns self, so watch operations can be chained.

unsubscribe_all() → None

Should be called before the watcher is disposed, to release all watched paths.