Element templates define symbology properties. More...

#include <ElementTemplateNode.h>

Inheritance diagram for ElementTemplateNode:

Public Member Functions
DGNPLATFORM_EXPORT ECN::IECInstancePtr	GetDefaultInstance () const
	Return the "default" IECInstance used to store symbology paraemeters in Element Templates. More...

DGNPLATFORM_EXPORT ECN::IECInstancePtr	GetOrCreateDefaultInstance ()
	Return the "default" IECInstance used to store symbology paraemeters in Element Templates. More...

Public Member Functions inherited from XDataTreeNode
DGNPLATFORM_EXPORT void	SortParent ()
	Sort all children of the parent of this node. More...

DGNPLATFORM_EXPORT void	SortChildren ()
	Sort all children of this node if this node contains child nodes. More...

DGNPLATFORM_EXPORT WString	GetFullPath () const
	Return the full heirarchial path to the XDataTreeNode. More...

DGNPLATFORM_EXPORT WCharCP	GetNameCP () const
	Return pointer to the name of the XDataTreeNode. More...

DGNPLATFORM_EXPORT void	SetName (WCharCP name)
	Set the name of the XDataTreeNode. More...

DGNPLATFORM_EXPORT bool	AllowChildNodes () const
	Return true if node is allowed to have child nodes. More...

DGNPLATFORM_EXPORT DgnPlatform::ElementId	GetParentId () const
	Return the ElementId of the parent node. If the node is a root node a value of 0 is returned. More...

DGNPLATFORM_EXPORT int	GetSortPriority () const
	Return the Sort Priority which is used to determine the postion of the node under its parent node. More...

DGNPLATFORM_EXPORT void	SetSortPriority (int sortPriority)
	Set the Sort Priority which is used to determine the position of the node under its parent node. More...

DGNPLATFORM_EXPORT DgnPlatform::ElementId	GetId () const
	Return the ElementId of the Type 66 element that serves as a host for the node. More...

DGNPLATFORM_EXPORT ElementRefP	GetElementRef () const
	Return the ElementRef of the Type 66 element that serves as a host for the node. More...

DGNPLATFORM_EXPORT StatusInt	Write ()
	Write any node changes to the owner, which is typically a DgnFile. More...

DGNPLATFORM_EXPORT DgnPlatform::HandlerId	GetHandlerId () const
	Return the HandlerId for the node. This is use to determine the type of data the node contains, such as Element Template, Task, NamedTools, Detailing Symbol Styles, etc. More...

DGNPLATFORM_EXPORT XInstanceContainer *	GetXInstanceContainer ()
	Return a pointer to the XInstanceContainer that holds a list of ECXAInstance associated with the node. A NULL will be return if no instances are held by the node. More...

DGNPLATFORM_EXPORT XDataTreeOwner *	GetOwner () const
	Return the XDataTreeOwner that hold the XDataTree that contains the XDataTree node. More...

DGNPLATFORM_EXPORT void	ClearCachedInstances ()
	Clear the cached instances held by the XInstanceContainer. More...

DGNPLATFORM_EXPORT BentleyStatus	ReloadXAttributeData ()
	Reload the XAttribute data which holds the node name, sort priority, and parent node specification. More...

DGNPLATFORM_EXPORT WCharCP	GetPathSeparatorCP () const
	Return the separator character used to separate the individual node names to form the fullpath for the node. More...

DGNPLATFORM_EXPORT ECN::IECInstancePtr	GetECInstanceBySchemaName (WCharCP fullSchemaName) const
	Return a pointer to an IECIntance that is held in the node XInstanceContainer. More...

DGNPLATFORM_EXPORT ECN::IECInstancePtr	GetECInstanceByClassName (WCharCP className) const
	Return a pointer to an IECIntance that is held in the node XInstanceContainer. More...

Public Member Functions inherited from RefCounted< IRefCounted >
void *	operator new (size_t size)

void	operator delete (void *rawMemory, size_t size)

UInt32	AddRef () const

UInt32	Release () const

	RefCounted ()

	RefCounted (RefCounted const &rhs)

RefCounted &	operator= (RefCounted const &rhs)

UInt32	GetRefCount () const

Static Public Member Functions
static DGNPLATFORM_EXPORT ElementTemplateNodePtr	FindByElementId (ElementId elemID, XDataTreeOwner &owner)
	Return a pointer to an ElementTemplateNode for an existing element. More...

