Using ObjectOverrule To Force Entities' Change

Very often in drafting process, we want certain entities would only change in particular manners, for example, we'd line a line always has its end point connected to a circle or a circle's radius can only be one of give values no matter what the drafter does to the line or circle (stretching, moving...).

There are a few different ways to achieve this goal:

1. We can write our own custom command to guide user the required change. For example, if we need to keep two or more entities somehow linked/connected when user stretch/move one of the connected entity, instead of using AutoCAD built-in command STRETCH and/or MOVE, we let user to use a custom command specifically designed for this particular situation. One of my old articles shows how to do this.

2. Sometimes one may not want to force user to use custom command, while still likes some kind of auto-enforcement could happen. For example, after user stretched/moved one entity, it should still connect to a circle. There are 2 ways to do this:

• Handle Document.CommandWillStart/CommandEnded and Database.ObjectModified events. That is, when command starts, create a empty ObjectId container (ObjectIdCollection, List, ObjectId[]...); then in ObjectModified event, test if the modified entity is the target entity; if yes, save its ObjectId into the ObjectId container; finally when command ended, go through the ObjectId container to modify the entities again, if necessary, to enforce required geometries (or other properties). This article from my old posts shows how to do it.
• Use ObjectOverrule to enforce required conditions before the entity's modification is finalized by overriding ObjectOverrule.Close() method. This post will focus on this approach.

3. Use AutoCAD's built-in Constraints/Parametric mechanism. I am not going discuss this topic here.

In this post, I focus on using ObjectOverrule. Different from the handing CommandWillStart, CommandEnded and ObjectModified events, which modifies the targeting entities again after targeting entities being modified and tracked in Database.ObjectModified event handler, using ObjectOverrule with overridden Close() method make it possible to do additional modification to entities being changed with out opening the entities again. Of course we are not limited to do additional modification to currently opened entities in the overridden Close() method, we can also do something to other entities. Here I present 2 custom ObjectOverrule classes as examples.

Here are the 2 scenarios:

1. I want to be able to modify entities of Line (stretching to change its length) so that the length always change by given incremental length, say, it can only extend/shrink by 2 units. In this case, the custom Overrule does the additional work after user stretches a line to make sure the line's length extend or shrink in given increment. That is, the modified entity is modified again before the modification caused by user is closed.

2. I want to have a line with a circle connected to its end point. When user moves the line or the circle, the 2 always remain connected (i.e. the circle stays at the end point of the line). In this case, I let the custom Overrule to actually start modify the other entity that is linked to the currently modified entity, in order to make them remain linked.

Since I am going to apply Overrule to only selected entities, I decided to use XData to flag entities as the targets of the Overrule (i.e. let the Overrule to use XData filter to identify targeting entities).

Class MyLineObjectOverrule is used for the first scenario:

using System;
using Autodesk.AutoCAD.DatabaseServices;
using Autodesk.AutoCAD.Runtime;
 
namespace EntityModifiedObjectOverule
{
    public class MyLineObjectOverrule : ObjectOverrule
    {
        private static string _xDataAppName="";
        private static MyLineObjectOverrule _instance = null;
        private static Action<Line, string> _overruleAction = null;
 
        public static MyLineObjectOverrule Instance
        {
            get
            {
                if (_instance == null) 
                    _instance = new MyLineObjectOverrule();
 
                return _instance;
            }
        }
 
        public void StartOverrule(
            string xDataAppName, Action<Line, string> overruleAction)
        {
            _xDataAppName = xDataAppName;
 
            AddOverrule(RXClass.GetClass(typeof(Line)), this, false);
            this.SetXDataFilter(xDataAppName);
 
            _overruleAction = overruleAction;
 
            Overruling = true;
        }
 
        public void StopOverrule()
        {
            RemoveOverrule(RXClass.GetClass(typeof(Line)), this);
            Overruling = false;
        }
 
        public override void Close(DBObject dbObject)
        {
            if (dbObject.IsModified && 
                !dbObject.IsUndoing && 
                dbObject.IsWriteEnabled)
            {
                //Do something to the modified entity before it is closed
                Line line = dbObject as Line;
                _overruleAction(line, _xDataAppName);
            }
 
            base.Close(dbObject);
        }
    }
}

Class MyPairedEntitiesObjectOverrule is for the second scenario:

using System;
using Autodesk.AutoCAD.DatabaseServices;
using Autodesk.AutoCAD.Runtime;
 
