This document covers the following topics:
A plug-in provides this interface in order to provide information about tree view and list view nodes to Natural Studio. Natural Studio calls the methods of this interface if the plug-in has defined its own node types and has opened a tree view or list view document window with a node of one of these types as root node. Natural Studio calls the methods to gather information about these nodes whenever this is required to expand or refresh a tree view or list view.
Note:
A plug-in defines its own node types by using the interface
INatAutoNodeTypes
.
In order to provide the interface, plug-ins written in Natural include
the interface module (copycode) NSTPLG-T
from the example library
SYSEXPLG
in their class definition. Plug-ins written in other
languages use the type library naturalstudioplugin.tlb
. This type
library is also contained in the example library SYSEXPLG
.
The following methods are available:
Natural Studio calls this method to retrieve additional information about a plug-in defined node identified by type and key.
Name | Natural Data Format | Variant Type | Remark |
---|---|---|---|
ReturnValue | L | VT_BOOL | |
Type | I4 | VT_I4 | |
Key | A | VT_BSTR | |
Info | A | VT_BSTR | |
Template | I4 | VT_I4 | |
Data | A | VT_BSTR | By reference |
- ReturnValue
The plug-in returns TRUE if it knows the node, FALSE otherwise.
- Type
The type of the node.
- Key
The key that identifies the node within its type.
- Info
An additional information string that the plug-in has previously assigned to the node.
- Template
The TemplateID that the plug-in has passed to the method
INatAutoObjectTrees::Open
orINatAutoObjectLists::Open
when opening the tree view or list view document window.- Data
The plug-in returns a string containing an XML document that describes the node. The XML document is structured according to the following DTD.
<?xml version="1.0"?> <!ELEMENT data (pinfo?, pname?, (ntype, nkey)?)> <!ELEMENT pinfo (#PCDATA)> <!ELEMENT pname (#PCDATA)> <!ELEMENT ntype (#PCDATA)> <!ELEMENT nkey (#PCDATA)>
Element Meaning pinfo Additional information about the node that the plug-in wants to receive back whenever Natural Studio later refers to the node. Natural Studio never considers the content of this element, but just passes it back and forth. pname The text to be displayed with the node in a tree view or list view. ntype If the node has been defined by a plug-in, but corresponds to an node of a predefined Natural Studio type, this element contains the type of the corresponding predefined node. nkey If the node has been defined by a plug-in, but corresponds to an node of a predefined Natural node type, this element contains the key of the corresponding predefined node.
Natural Studio calls this method to retrieve the child nodes of a node defined by a plug-in. This node is identified by type and key.
Name | Natural Data Format | Variant Type | Remark |
---|---|---|---|
ReturnValue | I4 | VT_I4 | |
Type | I4 | VT_I4 | |
Key | A | VT_BSTR | |
Info | A | VT_BSTR | |
Template | I4 | VT_I4 | |
Children | A | VT_BSTR | By reference |
- ReturnValue
Indicates the number of child nodes.
- Type
The type of the node.
- Key
The key that identifies the node within its type.
- Info
An additional information string that the plug-in has previously assigned to the node.
- Template
The TemplateID that the plug-in has passed to the method
INatAutoObjectTrees::Open
orINatAutoObjectLists::Open
when opening the tree view or list view document window. The plug-in can interpret the parameterTemplate
to return different tree structures for different values ofTemplate
.- Children
The plug-in returns a string containing an XML document that describes the child nodes. The XML document is structured according to the following DTD.
<?xml version="1.0"?> <!ELEMENT children (child*)> <!ELEMENT child (ptype, pkey, pinfo?, pname?, phch?, children?, (ntype, nkey)?)> <!ELEMENT ptype (#PCDATA)> <!ELEMENT pkey (#PCDATA)> <!ELEMENT pinfo (#PCDATA)> <!ELEMENT pname (#PCDATA)> <!ELEMENT phch (#PCDATA)> <!ELEMENT ntype (#PCDATA)> <!ELEMENT nkey (#PCDATA)>
Element Meaning ptype The type of the child node. pkey The key that identifies the child node within its type. pinfo Additional information about the child node that the plug-in wants to receive back whenever Natural Studio later refers to the node. Natural Studio never considers the content of this element, but just passes it back and forth. pname The text to be displayed with the child node in a tree view or list view. children Allows specifying a subtree of child nodes in arbitrary depth. If this element is specified, it is implicitly assumed that the child node itself has children and the method HasChildren
is not called for this child node.phch Allows specifying in advance if the given child node itself has child nodes.
A value of 1 means that the child node itself has child nodes.
A value of -1 means that the child node itself has no child nodes.
A value of 0 (default) means that the plug-in cannot determine now if the child node itself has child nodes and wants to be asked in a subsequent call to the method
HasChildren
.ntype If the node has been defined by a plug-in, but corresponds to a node of a predefined Natural Studio type, this element contains the type of the corresponding predefined node. nkey If the node has been defined by a plug-in, but corresponds to a node of a predefined Natural node type, this element contains the key of the corresponding predefined node.
Natural Studio calls this method to check if the plug-in defined node identified by type and key has child nodes of any type. This is used to decide if the node will be shown as expandable in a tree view document window.
Name | Natural Data Format | Variant Type | Remark |
---|---|---|---|
ReturnValue | L | VT_BOOL | |
Type | I4 | VT_I4 | |
Key | A | VT_BSTR | |
Info | A | VT_BSTR | |
Template | I4 | VT_I4 | |
Children | A | VT_BSTR | By reference |
- ReturnValue
The plug-in returns TRUE if the node has child nodes, FALSE otherwise.
- Type
The type of the node.
- Key
The key that identifies the node within its type.
- Info
An additional information string that the plug-in has previously assigned to the node.
- Template
The TemplateID that the plug-in has passed to the method
INatAutoObjectTrees::Open
orINatAutoObjectLists::Open
when opening the tree view or list view document window. The plug-in can interpret the parameterTemplate
to return different tree structures for different values ofTemplate
.- Children
If the plug-in not only knows that the given node has child nodes, but knows also the child nodes themselves, it can return them in this parameter. The plug-in then returns a string containing an XML document that describes the child nodes. The XML document is structured according to the DTD defined with the method
GetChildren
.
Natural Studio calls this method to retrieve meta information about the attributes of the given node type. This method is called when the attributes of the node are to be displayed in a list view document window.
Name | Natural Data Format | Variant Type | Remark |
---|---|---|---|
ReturnValue | I4 | VT_I4 | |
Type | I4 | VT_I4 | |
Template | I4 | VT_I4 | |
Attributes | A | VT_BSTR | By reference |
- ReturnValue
The number of defined attributes.
- Type
The type of the node.
- Template
The TemplateID that the plug-in has passed to the method
INatAutoObjectTrees::Open
orINatAutoObjectLists::Open
when opening the tree view or list view document window. The plug-in can interpret the parameterTemplate
to return different attribute sets for different values ofTemplate
.- Attributes
The plug-in returns a string containing an XML document that describes the attributes. The XML document is structured according to the following DTD.
<?xml version="1.0"?> <!ELEMENT attributes (attdef*)> <!ELEMENT attdef (akey, acaption?)> <!ELEMENT akey (#PCDATA)> <!ELEMENT acaption (#PCDATA)>
Element Meaning akey A key that identifies the attribute internally. This key is freely defined by the plug-in. acaption A caption that is used to display the attribute externally, for instance, in list view column headers. For nodes that correspond to predefined Natural Studio node types the attributes of the corresponding Natural node type can also be specified. In order to refer to these attributes, the following predefined attribute keys are used. If one of these attribute keys is used, no attribute caption needs to be specified, because the captions are predefined by Natural Studio.
Key Caption NOLibrary Library name NOFnr File number NODBID Database number NOType Natural object type NOMode Mode (Structured/Report) NOUserID User ID NOSrcDate Date of last save NOSrcSize Source size NOCatDate Date of last catalog NOCatSize GP size
Natural Studio calls this method to retrieve the attribute values of the node defined by a plug-in. This node is identified by type and key.
Name | Natural Data Format | Variant Type | Remark |
---|---|---|---|
ReturnValue | I4 | VT_I4 | |
Type | I4 | VT_I4 | |
Key | A | VT_BSTR | |
Info | A | VT_BSTR | |
Template | I4 | VT_I4 | |
AttributeValues | A | VT_BSTR | By reference |
- ReturnValue
The number of attribute values.
- Type
The type of the node.
- Key
The key that identifies the node within its type.
- Info
An additional information string that the plug-in has previously assigned to the node.
- Template
The TemplateID that the plug-in has passed to the method
INatAutoObjectTrees::Open
orINatAutoObjectLists::Open
when opening the tree view or list view document window. The plug-in can interpret the parameterTemplate
to return different attribute sets for different values ofTemplate
.- AttributeValues
The plug-in returns a string containing an XML document that describes the attribute values. The XML document is structured according to the following DTD.
<?xml version="1.0"?> <!ELEMENT attributevalues (attval*)> <!ELEMENT attval (akey, avalue)> <!ELEMENT akey (#PCDATA)> <!ELEMENT avalue (#PCDATA)>
Element Meaning akey A key that identifies the attribute internally. The key must match one of the keys previously returned in a call to GetAttributes
, otherwise the element is ignored.avalue The attribute value.