static DGNPLATFORM_EXPORT ElementTemplateNodePtr	CreateNode (WCharCP name, ElementId parentId, bool allowChildNodes, int sortPriority, XDataTreeOwner &owner, XInstanceContainer *seedContainer=NULL)
	Create and return a pointer to an ElementTemplateNode. More...

static DGNPLATFORM_EXPORT ElementTemplateNodePtr	CreateNode (WCharCP name, ElementTemplateNodeP parentNode, bool allowChildNodes, int sortPriority, XDataTreeOwner &owner, XInstanceContainer *seedContainer=NULL)
	Create and return a pointer to an ElementTemplateNode. More...

static DGNPLATFORM_EXPORT ElementTemplateNodePtr	CreateNode (WCharCP name, ElementTemplateNodePtr &parentNode, bool allowChildNodes, int sortPriority, XDataTreeOwner &owner, XInstanceContainer *seedContainer=NULL)
	Create and return a pointer to an ElementTemplateNode. More...

static DGNPLATFORM_EXPORT ElementTemplateNodePtr	FromXDataTreeNodePtr (XDataTreeNodeP xDataTreeNode)
	Return a pointer to an ElementTemplateNode given a pointer to an XDataTreeNode. More...

static DGNPLATFORM_EXPORT HandlerId	GetNodeHandlerId ()
	Return the HandlerId used to designate an element as an ElementTemplate Node. More...

Static Public Member Functions inherited from XDataTreeNode
static DGNPLATFORM_EXPORT XDataTreeNodePtr	FindByElementId (DgnPlatform::ElementId elemID, DgnPlatform::HandlerId handlerId, XDataTreeOwner &owner)
	Return a reference counted pointer to an XDataTreeNode. More...

static DGNPLATFORM_EXPORT XDataTreeNodePtr	Create (WStringR name, int sortPriority, bool allowChildNodes, XDataTreeNodeP parentNodeP, XDataTreeOwner &owner, DgnPlatform::HandlerId handlerId, XInstanceContainer *seedInstances)
	Create and return a new XDataTreeNode. More...

Additional Inherited Members
Protected Member Functions inherited from RefCounted< IRefCounted >
virtual	~RefCounted ()

Protected Member Functions inherited from IRefCounted
virtual	~IRefCounted ()

void *	operator new (size_t size)

void	operator delete (void *rawMemory, size_t size)

Detailed Description

Element templates define symbology properties.

Element templates are contained in template groups. Template groups are arranged in a hierarchy, where one group may contain another template group. Both the groups and templates are stored in DGN or DGNLib files. A template can be used by MicroStation to set the active symbology setting, they can be reference by elements so the symbology defined in the template is applied to an element. Templates can also be used by Standard Checker to validate element symbology. The ElementTemplateNode is the in-memory object used to store the Element Template groups and its containing templates in a hierarchical tree structure in memory. The in-memory representation of the tree structure is called an XDataTree.

Creating a new Element Template

A new element template may be created by:

supplying a full path to the template to create using the method ElementTemplateUtils::CreateByPath.
calling the method ElementTemplateNode::CreateNode passing in the parentId of the containing group. Once the ElementTemplateNode is created then an ECN::IECInstancePtr is created to hold the default symbology properties. A The default symbology properties are used by MicroStation. Other applications can also add application specific properties in a different IECInstance.

// create the template by path
ElementTemplateNodePtr   elementTemplate = nullptr;
if (ETSTATUS_Success != ElementTemplateUtils::CreateByPath (elementTemplate, L"TestGroup\\Default", dgnFile))
    return;
ECN::IECInstancePtr etPropertyInstance = elementTemplate->GetOrCreateDefaultInstance ();
if (etPropertyInstance.IsNull())
    return;
 
int lineWeight = 2;         
UInt32 elementColor = 5;
// set template properties
ElementTemplateParamsHelper::AddLevelByName (etPropertyInstance, L"Piping");
ElementTemplateParamsHelper::AddLineStyleById (etPropertyInstance, 0, dgnFile);
ElementTemplateParamsHelper::AddLineWeight (etPropertyInstance, lineWeight);
ElementTemplateParamsHelper::AddElementColor (etPropertyInstance, elementColor, dgnFile);
ElementTemplateUtils::WriteTemplateNode (*elementTemplate);

To create a template using ElementTemplateNode::CreateNode a parent group must first be located and then the new template inserted in that group. Once the template (ElementTemplateNodePtr) is created the adding of the properties IECInstance is done as in the above example.