namespace EntityModifiedObjectOverule
{
    public class MyPairedEntitiesObjectOverrule : ObjectOverrule
    {
        private static string _xDataAppName = "";
        private static MyPairedEntitiesObjectOverrule _instance = null;
        private static Action<ObjectId, DBObject> _overruleAction = null;
        private static bool _changeOtherEntity = false;
 
        public static MyPairedEntitiesObjectOverrule Instance
        {
            get
            {
                if (_instance == null)
                    _instance = new MyPairedEntitiesObjectOverrule();
 
                return _instance;
            }
        }
 
        public void StartOverrule(
            string xDataAppName, Action<ObjectId, DBObject> overruleAction)
        {
            _xDataAppName = xDataAppName;
            _overruleAction = overruleAction;
 
            StartOverrule();
        }
 
        public void StopOverrule()
        {
            RemoveOverrule(RXClass.GetClass(typeof(Line)), this);
            RemoveOverrule(RXClass.GetClass(typeof(Circle)), this);
 
            Overruling = false;
        }
 
        public bool PairLineAndCircle()
        {
            bool ruling=Overruling;
 
            if (ruling) StopOverrule();
 
            bool done = CadHelper.SetPairedLineAndCircle(_xDataAppName);
 
            if (ruling) StartOverrule();
 
            return done;
        }
 
        public override void Close(DBObject dbObject)
        {  
            if (dbObject.IsModified &&
                !dbObject.IsUndoing &&
                dbObject.IsWriteEnabled)
            {
                if (!_changeOtherEntity)
                {
                    //Find the paired entity
                    ResultBuffer buffer =
                        dbObject.GetXDataForApplication(_xDataAppName);
                    string handleString = null;
                    if (buffer != null)
                    {
                        TypedValue[] vals = buffer.AsArray();
                        if (vals.Length >= 2)
                        {
                            handleString = vals[1].Value.ToString();
                        }
                    }
 
                    if (!string.IsNullOrEmpty(handleString))
                    {
                        ObjectId entId =
                            CadHelper.GetObjectIdFromHandleString(
                            dbObject.Database, handleString);
 
                        if (!entId.IsNull)
                        {
                            _changeOtherEntity = true;
                            _overruleAction(entId, dbObject);
                            _changeOtherEntity = false;
                        }
                    }
                }
            }
            
            base.Close(dbObject);
        }
 
        private void StartOverrule()
        {
            AddOverrule(RXClass.GetClass(typeof(Line)), this, false);
            AddOverrule(RXClass.GetClass(typeof(Circle)), this, false);
 
            this.SetXDataFilter(_xDataAppName);
 
            Overruling = true;
        }
    }
}

You may notice that the StartOverrule() method of the 2 custom Overrule classes takes Action as an argument, and the Action passed in is called in the overridden Close(). That means, the custom Overrule is just provide a chance for the whatever action we want to do. We are separate the code for doing actual work out of the custom Overrule. This way, we can easily inject different action into the custom Overrule based on the business requirements.

Following is a helper class doing generic AutoCAD work CadHelper:

using System;
using Autodesk.AutoCAD.DatabaseServices;
using Autodesk.AutoCAD.ApplicationServices;
using Autodesk.AutoCAD.EditorInput;
using Autodesk.AutoCAD.Geometry;
using CadApp = Autodesk.AutoCAD.ApplicationServices.Application;
 
namespace EntityModifiedObjectOverule
{
    public class CadHelper
    {
        public static void SetSnapLengthFlagToLine(
            ObjectId lineId, string xDataAppName, double lengthIncrement)
        {
            if (lineId.ObjectClass.DxfName.ToUpper()!="LINE")
            {
                throw new TypeAccessException(
                    "Selected entity is not a LINE object!");
            }
 
            using (Transaction tran=
                lineId.Database.TransactionManager.StartTransaction())
            {
                EnsureXDataAppRegistered(xDataAppName, lineId.Database, tran);
 
                Entity ent = (Entity)tran.GetObject(lineId, OpenMode.ForWrite);
 
                TypedValue[] vals = new TypedValue[]
                {
                    new TypedValue(
                        (int)DxfCode.ExtendedDataRegAppName, 
                        xDataAppName),
                    new TypedValue(
                        (int)DxfCode.ExtendedDataReal, 
                        lengthIncrement)
                };
 
                using (ResultBuffer buffer=new ResultBuffer(vals))
                {
                    ent.XData = buffer;
                }
 
                tran.Commit();
            }
        }
 
