1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
"""The FerroCAD-only Python API (the extensions upstream FreeCAD does not have).
A mod that imports ``FerroCAD`` declares a FerroCAD dependency; a mod that only
imports ``FreeCAD``/``FreeCADGui`` is written against the upstream surface and
should run there unchanged. The boundary is deliberate and has no aliases: the
names here are **not** available on ``FreeCAD``. See
``docs/architecture/api-namespaces.md``.
This module holds the app-side extension points:
* :data:`Grid` — the semantic grid-settings singleton;
* :data:`Axis` — the semantic axis-cross settings singleton;
* :data:`Gizmo` — the semantic manipulator-gizmo settings singleton;
* :func:`register_display_provider` / :func:`display_mesh` — how a module draws
its objects;
* :func:`register_interaction_provider` / :func:`interaction` — how a module
applies a manipulator's commit;
* :func:`register_manipulator_provider` / :func:`manipulator_specs` — how a module
declares the handles a selection arms;
* :func:`set_parameter_file` / :func:`parameter_file` — which file backs
``FreeCAD.ParamGet`` (see ``docs/tasks/settings-model.md`` S3);
* the **document lifecycle aliases** — ``newDocument``, ``openDocument`` /
``open``, ``closeDocument`` and ``setActiveDocument`` delegate to ``FreeCAD``,
which fires the ``FerroCADGui`` document-observer slot (deactivation happens
before the document disappears). They are not exported in ``__all__``: their
names are upstream-shaped, and the slot they reach is the FerroCAD extension.
The document registry, the base value types and the parameters stay on
``FreeCAD``: those are upstream-shaped.
"""
# ---------------------------------------------------------------------------
# The semantic capabilities (see FerroCAD._grid, _axis and _gizmo)
# ---------------------------------------------------------------------------
# PEP 562: bound lazily so importing FerroCAD stays headless and GUI-free, and
# so a build without a capability is detected through
# ``getattr(..., "Grid", None)`` / ``getattr(..., "Axis", None)`` /
# ``getattr(..., "Gizmo", None)``.
return
return
return
# ---------------------------------------------------------------------------
# Module hooks: display and interaction providers
# ---------------------------------------------------------------------------
# A workbench registers how **its** objects are drawn and how a manipulator's
# commit is applied, so the shell never names a module (the shell must serve any
# edition). Upstream puts this on `FreeCADGui` (one `ViewProvider` per object,
# plus commands); until the M5 GUI module exists these two hooks are the minimal
# equivalent. A provider returns `None` for a request it does not own, and the
# next provider is asked.
=
=
=
"""Let ``provider(obj)`` supply the display mesh of a document object.
The provider returns the tessellation dict of `ferrocad.geom.Tessellation`
(``positions``, ``triangles``, ``edges``, ``parts``, …) or ``None``. Modules
register once, when they are imported; registration is idempotent.
"""
"""The display mesh for `obj`, from the first module that claims it."""
=
return
return None
"""Let ``provider(obj, manipulator, action, element, values)`` apply an edit.
``manipulator`` is the registry id of the manipulator that committed
(``"dress_up"``), ``action`` the operation within it (``"fillet"``,
``"chamfer"``), ``element`` the sub-element name (or ``""``), and ``values``
the numbers in the manipulator's documented order. The provider returns a dict
``{"ok": bool, ...}`` (or ``None`` when it does not own the manipulator). The
edit itself — creating the feature, wrapping it in a transaction, recomputing —
belongs to the module, not to the shell.
"""
"""Apply a manipulator commit through the first module that supports it."""
=
=
return
return None
"""Let ``provider(obj, element)`` declare handles for a selection.
The callback is called **when a selection is armed**, so it must be cheap:
return a list of declarative handle dicts (the same shape the viewport's
transport validates in ``crates/ferrocad_gpui/src/manipulators.rs``), or
``None``/``[]`` when the module has no handle for this object. The provider
must not mutate the document or raise; a raised exception is reported and
the other providers still run. Registration is idempotent.
The commit half is :func:`register_interaction_provider`: when the user
drags the handle, its ``action``, ``element`` and value arrive there as
``manipulator``, ``action``, ``element`` and ``values``.
"""
"""The declarative handles every module declares for ``obj``, in order.
Each provider is called as ``provider(obj, element)``. A provider that
returns ``None`` or ``[]`` contributes nothing. A provider that raises is
reported once to stderr and skipped, so one broken mod cannot break the
shell's selection path; the remaining providers still run.
"""
=
=
# noqa: BLE001 - a mod must not break selection
=
continue
continue
=
continue
return
# ---------------------------------------------------------------------------
# Document lifecycle
#
# ``FreeCAD.newDocument`` / ``openDocument`` / ``closeDocument`` /
# ``setActiveDocument`` are the upstream-shaped calls and own the lifecycle: the
# App facade fires the ``FerroCADGui`` document-observer slot (without importing
# the GUI layer in a headless session). These names stay as the app-side aliases
# scripts and the shell already use; only ``closeDocument`` differs, returning
# whether the document was open where ``FreeCAD`` raises. They are not in
# ``__all__`` because the names are upstream-shaped and ``FerroCADGui`` owns the
# extension; see ``docs/architecture/api-namespaces.md``.
# ---------------------------------------------------------------------------
"""Alias for :func:`FreeCAD.newDocument` (the lifecycle lives there)."""
return
"""Alias for :func:`FreeCAD.openDocument`."""
return
"""Upstream's ``FreeCAD.open`` alias, with the same lifecycle."""
return
"""Close a document; ``False`` when it was not open (``FreeCAD`` raises)."""
return False
return True
"""Alias for :func:`FreeCAD.setActiveDocument`."""
=