ElementTemplateNodePtr   elementTemplate = nullptr;
XDataTreeOwner* owner = XDataTreeManager::GetDgnXDataTreeOwner (dgnFile);
ElementTemplateNodePtr parentGroup = ElementTemplateUtils::FindTemplateNodeByPath (L"TestGroup", dgnFile);
if (parentGroup.IsValid())
    elementTemplate = ElementTemplateNode::CreateNode(L"Default", parentGroup->GetId(), false, -1, owner, nullptr);

Reading an Element Template

The steps to read element property data are:

locate the element template
retrieve the IECInstance holding the default symbology data
use ElementTemplateParamsHelper methods to get property values.
ElementTemplateNodePtr elementTemplate = ElementTemplateUtils::FindTemplateNodeByPath (L"TestGroup\\Default", dgnFile);

if (elementTemplate.IsNull())

return;

ECN::IECInstancePtr etPropertyInstance = elementTemplate->GetDefaultInstance ();

if (etPropertyInstance.IsNull())

return;

WString levelName;

if (ETSTATUS_Success != ElementTemplateParamsHelper::GetLevelName (levelName, etPropertyInstance))

return;

Updating an Element Template

The steps to update element property data are:

locate the element template
retrieve the IECInstance holding the default symbology data
use ElementTemplateParamsHelper methods to update property values.
write the changed data.
ElementTemplateNodePtr elementTemplate = ElementTemplateUtils::FindTemplateNodeByPath (L"TestGroup\\Default", dgnFile);

if (elementTemplate.IsNull())

return;

ECN::IECInstancePtr etPropertyInstance = elementTemplate->GetDefaultInstance ();

if (etPropertyInstance.IsNull())

return;

// update template properties

ElementTemplateParamsHelper::SetLevelByName (etPropertyInstance, L"Road-Centerline");

ElementTemplateParamsHelper::SetLineStyleById (etPropertyInstance, 5, dgnFile);

// write the changes

ElementTemplateUtils::WriteTemplateNode (*elementTemplate);

Deleting an Element Template

The steps to update an element template are:

locate the element template
delete the template.
ElementTemplateNodePtr elementTemplate = ElementTemplateUtils::FindTemplateNodeByPath (L"TestGroup\\Default", dgnFile);

if (elementTemplate.IsValid())

ElementTemplateUtils::DeleteTemplateNode (*elementTemplate);

Associating an Element Template with an element

The steps to associate an element template with an element are:

locate the element template
schedule the attachment of the element template reference.
write the element so the scheduled changes are saved to the file.
EditElementHandle lineEeh = CreateLineElement (...not shown...);

ElementTemplateNodePtr elementTemplate = ElementTemplateUtils::FindTemplateNodeByPath (L"TestGroup\\Default", dgnFile);

if (elementTemplate.IsValid())

ElementTemplateUtils::ScheduleTemplateReferenceAttachment (lineEeh, *elementTemplate);

lineEeh.AddToModel()

Determing the Element Template associate with an element

Given an element the associated element template can be returned as:

a WString containing the path of the element template.
a refcounted ElementTemplateNodePtr
WString actualTemplatePath;

if (ETSTATUS_Success != ElementTemplateUtils::GetPathForReferencedTemplate (actualTemplatePath, lineEeh.GetElementRef()))

return;

ElementTemplateNodePtr elementTemplate = ElementTemplateUtils::GetReferencedTemplate (lineEeh.GetElementRef());

if (elementTemplate.IsNull())

return;

ElementTemplateNode is a Refcounted native interface class used to access Element Template data. An ElementTemplateNode is derived from XDataTreeNode and is cached in XDataTrees. If an ElementTemplateNode's allowChildNodes property is set to true, the node is considered a Element Template Group otherwise it is considered an Element Template that holds one or more IECInstance that define its properties.
Remarks
Required library : DgnPlatform<ApiNumber>.lib i.e. DgnPlatform5.lib

Member Function Documentation

static DGNPLATFORM_EXPORT ElementTemplateNodePtr CreateNode	(	WCharCP	name,
		ElementId	parentId,
		bool	allowChildNodes,
		int	sortPriority,
		XDataTreeOwner &	owner,
		XInstanceContainer *	seedContainer = `NULL`
	)

static

Create and return a pointer to an ElementTemplateNode.

Parameters