        public static double GetlengthIncrementFromLine(
            ObjectId lineId, string xDataAppName)
        {
            double increment = 0.0;
 
            using (Transaction tran = 
                lineId.Database.TransactionManager.StartTransaction())
            {
                Entity ent = (Entity)tran.GetObject(lineId, OpenMode.ForRead);
 
                ResultBuffer buffer = ent.GetXDataForApplication(xDataAppName);
                if (buffer!=null)
                {
                    TypedValue[] vals = buffer.AsArray();
                    if (vals.Length==2)
                    {
                        increment = Convert.ToDouble(vals[1].Value);
                    }
                }
 
                tran.Commit();
            }
 
            return increment;
        }
 
        public static void ClearSnapLengthFlagFromLine(
            ObjectId lineId, string xDataAppName)
        {
            if (lineId.ObjectClass.DxfName.ToUpper() != "LINE")
            {
                throw new TypeAccessException(
                    "Selected entity is not a LINE object!");
            }
 
            using (Transaction tran = 
                lineId.Database.TransactionManager.StartTransaction())
            {
                EnsureXDataAppRegistered(xDataAppName, lineId.Database, tran);
 
                Entity ent = (Entity)tran.GetObject(lineId, OpenMode.ForWrite);
 
                TypedValue[] vals = new TypedValue[]
                {
                    new TypedValue(
                        (int)DxfCode.ExtendedDataRegAppName, 
                        xDataAppName)
                };
 
                using (ResultBuffer buffer = new ResultBuffer(vals))
                {
                    ent.XData = buffer;
                }
 
                tran.Commit();
            }
        }
 
        public static ObjectId GetObjectIdFromHandleString(
            Database db, string handleString)
        {
            ObjectId id = ObjectId.Null;
 
            Handle hdl = 
                new Handle(Int64.Parse(
                handleString, 
                System.Globalization.NumberStyles.HexNumber));
 
            id = db.GetObjectId(false, hdl, 0);
 
            return id;
        }
 
        public static bool SetPairedLineAndCircle(string xDataAppName)
        {
            Document dwg=Application.DocumentManager.MdiActiveDocument;
            bool ok = true;
 
            ObjectId lineId = PickEntity(
                dwg.Editor, typeof(Line), "Select a line:");
            if (!lineId.IsNull)
            {
                ObjectId circleId = PickEntity(
                    dwg.Editor, typeof(Circle), "Select a circle:");
                if (!circleId.IsNull)
                {
                    using (Transaction tran =
                        dwg.TransactionManager.StartTransaction())
                    {
                        EnsureXDataAppRegistered(
                            xDataAppName, dwg.Database, tran);
 
                        Entity line = (Entity)tran.GetObject(
                            lineId, OpenMode.ForWrite);
                        Entity circle = (Entity)tran.GetObject(
                            circleId, OpenMode.ForWrite);
 
                        TypedValue[] vals;
                        
                        vals = new TypedValue[] { 
                            new TypedValue(
                                (int)DxfCode.ExtendedDataRegAppName, 
                                xDataAppName),
                            new TypedValue(
                                (int)DxfCode.ExtendedDataAsciiString, 
                                line.Handle.ToString())
                        };
 
                        using (ResultBuffer buffer = new ResultBuffer(vals))
                        {
                            circle.XData = buffer;
                        }
 
                        vals = new TypedValue[] { 
                            new TypedValue(
                                (int)DxfCode.ExtendedDataRegAppName, 
                                xDataAppName),
                            new TypedValue(
                                (int)DxfCode.ExtendedDataAsciiString, 
                                circle.Handle.ToString())
                        };
 
                        using (ResultBuffer buffer = new ResultBuffer(vals))
                        {
                            line.XData = buffer;
                        }
 
                        tran.Commit();
                    }
                }
                else
                {
                    ok = false;
                }
            }
            else
            {
                ok = false;
            }
 
            return ok;
        }
 
        #region Objectoverrule actions
 
        public static void ForceLineLength(Line line, string xDataAppName)
        {
            double increment = 0.0;
            ResultBuffer buffer = line.GetXDataForApplication(xDataAppName);
            if (buffer != null)
            {
                TypedValue[] vals = buffer.AsArray();
                if (vals.Length == 2)
                {
                    increment = Convert.ToDouble(vals[1].Value);
                }
            }
 
            if (increment > Tolerance.Global.EqualVector)
            {
                Point3d pt = GetLineEndPoint(line, increment);
                if (pt.DistanceTo(line.EndPoint) > Tolerance.Global.EqualPoint)
                {
                    line.EndPoint = pt;
                    Editor ed = CadApp.DocumentManager.MdiActiveDocument.Editor;
                    ed.WriteMessage(
                        "\nThe length of modified line has been forced to {0}\n",
                        line.Length);
                }
            }
        }
 
