Intercepting Entity Drag, Copy & Explode Operations via TransformOverrule & GripOverrule (dev-cookbook-22)

1. Governing Entity Behavior Without Custom C++ Subclasses

While `DrawableOverrule` controls how an entity *looks*, TransformOverrule, GripOverrule, and ObjectOverrule inside GstarCAD 2027's `.NET` API (`Gssoft.GstarCAD.DatabaseServices`) govern how standard entities *behave* when a user runs `MOVE`, `ROTATE`, `SCALE`, `MIRROR`, `EXPLODE`, or drags a grip point. This architectural pattern enables CAD teams to build intelligent, rule-driven equipment blocks and schematic components in pure C#.

For example, in a cleanroom pharmaceutical piping layout or an electrical switchgear panel, certain equipment blocks must never be scaled non-uniformly, must remain snapped to modular 100 mm DIN rail increments during `MOVE`, and must never be shattered into raw lines via `EXPLODE`.

2. C# .NET Implementation: Modular Grid Snapping & Explode Protection

The following C# `TransformOverrule` implementation intercepts all transformation matrices (`TransformBy`) and `Explode` calls on `BlockReference` entities tagged with the `"GSTAR_LOCKED_EQUIP"` XData application name. It quantizes translations to a 50 mm modular grid, strips unauthorized scaling factors, and blocks `EXPLODE`:

using System;
using Gssoft.GstarCAD.Runtime;
using Gssoft.GstarCAD.ApplicationServices;
using Gssoft.GstarCAD.DatabaseServices;
using Gssoft.GstarCAD.Geometry;

namespace GstarCadSamples.BehavioralOverrules
{
    public class ModularEquipmentTransformOverrule : TransformOverrule
    {
        public static readonly ModularEquipmentTransformOverrule Instance =
            new ModularEquipmentTransformOverrule();

        public override void TransformBy(Entity entity, Matrix3d transform)
        {
            if (entity is BlockReference blkRef)
            {
                // Extract translation component and quantize to 50.0 mm modular grid
                Vector3d rawTrans = transform.Translation;
                double snapStep = 50.0;
                Vector3d snappedTrans = new Vector3d(
                    Math.Round(rawTrans.X / snapStep) * snapStep,
                    Math.Round(rawTrans.Y / snapStep) * snapStep,
                    0.0 // Lock Z-elevation strictly to 0.0
                );

                // Reconstruct rigid transformation (preserve rotation, strip scale, apply grid snap)
                Matrix3d sanitized = Matrix3d.Displacement(snappedTrans);
                base.TransformBy(entity, sanitized);
                return;
            }
            base.TransformBy(entity, transform);
        }

        public override void Explode(Entity entity, DBObjectCollection entitySet)
        {
            // Prevent destructive EXPLODE on governed BIM/MEP equipment blocks
            var doc = Application.DocumentManager.MdiActiveDocument;
            doc?.Editor.WriteMessage(
                "
[BIM Governance] EXPLODE is blocked on catalog equipment blocks. Use BEDIT by CAD Admin.");
            throw new Gssoft.GstarCAD.Runtime.Exception(ErrorStatus.NotApplicable);
        }
    }
}

3. Combining `GripOverrule` with Custom `GripData` Callbacks in C#

When pairing `TransformOverrule` with `GripOverrule`, override `GetGripPoints(Entity, GripDataCollection, double, int, Vector3d, GetGripPointsFlags)` and `MoveGripPointsAt(Entity, GripDataCollection, Vector3d, MoveGripPointsFlags)`. Key implementation rules in GstarCAD 2027:

• Clone Semantics (`DeepClone` / `WblockClone`): If your overrule stores associative handle references inside an `ExtensionDictionary`, pair it with an `ObjectOverrule` overriding `DeepClone()` so copied entities generate fresh dictionary records rather than pointing back to the source entity's handle.
• Throwing `ErrorStatus.NotApplicable` in `Explode()`: Throwing `new Gssoft.GstarCAD.Runtime.Exception(ErrorStatus.NotApplicable)` inside `TransformOverrule.Explode()` cleanly aborts the native `EXPLODE` command for that entity while leaving the original `BlockReference` untouched in Model Space.

4. Preserving Associative Dimension & Leader Connectivity During Overruled Moves

When overriding `TransformOverrule.TransformBy()`, always invoke `base.TransformBy(entity, sanitizedMatrix)` as the final step rather than manually mutating `blkRef.Position`. Calling `base.TransformBy()` ensures that GstarCAD 2027's associative reactors (`AcDbAssocNetwork`, associative leaders, and parametric constraints) receive the standard `modified()` notification and update connected dimensions automatically.

To allow administrators to temporarily bypass your `Explode()` lock during template maintenance, gate the check behind a custom environment toggle or `.NET` static flag (e.g., `if (!AdminMaintenanceMode.IsUnlocked) throw new Exception(ErrorStatus.NotApplicable);`).

Validate This Workflow in GstarCAD 2027

Engineered by Suzhou Gstarsoft Co., Ltd. (SSE: 688657), GstarCAD 2027 delivers 100% native AC1032 DWG binary fidelity, perpetual licensing sovereignty, and zero-day AutoCAD command parity.