ElementHandle.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------+
|
|   Supplied under applicable software license agreement.
|
|   Copyright (c) 2018 Bentley Systems, Incorporated. All rights reserved.
|
+---------------------------------------------------------------------------------------*/
#pragma once

#include <Bentley/RefCounted.h>
#include "DgnPlatform.h"
#include "Handler.h"
#include "DgnFile.h"
#include "DgnFileIO/MSElementDescr.h"
#include "DgnModel.h"
#include "DgnFileIO/XAttributeIter.h"
#include "XAttributeChange.h"

DGNPLATFORM_TYPEDEFS (ElementLinkageIterator)
DGNPLATFORM_TYPEDEFS (ConstElementLinkageIterator)

BEGIN_BENTLEY_DGNPLATFORM_NAMESPACE

struct ITxn;
class  Handler;

// =======================================================================================
// =======================================================================================
enum            MissingHandlerPermissions
{
    MISSING_HANDLER_PERMISSION_None             = 0x0000,       
    MISSING_HANDLER_PERMISSION_Delete           = (1<<0),       
    MISSING_HANDLER_PERMISSION_Copy             = (1<<1),       
    MISSING_HANDLER_PERMISSION_Draw             = (1<<3),       
    MISSING_HANDLER_PERMISSION_Manipulators     = (1<<4),       
    MISSING_HANDLER_PERMISSION_Move             = (1<<5),       
    MISSING_HANDLER_PERMISSION_Transform        = (1<<6),       
    MISSING_HANDLER_PERMISSION_CurveEdit        = (1<<7),       
    MISSING_HANDLER_PERMISSION_ChangeAttrib     = (1<<9),       
    MISSING_HANDLER_PERMISSION_All_             = 0xffffffff,   
};


/*=================================================================================**/
struct      ChildElemIter;
struct      ChildEditElemIter;


// =======================================================================================
//  @remark Required library : DgnPlatform<ApiNumber>.lib  i.e. DgnPlatform5.lib
// @bsiclass                                                     Bentley Systems
// =======================================================================================
struct  ElemHandleBase
{
    ElementRefP         m_elRef;
    MSElementCP         m_cacheElem;
    DgnModelRefP        m_modelRef;
    MSElementDescrP     m_descr;
    IElementStateP      m_state;
    bool                m_isPersistent;    // Is the underlying element persistent?
    bool                m_descrOwned;
};

/*=================================================================================**/
struct     IElementState : public IRefCounted {};

// =======================================================================================