[in]	name	The name of the Element Template or Element Template Group being created.
[in]	parentId	The ElementId of the parent Template Group. If the Template Group is a root level node then the parentId should be set to 0.
[in]	allowChildNodes	If true the node is considered a Template Group that holds Element Template nodes. A Template Group does not hold any symbology parameters.
[in]	sortPriority	The sort priority determines the order the template nodes are shown in the user interface.
[in]	owner	Owner of the XDataTree which is to contains the ElementTemplateNode.
[in]	seedContainer	Optional container of IECInstance data containing Element Template data.

static DGNPLATFORM_EXPORT ElementTemplateNodePtr CreateNode	(	WCharCP	name,
		ElementTemplateNodeP	parentNode,
		bool	allowChildNodes,
		int	sortPriority,
		XDataTreeOwner &	owner,
		XInstanceContainer *	seedContainer = `NULL`
	)

static

Create and return a pointer to an ElementTemplateNode.

Parameters

[in]	name	The name of the Element Template or Element Template Group being created.
[in]	parentNode	Pointer to the Parent Template Group. If the Template Group is a root level node then NULL should be passed in.
[in]	allowChildNodes	If true the node is considered a Template Group that holds Element Template nodes. A Template Group does not hold any symbology parameters.
[in]	sortPriority	The sort priority determines the order the template nodes are shown in the user interface.
[in]	owner	Owner of the XDataTree which is to contains the ElementTemplateNode.
[in]	seedContainer	Optional container of IECInstance data containing Element Template data.

static DGNPLATFORM_EXPORT ElementTemplateNodePtr CreateNode	(	WCharCP	name,
		ElementTemplateNodePtr &	parentNode,
		bool	allowChildNodes,
		int	sortPriority,
		XDataTreeOwner &	owner,
		XInstanceContainer *	seedContainer = `NULL`
	)

static

Create and return a pointer to an ElementTemplateNode.

Parameters

[in]	name	The name of the Element Template or Element Template Group being created.
[in]	parentNode	Pointer to the Parent Template Group. If the Template Group is a root level node then an ElementTemplateNodePtr set to NULL should be passed in.
[in]	allowChildNodes	If true the node is considered a Template Group that holds Element Template nodes. A Template Group does not hold any symbology parameters.
[in]	sortPriority	The sort priority determines the order the template nodes are shown in the user interface.
[in]	owner	Owner of the XDataTree which is to contains the ElementTemplateNode.
[in]	seedContainer	Optional container of IECInstance data containing Element Template data.L

static DGNPLATFORM_EXPORT ElementTemplateNodePtr FindByElementId	(	ElementId	elemID,
		XDataTreeOwner &	owner
	)

static

Return a pointer to an ElementTemplateNode for an existing element.

Parameters

[in]	elemID	The ElementId of the Type 66 element that holds the element template XAttribute data.
[in]	owner	The owner of the node. The owner can be determined by the DgnFileP. See XDataTreeManager::GetDgnXDataTreeOwner.

static DGNPLATFORM_EXPORT ElementTemplateNodePtr FromXDataTreeNodePtr ( XDataTreeNodeP xDataTreeNode )

static

Return a pointer to an ElementTemplateNode given a pointer to an XDataTreeNode.

If the XDataTreeNode is not for an Element Template a NULL pointer in returned.

Parameters

[in] xDataTreeNode The XDataTreeNode that is potentially an Element Template node.

DGNPLATFORM_EXPORT ECN::IECInstancePtr GetDefaultInstance ( ) const

Return the "default" IECInstance used to store symbology paraemeters in Element Templates.

It is possible for an element template to hold instance data for other applications. The default instance holds the symbology parameters used by MicroStation and its derivatives.

static DGNPLATFORM_EXPORT HandlerId GetNodeHandlerId ( )

static

Return the HandlerId used to designate an element as an ElementTemplate Node.

DGNPLATFORM_EXPORT ECN::IECInstancePtr GetOrCreateDefaultInstance ( )

Return the "default" IECInstance used to store symbology paraemeters in Element Templates.

It is possible for an element template to hold instance data for other applications. The default instance holds the symbology parameters used by MicroStation and its derivatives. This method with create an instance so it can be populated if one does not exist.

The documentation for this struct was generated from the following file:

ElementTemplateNode.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Creating a new Element Template

Reading an Element Template

Updating an Element Template

Deleting an Element Template

Associating an Element Template with an element

Determing the Element Template associate with an element

Member Function Documentation