From 65fe268a473b5361d56f090be64e1dd623acfd51 Mon Sep 17 00:00:00 2001
From: Paulo Meira <10246101+PMeira@users.noreply.github.com>
Date: Mon, 18 Mar 2024 23:10:32 -0300
Subject: [PATCH] Obj: Expose the internal DSSObjectFlags

---
 docs/changelog.md       |  1 +
 include/dss_capi.h      | 32 ++++++++++++++++++++++++++++++++
 include/dss_capi_ctx.h  |  8 ++++++++
 src/CAPI/CAPI_Obj.pas   | 12 ++++++++++++
 src/Common/DSSClass.pas |  8 ++++----
 src/dss_capi.lpr        |  2 ++
 6 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/docs/changelog.md b/docs/changelog.md
index 58ea6b55f..db7ef98a1 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -22,6 +22,7 @@
 Minor release, relevant changes only in the Alt API, i.e. no need to upgrade if you don't use it.
 
 - Alt/Obj, Batch: adjust checks for new elements. Refactored some other internal code to simplify this kind of check.
+- Obj: expose internal object flags.
 - ReduceAlgs: Very minor code clean-up.
 - Header: Where possible, use uint32_t for bit sets (flags, options).
 
diff --git a/include/dss_capi.h b/include/dss_capi.h
index 8a4653370..0729cf606 100644
--- a/include/dss_capi.h
+++ b/include/dss_capi.h
@@ -514,6 +514,28 @@ extern "C" {
         */
     };
 
+    /*!
+    Object flags are bit flags used by various of the internal processes of the DSS engine.
+
+    Most are internal state, but advanced/expert users can manipulate them for some interesting uses.
+    */
+    enum DSSObjectFlags {
+        DSSObjectFlags_Editing = 0x0001,
+        DSSObjectFlags_HasBeenSaved = 0x0002,
+        DSSObjectFlags_DefaultAndUnedited = 0x0004,
+        DSSObjectFlags_Checked = 0x0008,
+        DSSObjectFlags_Flag = 0x0010, ///< General purpose flag for each object
+        DSSObjectFlags_HasEnergyMeter = 0x0020,
+        DSSObjectFlags_HasSensorObj = 0x0040,
+        DSSObjectFlags_IsIsolated = 0x0080,
+        DSSObjectFlags_HasControl = 0x0100,
+        DSSObjectFlags_IsMonitored = 0x0200, ///< Indicates some control is monitoring this element
+        DSSObjectFlags_HasOCPDevice = 0x0400, ///< Fuse, Relay, or Recloser
+        DSSObjectFlags_HasAutoOCPDevice = 0x0800, ///< Relay or Recloser only
+        DSSObjectFlags_NeedsRecalc = 0x1000, ///< Used for Edit command loops
+        DSSObjectFlags_NeedsYPrim = 0x2000 ///< Used for Edit command loops + setter flags
+    };
+
     /*!
     Setter flags customize down how the update of DSS properties are handled by the
     engine and parts of the API. Use especially in the `Obj` and `Batch` APIs
@@ -7734,6 +7756,16 @@ extern "C" {
     */
     DSS_CAPI_DLL int32_t* Obj_GetPropSeqPtr(void *obj);
 
+    /*!
+    Copy of the internal flags (bitset from DSSObjectFlags) of a DSS object -- for expert users
+    */
+    DSS_CAPI_DLL uint32_t Obj_GetFlags(void *obj);
+
+    /*!
+    Replace the internal flags of a DSS object -- for expert users
+    */
+    DSS_CAPI_DLL void Obj_SetFlags(void *obj, uint32_t flags);
+
     DSS_CAPI_DLL double Obj_GetFloat64(void *obj, int32_t Index);
     DSS_CAPI_DLL int32_t Obj_GetInt32(void *obj, int32_t Index);
     DSS_CAPI_DLL void* Obj_GetObject(void *obj, int32_t Index);