//  @remark Required library : DgnPlatform<ApiNumber>.lib  i.e. DgnPlatform5.lib
// @bsiclass                                                     Bentley Systems
// =======================================================================================
CLRPUBLIC struct    ElementHandle : protected  ElemHandleBase
{

protected:
    DGNPLATFORM_EXPORT ElementHandleR CopyFrom (ElementHandleCR from);
    void  ClearElementDescr()
        {
        if (m_descr)
            {
            if (m_descrOwned)
                {
                m_descr->Release();

                m_descrOwned = false;
                }
            m_descr = NULL;
            }
        }

    void ClearCacheElem()
        {
        if (m_cacheElem)
            ReleaseCacheElem();
        }

    void ClearElemState()
        {
        if (m_state)
            {
            m_state->Release();
            m_state = NULL;
            }
        }

    void ClearAll() {ClearElementDescr(); ClearCacheElem(); ClearElemState();}
    DGNPLATFORM_EXPORT void AssignElementRef (ElementRefP elRef, DgnModelRefP modelRef, bool resolveTransientElementRef=true);
    void Invalidate () {ClearAll(); m_elRef = NULL; m_modelRef = NULL;}
    DGNPLATFORM_EXPORT void AssignElemDescr (MSElementDescrP, bool owned, bool isPersistent, DgnModelRefP);
    void ReleaseCacheElem () {m_cacheElem=NULL;}
    DGNPLATFORM_EXPORT MSElementCP GetUnstableMSElementCP () const;

    DGNPLATFORM_EXPORT void Init (ElementRefP elRef, DgnModelRefP modelRef);
    DGNPLATFORM_EXPORT void Init (MSElementDescrCP elDscr, bool owned, bool isPersistent, DgnModelRefP modelRef);
    

public:
    ElementHandle () {Init (NULL, NULL);} 
    ~ElementHandle () {ClearAll();}

    explicit ElementHandle (ElementRefP elRef, DgnModelRefP modelRef=NULL) {Init (elRef, modelRef);}

    DGNPLATFORM_EXPORT ElementHandle (ElementId id, DgnModelRefP modelRef);

    ElementHandle (MSElementDescrCP elDscr, bool owned, bool isUnmodified=false, DgnModelRefP modelRef=NULL) {Init (elDscr, owned, isUnmodified, modelRef);}

    DGNPLATFORM_EXPORT ElementHandle (MSElementCP el, DgnModelRefP modelRef);

    ElementHandle (ElementHandleCR from) {CopyFrom (from);} 
    ElementHandleR operator= (ElementHandleCR from)
        {
        if (this == &from)
            return *this;

        ClearAll();
        return CopyFrom (from);
        }


    DGNPLATFORM_EXPORT void ResetHandler () const;

    DGNPLATFORM_EXPORT Handler& GetHandler (MissingHandlerPermissions perm=MISSING_HANDLER_PERMISSION_None) const;

    DisplayHandlerP GetDisplayHandler () const {return GetHandler(MISSING_HANDLER_PERMISSION_None).GetDisplayHandler();}

    IDependencyHandlerP GetIDependencyHandler () const {return GetHandler().GetIDependencyHandler();}

    ITransactionHandlerP GetITransactionHandler () const {return GetHandler().GetITransactionHandler();}

    DGNPLATFORM_EXPORT ITextQueryCP GetITextQuery () const;

    DGNPLATFORM_EXPORT ITextEditP GetITextEdit () const;



    ElementRefP GetElementRef () const {return m_elRef;}

    DGNPLATFORM_EXPORT DgnModelP GetDgnModelP () const;

    DgnFileP GetDgnFileP () const {DgnModelP dgnCache = GetDgnModelP (); return (NULL == dgnCache) ? NULL : dgnCache->GetDgnFileP ();}

    DgnModelRefP GetModelRef () const {return m_modelRef;}

    MSElementCP GetElementCP () const {return m_descr ? &m_descr->el : GetUnstableMSElementCP();}

    bool IsValid () const {return (NULL != m_elRef) || (NULL != m_descr);}

    bool IsPersistent () const {return m_isPersistent;}

    int GetElementType () const {return GetElementCP()->ehdr.type;}

    void GetElementHeader (Elm_hdr& hdr) const {hdr = GetElementCP()->ehdr;}

    MSElementDescrCP PeekElementDescrCP () const {return m_descr;}

    DGNPLATFORM_EXPORT MSElementDescrCP GetElementDescrCP () const;




    DGNPLATFORM_EXPORT ConstElementLinkageIterator BeginElementLinkages (UInt16 rl = 0) const;

    DGNPLATFORM_EXPORT ConstElementLinkageIterator EndElementLinkages () const;
    
    DGNPLATFORM_EXPORT ElementId GetElementId () const;
};