        public static void ForceLinkedLineAndCircle(
            ObjectId entToChange, DBObject modifiedEnt)
        {
            using (Transaction tran = 
                entToChange.Database.TransactionManager.StartTransaction())
            {
                Entity ent = (Entity)tran.GetObject(
                    entToChange, OpenMode.ForWrite);
                if (ent is Line)
                {
                    Circle c= modifiedEnt as Circle;
                    if (c != null)
                    {
                        MoveLineEndPointToCircle(ent as Line, c);
                    }
                }
                else
                {
                    Line l = modifiedEnt as Line;
                    if (l!=null)
                    {
                        MoveCircleToLine(ent as Circle, l);
                    }
                }
 
                tran.Commit();
            }
        }
 
        #endregion
 
        #region private methods
 
        private static void EnsureXDataAppRegistered(
            string xDataAppName, Database db, Transaction tran)
        {
            RegAppTable tbl = tran.GetObject(
                db.RegAppTableId, OpenMode.ForRead) as RegAppTable;
            if (!tbl.Has(xDataAppName))
            {
                RegAppTableRecord app = new RegAppTableRecord();
                app.Name = xDataAppName;
 
                tbl.UpgradeOpen();
                tbl.Add(app);
            }
        }
 
        private static Point3d GetLineEndPoint(Line line, double increment)
        {
            double len = 0.0;
 
            while (len <= line.Length)
            {
                len += increment;
            }
 
            len -= increment;
 
            double lenDiff = line.Length - len;
 
            if (lenDiff >= increment / 2.0)
            {
                len = len + increment;
            }
 
            //Get new end point
            double x = line.StartPoint.X + Math.Cos(line.Angle) * len;
            double y = line.StartPoint.Y + Math.Sin(line.Angle) * len;
 
            return new Point3d(x, y, 0.0);
        }
 
        private static void MoveLineEndPointToCircle(Line line, Circle circle)
        {
            line.EndPoint = circle.Center;
        }
 
        private static void MoveCircleToLine(Circle circle, Line line)
        {
            Matrix3d mt = Matrix3d.Displacement(
                circle.Center.GetVectorTo(line.EndPoint));
            circle.TransformBy(mt);
        }
 
        private static ObjectId PickEntity(
            Editor ed, Type entType, string pickingMsg)
        {
            PromptEntityOptions opt = new PromptEntityOptions(
                "\n" + pickingMsg);
            opt.SetRejectMessage(
                "\nInvalid pick: not a entity of \"" + 
                entType.Name + "\" type.");
            opt.AddAllowedClass(entType, true);
 
            PromptEntityResult res = ed.GetEntity(opt);
            if (res.Status == PromptStatus.OK)
                return res.ObjectId;
            else
                return ObjectId.Null;
        }
 
        #endregion
    }
}

Finally, I put everything together in a CommandClass MyCadCommands:

using Autodesk.AutoCAD.ApplicationServices;
using Autodesk.AutoCAD.DatabaseServices;
using Autodesk.AutoCAD.EditorInput;
using Autodesk.AutoCAD.Runtime;
using CadApp = Autodesk.AutoCAD.ApplicationServices.Application;
 
[assembly: CommandClass(typeof(EntityModifiedObjectOverule.MyCadCommands))]
 
namespace EntityModifiedObjectOverule
{
    public class MyCadCommands
    {
        private static bool _lineOverruleEnabled=false;
        private const string LINE_XDATA_APP_NAME = "Snap-Length-Line";
 
        private static bool _pairOverruleEnabled = false;
        private const string PAIR_XDATA_APP_NAME = "Line-Circle-Pair";
 
        [CommandMethod("MyLineOverrule")]
        public static void EnableSnapLengthLineObjectOverrule()
        {
            Document dwg = CadApp.DocumentManager.MdiActiveDocument;
            Editor ed = dwg.Editor;
 
            try
            {
                if (!_lineOverruleEnabled)
                {
                    MyLineObjectOverrule.Instance.StartOverrule(
                        LINE_XDATA_APP_NAME, CadHelper.ForceLineLength);
                    _lineOverruleEnabled = true;
                    ed.WriteMessage(
                        "\nSnap-length-line overrule has been enabled.");
                }
                else
                {
                    MyLineObjectOverrule.Instance.StopOverrule();
                    _lineOverruleEnabled = false;
                    ed.WriteMessage(
                        "\nSnap-length-line overrule has been disabled.");
                }
            }
            catch (System.Exception ex)
            {
                ed.WriteMessage(
                    "\nError: {0}\n{1}", ex.Message, ex.StackTrace);
            }
            finally
            {
                Autodesk.AutoCAD.Internal.Utils.PostCommandPrompt();
            }
        }
 