diff --git a/include/dss_capi_ctx.h b/include/dss_capi_ctx.h
index 3c3208343..b1159647c 100644
--- a/include/dss_capi_ctx.h
+++ b/include/dss_capi_ctx.h
@@ -7152,6 +7152,14 @@ extern "C" {
     (API Extension)
     */
 
+    /*!
+    Copy of the internal flags (bitset from DSSObjectFlags) of a DSS object -- for expert users
+    */
+
+    /*!
+    Replace the internal flags of a DSS object -- for expert users
+    */
+
     
 
 
diff --git a/src/CAPI/CAPI_Obj.pas b/src/CAPI/CAPI_Obj.pas
index 69af405d4..d96b132e0 100644
--- a/src/CAPI/CAPI_Obj.pas
+++ b/src/CAPI/CAPI_Obj.pas
@@ -87,6 +87,8 @@ procedure Obj_BeginEdit(obj: TDSSObject); CDECL;
 procedure Obj_EndEdit(obj: TDSSObject; NumChanges: Integer); CDECL;
 procedure Obj_Activate(obj: TDSSObject; AllLists: TAltAPIBoolean); CDECL;
 function Obj_GetPropSeqPtr(obj: TDSSObject): PInteger; CDECL;
+function Obj_GetFlags(obj: TDSSObject): TDSSObjectFlags; CDECL;
+procedure Obj_SetFlags(obj: TDSSObject; flags: TDSSObjectFlags) CDECL;
 
 function Obj_GetFloat64(obj: TDSSObject; Index: Integer): Double; CDECL;
 function Obj_GetInt32(obj: TDSSObject; Index: Integer): Integer; CDECL;
@@ -413,6 +415,16 @@ function Obj_GetPropSeqPtr(obj: TDSSObject): PInteger; CDECL;
     Result := PInteger(obj.PrpSequence);
 end;
 
+function Obj_GetFlags(obj: TDSSObject): TDSSObjectFlags; CDECL;
+begin
+    Result := obj.Flags;
+end;
+
+procedure Obj_SetFlags(obj: TDSSObject; flags: TDSSObjectFlags) CDECL;
+begin
+    obj.Flags := flags;
+end;
+
 function Obj_GetName(obj: TDSSObject): PAnsiChar; CDECL;
 begin
     Result := PAnsiChar(obj.Name);
diff --git a/src/Common/DSSClass.pas b/src/Common/DSSClass.pas
index ae9977a7d..6102a9ef4 100644
--- a/src/Common/DSSClass.pas
+++ b/src/Common/DSSClass.pas
@@ -143,13 +143,13 @@ interface
         IsIsolated,
         HasControl,
         IsMonitored, // indicates some control is monitoring this element
-        // IsPartofFeeder,  -- UNUSED
-        // Drawn,  // Flag used in tree searches etc  -- UNUSED
         HasOCPDevice, // Fuse, Relay, or Recloser
         HasAutoOCPDevice, // Relay or Recloser only
-        // HasSwtControl // Has a remotely-controlled Switch -- UNUSED
         NeedsRecalc, // Used for Edit command loops
-        NeedsYprim // Used for Edit command loops + setter flags
+        NeedsYPrim // Used for Edit command loops + setter flags
+        // IsPartofFeeder,  -- UNUSED
+        // Drawn,  // Flag used in tree searches etc  -- UNUSED
+        // HasSwtControl // Has a remotely-controlled Switch -- UNUSED
     );
     TDSSObjectFlags = set of TDSSObjectFlag;
     Flg = TDSSObjectFlag;
diff --git a/src/dss_capi.lpr b/src/dss_capi.lpr
index faf646347..d79d779a3 100644
--- a/src/dss_capi.lpr
+++ b/src/dss_capi.lpr
@@ -2020,6 +2020,8 @@
     Obj_PropertySideEffects,
     Obj_BeginEdit,
     Obj_EndEdit,
+    Obj_GetFlags,
+    Obj_SetFlags,
     Obj_Activate,
     Obj_GetPropSeqPtr,
     Obj_GetFloat64,