/*=================================================================================**/
CLRPUBLIC struct  EditElementHandle : public ElementHandle
{

private:
    EditElementHandleR operator= (EditElementHandleCR from); // illegal!!
    explicit EditElementHandle (ElementHandleCR from);        // illegal!!
    explicit EditElementHandle (EditElementHandleCR from);    // illegal!!

    MSElementDescrP ExtractElementDescr0 ();

public:

    EditElementHandle() {} 

    EditElementHandle (MSElementDescrP descr, bool owned, bool isUnmodified, DgnModelRefP modelRef=NULL) : ElementHandle (descr, owned, isUnmodified, modelRef) {}

    EditElementHandle (ElementRefP elRef, DgnModelRefP modelRef=NULL) : ElementHandle (elRef, modelRef) {}

    EditElementHandle (MSElementCP el, DgnModelRefP modelRef) : ElementHandle (el, modelRef){}

    EditElementHandle (ElementId id, DgnModelRefP modelRef) : ElementHandle (id, modelRef) {}

    DGNPLATFORM_EXPORT EditElementHandle (ElementHandleCR from, bool duplicateDescr);

    DGNPLATFORM_EXPORT void Duplicate (ElementHandleCR);

    DGNPLATFORM_EXPORT void SetModelRef (DgnModelRefP modelRef);

    void SetNonPersistent () {m_isPersistent = false; m_elRef = NULL;}

    void Invalidate () {ElementHandle::Invalidate ();}

    void SetIElementState (IElementStateP state) {ClearElemState (); m_state = state; if (m_state) m_state->AddRef ();}
    IElementStateP GetIElementState () {return m_state;}



    MSElementDescrP GetElementDescrP () {return (MSElementDescrP) ElementHandle::GetElementDescrCP();}

    MSElementP GetElementP () {GetElementDescrP(); return m_descr ? &m_descr->el : NULL;}

    DGNPLATFORM_EXPORT StatusInt ReplaceElement (MSElementCP el);

    DGNPLATFORM_EXPORT StatusInt ReplaceElementDescr (MSElementDescrP elDscr);

    DGNPLATFORM_EXPORT MSElementDescrP ExtractElementDescr ();

    void SetElementDescr (MSElementDescrP elDscr, bool owned, bool isUnmodified, DgnModelRefP modelRef = NULL) {AssignElemDescr (elDscr, owned, isUnmodified, modelRef);}

    void SetElementRef (ElementRefP elRef, DgnModelRefP modelRef) {AssignElementRef (elRef, modelRef);}
    




    DGNPLATFORM_EXPORT StatusInt ScheduleWriteXAttribute (XAttributeHandlerIdCR h, UInt32 xAttrId, size_t dataSize, void const* data);

    DGNPLATFORM_EXPORT StatusInt CancelWriteXAttribute (XAttributeHandlerIdCR h, UInt32 xAttrId);

    DGNPLATFORM_EXPORT StatusInt ScheduleDeleteXAttribute (XAttributeHandlerIdCR h, UInt32 xAttrId);

    DGNPLATFORM_EXPORT StatusInt CancelDeleteXAttribute (XAttributeHandlerIdCR h, UInt32 xAttrId);


    DGNPLATFORM_EXPORT StatusInt FindByID (ElementId elemID, DgnModelP dgnCache, bool allowDeleted = false);

    DGNPLATFORM_EXPORT StatusInt FindByID (ElementId elemID, DgnModelRefP modelRef, bool allowDeleted = false);



    DGNPLATFORM_EXPORT StatusInt AddToModel ();

    DGNPLATFORM_EXPORT StatusInt DeleteFromModel ();

    DGNPLATFORM_EXPORT StatusInt ReplaceInModel (ElementRefP oldRef);



    DGNPLATFORM_EXPORT ElementLinkageIterator BeginElementLinkages (UInt16 rl = 0);

    DGNPLATFORM_EXPORT ElementLinkageIterator EndElementLinkages ();

    DGNPLATFORM_EXPORT StatusInt ReplaceElementLinkage (ElementLinkageIteratorR it, LinkageHeader const& newLinkageHeader, void const* newLinkageData);


    DGNPLATFORM_EXPORT StatusInt RemoveElementLinkage (ElementLinkageIteratorR it);

    DGNPLATFORM_EXPORT StatusInt InsertElementLinkage (ElementLinkageIterator* newLinkageIt, LinkageHeaderCR newLinkageHeader, void const* newLinkageData, ElementLinkageIterator& wh, UInt16 rl = 0);
    
    DGNPLATFORM_EXPORT StatusInt AppendElementLinkage (ElementLinkageIterator* newLinkageIt, LinkageHeaderCR newLinkageHeader, void const* newLinkageData);
};

/*=================================================================================**/
struct     IElementSet
{
    virtual size_t GetCount () = 0;

    virtual bool GetFirst (ElementHandleR elHandle) = 0;

    virtual bool GetNext (ElementHandleR elHandle) = 0;
};

/*=================================================================================**/
struct  ChildElemIter : public ElementHandle
{

private:
    bool                          m_hasDescr;
    ElementRefVecP                m_subElements;
    ElementRefVec::const_iterator m_iter;

