INatAutoPlugIn

This document covers the following topics:

Purpose

An installed plug-in.

Properties

The following properties are available:

Parent

Used to navigate to the parent interface of this interface.

Natural Data Format Variant Type Remark
HANDLE OF OBJECT VT_DISPATCH (INatAutoPlugIns) Get only

Studio

Used to navigate to the root interface.

Natural Data Format Variant Type Remark
HANDLE OF OBJECT VT_DISPATCH (INatAutoStudio) Get only

ID

The global unique ID by which the plug-in is identified in Natural Studio. It is equal to the ID of the ActiveX component implementing the plug-in.

Natural Data Format Variant Type Remark
A VT_BSTR Get only

Type

The type of the plug-in.

Natural Data Format Variant Type Remark
A VT_BSTR Get only

The possible values are:

Value Meaning
Single server The plug-in runs in its own Natural server process, distinct from all other Natural-written plug-ins.
Shared server The plug-in runs in the same Natural server process as the Plug-in Manager.

Name

The descriptive name of the plug-in that is displayed in the Plug-in Manager.

Natural Data Format Variant Type Remark
A VT_BSTR Get only

CLSID

The CLSID of the ActiveX component implementing the plug-in. For a Natural-written plug-in this is the ID defined in the DEFINE CLASS statement.

Natural Data Format Variant Type Remark
A VT_BSTR Get only

ProgID

The ProgID of the ActiveX component implementing the plug-in. For a Natural-written plug-in this is the class name defined in the DEFINE CLASS statement.

Natural Data Format Variant Type Remark
A VT_BSTR Get only

Active

Indicates if the plug-in is currently active. Modifying this property activates and deactivates the plug-in respectively.

Natural Data Format Variant Type Remark
L VT_BOOL  

Automatic

Indicates if the plug-in is automatically activated when Natural Studio is started, or if it must be manually activated with the Plug-in Manager. Modifying this property changes the activation mode accordingly.

Natural Data Format Variant Type Remark
L VT_BOOL  

OptionValues

A string containing an XML document that describes the current option value setting for this plug-in.

Natural Data Format Variant Type Remark
A VT_BSTR  

The XML document is formatted according to the following DTD.

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT optvals (optval*)>
<!ELEMENT optval (name, value)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT value (#PCDATA)>
Element Meaning
name The name of the option. If this name does not correspond to a name defined in the DefineOptions method, this is a hidden option. This means that the user cannot see and modify the option value in the Options dialog. Otherwise the option is represented in a property page in the Options dialog as specified in the method DefineOptions.
value The option value.

Methods

The following methods are available:

DefineOptions

Defines the options for this plug-in and their layout in a property page in the Options dialog.

Parameters

Name Natural Data Format Variant Type Remark
OptionDefinition A VT_BSTR  
OptionDefinition

A string containing an XML document that describes the options of the plug-in and their layout in a property page in the Options dialog. The XML document is formatted according to the following DTD. 

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT optdef (caption, helpfile?, helptopic?, option*, groupbox*, statictext*)>
<!ELEMENT option (name, (checkbox | edittext | radiobuttons | spinbutton))>
<!ELEMENT checkbox (left, top, title, default)>
<!ELEMENT edittext (left, top, width, height, default)>
<!ELEMENT radiobuttons (radiobutton+, default)>
<!ELEMENT radiobutton (left, top, title, value)>
<!ELEMENT spinbutton (left, top, width, height, min, max, default)>
<!ELEMENT groupbox (title, left, top, width, height)>
<!ELEMENT statictext (title, left, top, width, height)>
<!ELEMENT caption (#PCDATA)>
<!ELEMENT helpfile (#PCDATA)>
<!ELEMENT helptopic (#PCDATA)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT value (#PCDATA)>
<!ELEMENT default (#PCDATA)>
<!ELEMENT left (#PCDATA)>
<!ELEMENT top (#PCDATA)>
<!ELEMENT width (#PCDATA)>
<!ELEMENT height (#PCDATA)>
<!ELEMENT min (#PCDATA)>
<!ELEMENT max (#PCDATA)>
Element Meaning
caption The caption displayed on the property page.
helpfile The full path name to a help file containing help information about the options.
helptopic A help topic to be displayed when the user chooses the Help button on the property page.
name The name of the option. This name is used only internally to refer to the option in the OptionValues DTD.
value The value assigned to a radio button.
default The default value of the option.
term The term displayed with a dialog control.
left, top, width, height The position and size of a dialog control.
min, max The minimum and maximum value displayed in a spinbutton control.

GetCustomInterface

Returns the custom interface of this plug-in, or NULL-HANDLE, if the plug-in does not provide a custom interface.

Plug-ins can provide a custom interface in order to provide services to clients other than Natural Studio itself. These clients can be, for instance, other plug-ins or programs running inside or outside Natural Studio. In order to provide a custom interface, a plug-in must implement an additional interface beside the two predefined interfaces INaturalStudioPlugIn and INaturalStudioPlugInTree and make this interface the default dispatch interface. For a plug-in implemented in Natural this means placing this interface at the first position in the DEFINE CLASS statement.

Parameters

Name Natural Data Format Variant Type Remark
Return value HANDLE OF OBJECT VT_DISPATCH  
Return value

The custom interface of this plug-in.

OnCommand

Sends a specific command to the plug-in.

Parameters

Name Natural Data Format Variant Type Remark
CommandID I4 VT_I4  
CommandID

Contains the command ID the plug-in has chosen when it defined the command with the method Add of the interface INatAutoCommands.

OnCommandStatus

Checks whether a specific command of the plug-in is currently enabled or checked.

Parameters

Name Natural Data Format Variant Type Remark
CommandID I4 VT_I4  
Enabled L VT_BOOL By reference
Checked L VT_BOOL By reference
CommandID

Contains the command ID the plug-in has chosen when it defined the command with the method Add of the interface INatAutoCommands.

Enabled

If the command is currently enabled, the method returns TRUE in this parameter.

Checked

If the command currently has a check mark, the method returns TRUE in this parameter.