        [CommandMethod("FlagMyLine")]
        public static void SetSnapLengthFlag()
        {
            Document dwg = CadApp.DocumentManager.MdiActiveDocument;
            Editor ed = dwg.Editor;
 
            try
            {
                ObjectId[] lines = SelectLines(ed);
                if (lines != null)
                {
                    foreach (var id in lines)
                    {
                        CadHelper.SetSnapLengthFlagToLine(
                            id, LINE_XDATA_APP_NAME, 2.0);
                    }
                }
                else
                {
                    ed.WriteMessage("\n*Cancel*");
                }
            }
            catch (System.Exception ex)
            {
                ed.WriteMessage(
                    "\nError: {0}\n{1}", ex.Message, ex.StackTrace);
            }
            finally
            {
                Autodesk.AutoCAD.Internal.Utils.PostCommandPrompt();
            }
        }
 
        [CommandMethod("DeflagMyLine")]
        public static void RemoveSnapLengthFlag()
        {
            Document dwg = CadApp.DocumentManager.MdiActiveDocument;
            Editor ed = dwg.Editor;
 
            try
            {
                ObjectId[] lines = SelectLines(ed);
                if (lines != null)
                {
                    foreach (var id in lines)
                    {
                        CadHelper.ClearSnapLengthFlagFromLine(
                            id, LINE_XDATA_APP_NAME);
                    }
                }
                else
                {
                    ed.WriteMessage("\n*Cancel*");
                }
            }
            catch (System.Exception ex)
            {
                ed.WriteMessage(
                    "\nError: {0}\n{1}", ex.Message, ex.StackTrace);
            }
            finally
            {
                Autodesk.AutoCAD.Internal.Utils.PostCommandPrompt();
            }
        }
 
        [CommandMethod("MyPairOverrule")]
        public static void EnablePairObjectOverrule()
        {
            Document dwg = CadApp.DocumentManager.MdiActiveDocument;
            Editor ed = dwg.Editor;
 
            try
            {
                if (!_pairOverruleEnabled)
                {
                    MyPairedEntitiesObjectOverrule.Instance.StartOverrule(
                        PAIR_XDATA_APP_NAME, CadHelper.ForceLinkedLineAndCircle);
                    _pairOverruleEnabled = true;
                    ed.WriteMessage(
                        "\nPaied line-circle overrule has been enabled.");
                }
                else
                {
                    MyPairedEntitiesObjectOverrule.Instance.StopOverrule();
                    _pairOverruleEnabled = false;
                    ed.WriteMessage(
                        "\nPaied line-circle overrule has been disabled.");
                }
            }
            catch (System.Exception ex)
            {
                ed.WriteMessage(
                    "\nError: {0}\n{1}", ex.Message, ex.StackTrace);
            }
            finally
            {
                Autodesk.AutoCAD.Internal.Utils.PostCommandPrompt();
            }
        }
 
        [CommandMethod("MyPair")]
        public static void PairLineAndCircle()
        {
            Document dwg = CadApp.DocumentManager.MdiActiveDocument;
            Editor ed = dwg.Editor;
 
            try
            {
                if (!MyPairedEntitiesObjectOverrule.Instance.PairLineAndCircle())
                {
                    ed.WriteMessage("\n*Cancel*");
                }
            }
            catch (System.Exception ex)
            {
                ed.WriteMessage(
                    "\nError: {0}\n{1}", ex.Message, ex.StackTrace);
            }
            finally
            {
                Autodesk.AutoCAD.Internal.Utils.PostCommandPrompt();
            }
        }
 
        #region private methods

        private static ObjectId[] SelectLines(Editor ed)
        {
            PromptSelectionOptions opt=new PromptSelectionOptions();
            opt.MessageForAdding = "Select line:";
 
            TypedValue[] vals=new TypedValue[]
            {
                new TypedValue((int)DxfCode.Start,"LINE")
            };
 
            PromptSelectionResult res = ed.GetSelection(
                opt, new SelectionFilter(vals));
 
            if (res.Status==PromptStatus.OK)
            {
                return res.Value.GetObjectIds();
            }
            else
            {
                return null;
            }
        }
 
        #endregion
    }
}

In comparison to the approach of handling CommandWillStart/CommnadEnded/ObjectModified events, the code of using ObjectOverrule is much simpler.

See this video clip for the action of the MyLineObjectOverrule class.
See this video clip for the action of the MyPairedEntitiesObjectOverrule class.

The source code of the project can be downloaded here.