    DGNPLATFORM_EXPORT void ToNext_();

public:
    ChildElemIter () { m_hasDescr=false; m_subElements=NULL;}

    DGNPLATFORM_EXPORT ChildElemIter (ChildElemIter const& from);
    DGNPLATFORM_EXPORT ChildElemIter& operator=(ChildElemIter const& from);

    //  @note To test for a public child that supports a specific modification (such as in a locate filter) a ChildElemIter 
    //        should be initialized using ExposeChildrenReason::Edit instead of creating a ChildEditElemIter.
    DGNPLATFORM_EXPORT explicit ChildElemIter (ElementHandleCR from, ExposeChildrenReason reason=ExposeChildrenReason::Query);

    ChildElemIter ToNext () const {ChildElemIter n (*this); n.ToNext_(); return n;}
};

/*=================================================================================**/
struct  ChildEditElemIter : public EditElementHandle
{
private:
    MSElementDescrP m_nextDescr;
    DGNPLATFORM_EXPORT void InitFrom (MSElementDescrP, DgnModelRefP, bool isPersistent);

public:
    ChildEditElemIter() { m_nextDescr=NULL;}
    DGNPLATFORM_EXPORT ~ChildEditElemIter();
    DGNPLATFORM_EXPORT ChildEditElemIter& operator= (ChildEditElemIter const&);
    DGNPLATFORM_EXPORT ChildEditElemIter (ChildEditElemIter const&);


    DGNPLATFORM_EXPORT explicit ChildEditElemIter (EditElementHandleR from);

    ChildEditElemIter ToNext () {ChildEditElemIter n; n.InitFrom (m_nextDescr, m_modelRef, IsPersistent()); return n;};
};

// =======================================================================================
//  @remark Required library : DgnPlatform<ApiNumber>.lib  i.e. DgnPlatform5.lib
// @bsiclass                                                     Bentley Systems
// =======================================================================================
struct          ConstElementLinkageIterator
{
protected:
    friend struct      ElementHandle;
    LinkageHeader const* m_thisLinkage;
    LinkageHeader const* m_end;
    UInt16               m_requestedLinkage;



public:
    ConstElementLinkageIterator () {m_thisLinkage=m_end=0; m_requestedLinkage=0;}

    DGNPLATFORM_EXPORT bool IsValid () const;

    DGNPLATFORM_EXPORT bool ToNext ();

    ConstElementLinkageIterator& operator++ () {ToNext(); return *this;}
    bool operator== (ConstElementLinkageIterator const& rhs) const {return m_thisLinkage == rhs.m_thisLinkage;}
    bool operator!= (ConstElementLinkageIterator const& rhs) const {return !(m_thisLinkage == rhs.m_thisLinkage);}

    LinkageHeader const& operator* () const {return *m_thisLinkage;}

    LinkageHeader const* operator-> () const {return m_thisLinkage;}

    void const* GetData () const {return m_thisLinkage + 1;}

    LinkageHeader const* GetLinkage () const {return m_thisLinkage;}

}; // ConstElementLinkageIterator

// =======================================================================================
// @bsiclass                                                     Bentley Systems
// =======================================================================================
struct          ElementLinkageIterator : ConstElementLinkageIterator
{

protected:


public:
    ElementLinkageIterator () : ConstElementLinkageIterator () {;}

    ElementLinkageIterator& operator++() {ToNext(); return *this;}
    bool operator==(ElementLinkageIterator const& rhs) const {return m_thisLinkage == rhs.m_thisLinkage;}
    bool operator!=(ElementLinkageIterator const& rhs) const {return !(m_thisLinkage == rhs.m_thisLinkage);}

    LinkageHeader& operator*() {return const_cast<LinkageHeader&>(*m_thisLinkage);}

    LinkageHeader* operator->() {return const_cast<LinkageHeader*>(m_thisLinkage);}

    void* GetDataRW () {return const_cast<void*>(GetData());}

}; // ReadWriteElementLinkageIterator

END_BENTLEY_DGNPLATFORM_NAMESPACE