This commit is contained in:
2026-09-09 18:06:21 +08:00
parent 161af68fe3
commit 45b9f9ed5d
79 changed files with 1167 additions and 1532 deletions
@@ -88,21 +88,17 @@
<h1 id="geometry-management-panel">Geometry Management Panel</h1>
<p>The geometry switchboard is one control: a kind picker over the kinds its host allows, and — unless
the host asked for the picker alone — the picked kind's editor beneath it. On the web it binds a
the host asked for the picker alone — the picked kind's editor beneath it. It binds a
<strong>key into the shared object store</strong>, not an object, and every Control-Tree Geometry slot is this
same control in selector-only mode.</p>
<h2 id="layout">Layout</h2>
<p>Web: a geometry-type dropdown; a separator, drawn only while a kind is active; then that kind's
editor. Picking a kind commits immediately — there is no Apply button. In selector-only mode
everything below the dropdown is dropped, which is the form each Geometry slot node shows.</p>
<p>Desktop: a combo box on the left of a head line with a <strong>Convert</strong> menu on its right, over a bordered
content presenter that hosts the kind's own control.</p>
<h2 id="what-it-binds">What It Binds</h2>
<p>The web panel has no target-geometry property. It takes a <code>modelKey</code> naming the object it edits and
mutates what sits behind that key; a host that also owns the <em>field</em> holding the geometry passes an
<code>onCreate</code> hook, so switching the kind rebinds the host's field rather than just the key. The
desktop panel is the one that exchanges an <a class="xref" href="../../api/Hi.Geom.IStlSource.html">IStlSource</a> directly, through a getter and
setter pair its host supplies.</p>
<code>onCreate</code> hook, so switching the kind rebinds the host's field rather than just the key.</p>
<p>Each host's field type decides which kinds it <em>may</em> offer; whether the kind survives a save decides
which of those it <em>does</em>. A fixture's geometry and a transformation geometry's inner geometry are
<a class="xref" href="../../api/Hi.Geom.IGetStl.html">IGetStl</a>; a workpiece's initial geometry is an <code>IMakeXmlSource</code>, which is why the
@@ -117,7 +113,7 @@ host that wires that source, the cutter's upper beam.</p>
<a class="xref" href="../../api/Hi.Geom.Cylindroid.html">Cylindroid</a>, <a class="xref" href="../../api/Hi.Geom.StlFile.html">StlFile</a>, <a class="xref" href="../../api/Hi.Geom.TransformationGeom.html">TransformationGeom</a>,
<a class="xref" href="../../api/Hi.Geom.GeomCombination.html">GeomCombination</a> and <a class="xref" href="../../api/Hi.Cbtr.CubeTreeFile.html">CubeTreeFile</a>. <a class="xref" href="../../api/Hi.Geom.ExtendedCylinder.html">ExtendedCylinder</a> is
in the kind map but out of that default: a host that can wire its start section names it explicitly.
Nothing is hidden by a flag on the web.</p>
Nothing is hidden by a flag.</p>
<p><strong>The default is a guard rail, not a shipped list.</strong> Every host passes its own whitelist — the five
Control-Tree Geometry slots from the node context, the four inline hosts as a constant — so no
shipped surface renders the default at all, and the whitelist is what really decides reach.</p>
@@ -151,17 +147,13 @@ shipped surface renders the default at all, and the whitelist is what really dec
only when the host asks for it: the three General Setup slots and a transformation geometry's inner
geometry do, while the mechanism anchor, the cutter upper beam and combination children do not, so
those pickers cannot clear the slot. Clearing goes through the host's create hook with the literal
kind <code>None</code>, which the container-aware endpoints map to null. The desktop combo always lists a
<strong>None</strong> item.</p>
<h2 id="converting-is-desktop-only">Converting Is Desktop-Only</h2>
<p>Wrapping an existing geometry into a <a class="xref" href="../../api/Hi.Geom.TransformationGeom.html">TransformationGeom</a> — and extracting it back out
— exists only in the desktop client, as items in the <strong>Convert</strong> menu rather than as buttons. The
<em>Convert to Transformation</em> item re-titles itself <em>Extract from Transformation</em> when the current
geometry already is one; the combination item behaves the same way, and its extract is offered only
when the combination holds exactly one child. Three code-behind properties can hide the menu and each
of its two items, but no shipped host sets any of them.</p>
<p><strong>The web has no equivalent, and the difference is not cosmetic.</strong> Picking <code>TransformationGeom</code> in
the picker creates a new, empty one and discards the geometry that was there — it does not wrap it.</p>
kind <code>None</code>, which the container-aware endpoints map to null.</p>
<h2 id="there-is-no-way-to-wrap-an-existing-geometry">There Is No Way to Wrap an Existing Geometry</h2>
<p>Wrapping a geometry that is already in a slot into a <a class="xref" href="../../api/Hi.Geom.TransformationGeom.html">TransformationGeom</a> — and
extracting it back out — is not offered anywhere in the application, and the difference from what
the picker looks like it does is not cosmetic. <strong>Picking <code>TransformationGeom</code> creates a new, empty
one and discards the geometry that was there.</strong> The same holds for a combination: there is no
operation that takes a geometry and puts a container around it in place.</p>
<h2 id="in-the-control-tree">In the Control Tree</h2>
<p><code>Geometry</code> is a slot item type. Its child builder probes the slot's key for the type behind it and,
when that type is a known kind, grows exactly <strong>one</strong> child node of that kind bound to the same key
@@ -219,8 +211,8 @@ editor</li>
<li><a href="extended-cylinder-panel.html">Extended Cylinder Panel</a> — the same, and the kind exactly one host offers</li>
<li><a href="stlfile-control.html">STL File Control</a> — the same, for an STL reference</li>
<li><a href="meshed-geom-panel.html">Meshed Geometry Panel</a> — the same, for a voxel cube tree</li>
<li><a href="transformation-geom-control.html">Transformation Geometry Control</a> — the container kind this panel
can wrap into on the desktop client</li>
<li><a href="transformation-geom-control.html">Transformation Geometry Control</a> — one of the container kinds
this panel offers, and why picking it replaces rather than wraps</li>
<li><a href="geom-combination-control.html">Geometry Combination Control</a> — the other container kind, whose
every child embeds this panel again</li>
</ul>