/////////////////////////////////////////////////////////////////////////////// // Copyright (C) 2002-2025, Open Design Alliance (the "Alliance"). // All rights reserved. // // This software and its documentation and related materials are owned by // the Alliance. The software may only be incorporated into application // programs owned by members of the Alliance, subject to a signed // Membership Agreement and Supplemental Software License Agreement with the // Alliance. The structure and organization of this software are the valuable // trade secrets of the Alliance and its suppliers. The software is also // protected by copyright law and international treaty provisions. Application // programs incorporating this software must include the following statement // with their copyright notices: // // This application incorporates Open Design Alliance software pursuant to a license // agreement with Open Design Alliance. // Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance. // All rights reserved. // // By use of this software, its documentation or related materials, you // acknowledge and accept the above terms. /////////////////////////////////////////////////////////////////////////////// #ifndef _ODRXMEMBER_INCLUDED_ #define _ODRXMEMBER_INCLUDED_ #include "OdString.h" #include "OdArray.h" #include "RxOverrule.h" #include "SharedPtr.h" //DOM-IGNORE-BEGIN class OdRxValue; class OdRxValueType; class OdRxAttributeCollection; class OdRxPromotingQueryContext; class OdRxMemberIteratorImpl; class OdRxMemberQueryContextImpl; class OdRxMemberQueryEngineImpl; class OdRxMemberImpl; class OdRxMemberCollectionImpl; class OdRxMember; //DOM-IGNORE-END /** \details This template class is a specialization of the OdSmartPtr class for OdRxMember object pointers. */ typedef OdSmartPtr OdRxMemberPtr; /** \details Base class for properties and methods. */ class ODRX_ABSTRACT FIRSTDLL_EXPORT OdRxMember : public OdRxObject { public: //DOM-IGNORE-BEGIN ODRX_DECLARE_MEMBERS(OdRxMember); //DOM-IGNORE-END /** \details Gets the static unlocalized name of the property. \returns Name of the property. */ const OdString& name() const throw(); /** \details Gets the localized name (can be loaded from resources via OdRxLocalizedNameAttribute::getLocalizedName). \returns Localized name of the property. */ OdString localName() const throw(); /** \details Gets the property value type. \returns Property value type. */ const OdRxValueType& type()const throw(); /** \details Gets the attributes that are used on some properties to modify their behavior. E.g., OdRxLocalizedNameAttribute defines localName(). See RxAttributes.h for more information. \returns Collection of property attributes. */ const OdRxAttributeCollection& attributes() const throw(); /** \details Gets the attributes that are used on some properties to modify their behavior. E.g., OdRxLocalizedNameAttribute defines localName(). See RxAttributes.h for more information. \returns Collection of property attributes. */ OdRxAttributeCollection& attributes() throw(); /** \details Gets the owner of the property. For the usual properties owner is the OdRxClass they are attached to. For subproperties owner is the main property. \returns Owner of the property. */ const OdRxObject* owner() const throw(); /** \details Gets the array of subproperties (child properties). \returns Array of subproperties (child properties). \remarks Some properties may have child properties, e.g., "EndPoint" property of OdDbLine has subproperties "EndPoint/X", "EndPoint/Y", "EndPoint/Z". */ const OdArray* children() const throw(); /** \details Removes this member from the owner and fires "goodbye" reactors registered with the OdRxMemberQueryEngine. \param pMember [in] Property to be removed. \remarks This method should be used to delete properties while unloading. */ static void deleteMember(const OdRxMember* pMember) throw(); protected: friend class OdRxMemberImpl; ~OdRxMember() override; OdRxMember(OdRxMemberImpl*); /** \details Descendants may overload localized name obtaining method. */ virtual OdString subLocalName() const; /** \details Adds an array of member children. \param children [in] An array of children. \returns eOk if a member child array is added successfully, or a corresponding error type otherwise. \remarks First call to children calls subChildren, if it returned eNotApplicable then subChildrenEx is called. subChildren() is expected to adds members children array. */ virtual OdResult subChildren(OdArray& children) const; /** \details Adds properties in bulk. \returns eOk if properties are added in bulk successfully, or a corresponding error type otherwise. \remarks pChildren array is managed by the function itself. */ virtual OdResult subChildrenEx(OdArray*& pChildren) const; /** \details Assigns an unlocalized name, type and owner to this member. \remarks Initialization method used by descendants. */ void init(const OdString& name, const OdRxValueType* type, const OdRxObject* owner = 0); OdRxMemberImpl* m_pImpl; }; //DOM-IGNORE-BEGIN class OdRxEnumTag; //DOM-IGNORE-END /** \details This template class is a specialization of the OdSmartPtr class for OdRxEnumTag object pointers. */ typedef OdSmartPtr OdRxEnumTagPtr; //DOM-IGNORE-BEGIN class OdRxEnumTagImpl; //DOM-IGNORE-END /** \details This class describes a single item of an enumeration in OdRxEnumType. */ class FIRSTDLL_EXPORT OdRxEnumTag : public OdRxMember { public: //DOM-IGNORE-BEGIN ODRX_DECLARE_MEMBERS(OdRxEnumTag); //DOM-IGNORE-END /** \details Creates a new enumeration member descriptor. \param name [in] Name of the enumeration item. \param value [in] Value, containing the underlying enumeration item. \param owner [in] Owner of the enumeration item (OdRxEnumType). \returns Pointer to the created enumeration member descriptor. */ static OdRxEnumTagPtr createObject(const OdChar* name, const OdRxValue& value, const OdRxObject* owner); /** \details Value with the element of the enumeration, described by this tag. \returns Value, described by this tag. */ const OdRxValue& value() const; /** \details Queries OdRxAlternateLocalizedNameAttribute to retrieve the alternative local name. \returns Alternate local name. */ OdString alternateLocalName() const; protected: OdRxEnumTag(OdRxMemberImpl*); /** \details Overloaded implementation of the alternateLocalName() function. Should use OdRxAlternateLocalizedNameAttribute by default. */ virtual OdString subAlternateLocalName() const; }; /** \details Simple container interface for the members. */ class ODRX_ABSTRACT FIRSTDLL_EXPORT OdRxMemberCollection { public: /** \details Destroys objects of the OdRxMemberCollection class. */ virtual ~OdRxMemberCollection(); /** \details Returns the number of members in the collection. \returns Number of members. */ virtual int count() const = 0; /** \details Returns the member at the specified index. \param index [in] Index of the member to be got. \returns Member at the specified index. */ virtual OdRxMember* getAt(int index) const = 0; }; /** \details Helper class passed to the user callback to add new members to the class. */ class FIRSTDLL_EXPORT OdRxMemberCollectionBuilder { public: /** \details Adds specified member to the class member collection. \param member [in] Member to be added. */ void add(OdRxMember* member); /** \details Gets the object that members are being added to. \returns Owner object. */ const OdRxClass* owner() const { return m_owner; } private: friend class OdRxMemberCollectionImpl; OdRxMemberCollectionBuilder(OdRxMemberCollectionImpl* imp, const OdRxClass* owner) : m_pImpl(imp), m_owner(owner) {} OdRxMemberCollectionImpl* m_pImpl; const OdRxClass* m_owner; }; /** \details Member iterator interface. Used by OdRxMemberQueryEngine. */ class FIRSTDLL_EXPORT OdRxMemberIterator { public: /** \details Destroys objects of the OdRxMemberIterator class. */ virtual ~OdRxMemberIterator(); /** \details Returns true if the iteration is finished. \returns true if the traversal by this iterator object is complete; false otherwise. */ virtual bool done(); /** \details Steps to the next member. \returns true if the iteration succeded; false otherwise. */ virtual bool next(); /** \details Returns the member currently being pointed at by the iterator. \returns Member, currently being pointed at. */ virtual OdRxMember* current() const; /** \details Iterates the list until member with that name is found (otherwise returns NULL). \param name [in] Name of the member to be found. \returns Pointer to the member if it was found; NULL otherwise. */ virtual OdRxMemberPtr find(const OdChar* name) const; /** \details Returns the number of iterated objects. \returns The size of the collection by which iteration is performed. */ virtual OdUInt64 size() const; protected: OdRxMemberIterator(); private: friend class OdRxMemberIteratorImpl; OdRxMemberIteratorImpl* m_pImpl; }; /** \details This template class is a specialization of the OdSharedPtr class for OdRxMemberIterator object pointers. */ typedef OdSharedPtr OdRxMemberIteratorPtr; /** \details Class that makes a list of members for the iterator. It is called by the engine with a list of the facets it has collected. Facets include the object class. It is up to the context to check the class parents. */ class ODRX_ABSTRACT FIRSTDLL_EXPORT OdRxMemberQueryContext : public OdRxObject { public: //DOM-IGNORE-BEGIN ODRX_DECLARE_MEMBERS(OdRxMemberQueryContext); //DOM-IGNORE-END /** \details Builds an iterator listing all the members of these classes (optionally including members of parents and children of members). Parameters are called "facets", because they can include "extension" classes. \param facets [in] Array of objects. \returns Pointer to the iterator of the members of the specified objects. */ OdRxMemberIteratorPtr newMemberIterator(const OdArray& facets) const; /** \details Gets the pointer to the member of the class by name. \param facets [in] Array of objects. \param name [in] The pointer to the name of member to be found. \returns Pointer to the member if it was found; NULL otherwise. */ virtual OdRxMemberPtr find(const OdArray& facets, const OdChar* name) const; protected: friend class OdRxMemberQueryContextImpl; OdRxMemberQueryContextImpl* m_pImpl; OdRxMemberQueryContext(); ~OdRxMemberQueryContext() override; virtual OdRxMemberIteratorPtr subNewMemberIterator(const OdArray& facets) const = 0; }; /** \details This interface provides a way to extend a given class (or an object) with methods/properties. */ struct ODRX_ABSTRACT FIRSTDLL_EXPORT OdRxFacetProvider : OdRxObject { //DOM-IGNORE-BEGIN ODRX_DECLARE_MEMBERS(OdRxFacetProvider); //DOM-IGNORE-END /** \details This method is called every time when OdRxMemberQueryEngine::find or OdRxMemberQueryEngine::newMemberIterator is called. Facet is an extension class which is used only to get a list of members. Facet provider may add different facets depending on context and object. \param pO [in] Object to get facets of. \param pContext [in] Context. \param facets [out] Array of facets. */ virtual void getFacets(const OdRxObject* pO, const OdRxMemberQueryContext* pContext, OdArray& facets) = 0; }; /** \details This template class is a specialization of the OdSmartPtr class for OdRxFacetProvider object pointers. */ typedef OdSmartPtr OdRxFacetProviderPtr; /** \details Member engine reactor. Currently supports only "goodbye" event. */ class FIRSTDLL_EXPORT OdRxMemberReactor { public: /** \details Destroys objects of the OdRxMemberReactor class. */ virtual ~OdRxMemberReactor() {} /** \details Called when a member is removed from the owner (OdRxMember::deleteMember). */ virtual void goodbye(const OdRxMember* ) {} }; /** \details This class provides ability to enumerate and find members associated with the given object, add new property providers (OdRxFacetProvider) and reactors. */ class FIRSTDLL_EXPORT OdRxMemberQueryEngine { public: /** \details This singleton object is the main access point to the member engine services. \returns The member engine services access point object. */ static OdRxMemberQueryEngine* theEngine(); /** \details Finds a member by name, uses defaultContext() if no context is passed. \param pO [in] Object to search the member in. \param name [in] Name of the member to be found. \param pContext [in] Context. Optional. \param bQueryFacets [in] Flag determines if the function will query members added dynamically by facet providers. Default value is true. \returns Pointer to the found member. */ OdRxMemberPtr find(const OdRxObject* pO, const OdChar* name, const OdRxMemberQueryContext* pContext = NULL, bool bQueryFacets = true) const; /** \details Enumerates all the properties of the object, uses defaultContext() if no context is passed. \param pO [in] Object to enumerate the properties of. \param pContext [in] Context. Optional. \returns Pointer to the iterator of the enumerated properties. */ OdRxMemberIteratorPtr newMemberIterator(const OdRxObject* pO, const OdRxMemberQueryContext* pContext = NULL) const; /** \details Gets a reference to the default query context. Query context handles collecting members in a list. \returns Query context. */ const OdRxMemberQueryContext* defaultContext() const; /** \details Reference to the default promoting query context. Handles collecting members in a list, but unlike the default, this one includes children (sub-properties) in the list, instead of parents. For example OdDbLine property "EndPoint" would be replaced by "EndPoint/X", "EndPoint/Y", "EndPoint/Z" if queried using this context. \returns Promoting query context. */ const OdRxPromotingQueryContext* promotingContext() const; /** \details Registers a new facet provider (to provide extension classes with additional members). \param pProvider [in] Facet provider to be registered. */ void addFacetProvider(OdRxFacetProvider* pProvider); /** \details Unregisters an extension provider. \param pProvider [in] Facet provider to be removed. */ void removeFacetProvider(OdRxFacetProvider* pProvider); /** \details Registers a new reactor. \param pReactor [in] Reactor to be registered. */ void addReactor(OdRxMemberReactor* pReactor); /** \details Unregisters a reactor. \param pReactor [in] Reactor to be removed. */ void removeReactor(OdRxMemberReactor* pReactor); /** \details Class destructor */ ~OdRxMemberQueryEngine(); private: friend class OdRxMemberQueryEngineImpl; OdRxMemberQueryEngineImpl* m_pImpl; OdRxMemberQueryEngine(OdRxMemberQueryEngineImpl*); }; /** \details Base class for properties overrules. Works the same as usual overrules, but per member - not per class. Currently not implemented. */ class FIRSTDLL_EXPORT OdRxMemberOverrule : public OdRxObject { public: //DOM-IGNORE-BEGIN ODRX_DECLARE_MEMBERS(OdRxMemberOverrule); //DOM-IGNORE-END /** \details Registers a new overrule. \param pOverruledSubject [in] Overruled member. \param pOverrule [in] Overrule. \param bAddAtLast [in] If true the overrule is added last. Optional. \returns eOk if a new overrule is registered successfully, or an appropriate error code otherwise. \remarks Not implemented yet. */ static OdResult addOverrule(OdRxMember* pOverruledSubject, OdRxMemberOverrule* pOverrule, bool bAddAtLast = false); /** \details Unregisters an overrule. \param pOverruledSubject [in] Overruled member. \param pOverrule [in] Overrule. \returns eOk if an overrule is unregistered successfully, or an appropriate error code otherwise. \remarks Not implemented yet. */ static OdResult removeOverrule(OdRxMember* pOverruledSubject, OdRxMemberOverrule* pOverrule); }; #endif