Version 6.3.8 for Windows
 —  Extending Natural Studio with Plug-ins  —

INaturalStudioPlugIn

This document covers the following topics:


Purpose

This is the primary interface a plug-in must provide. Natural Studio uses this interface to activate and deactivate the plug-in and to send commands and notifications to it.

In order to provide the interface, plug-ins written in Natural include the interface module (copycode) NSTPLG-I 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.

Top of page

Methods

The following methods are available:

OnActivate

Natural Studio calls this method when it activates the plug-in. The plug-in should use this opportunity to define its commands and to make them visible in the Natural Studio user interface. Also it might store a handle to the Natural Studio Automation root interface (INatAutoStudio) for further use.

If a plug-in determines that it cannot activate because certain resources or prerequisites are missing, it should set *ERROR-NR to 9002 on return. This causes the plug-in framework to call the method OnDeactivate for the necessary cleanup and to leave the plug-in in inactive status. The plug-in itself is responsible to alert the user in an appropriate way.

Parameters

Name Natural Data Format Variant Type Remark
NaturalStudio HANDLE OF OBJECT VT_DISPATCH (INatAutoStudio)  
NaturalStudio

Contains a handle to the Natural Studio Automation root interface.

OnDeactivate

Natural Studio calls this method when it deactivates the plug-in. The plug-in should use this opportunity to close windows, files and network connections etc. and to clean up other used resources. It does not need to remove the commands, menu items and toolbar items that is might have created in the method OnActivate. This is done by Natural Studio automatically.

Parameters

Name Natural Data Format Variant Type Remark
NaturalStudio HANDLE OF OBJECT VT_DISPATCH (INatAutoStudio)  
NaturalStudio

Contains a handle to the Natural Studio Automation root interface.

OnCommand

Natural Studio calls this method when the user selects one of the commands the plug-in has defined. Usually the plug-in will then apply the command to the set of objects that are currently selected. It retrieves this set through the interface INatAutoSelectedObjects.

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

Natural Studio calls this method when one of the commands the plug-in has defined becomes visible in the user interface, for instance, when the user opens a pop-up menu that contains one of these commands. The plug-in decides if the command is to be enabled or not and if it is to have a check mark or not. By default, all plug-in defined commands are disabled and unchecked. Usually the plug-in will decide about the command status based on the set of objects that are currently selected. It retrieves this set through the interface INatAutoSelectedObjects.

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 to be enabled, the plug-in returns TRUE in this parameter.

Checked

If the command is to have a check mark, the plug-in returns TRUE in this parameter.

OnNotify

Natural Studio calls this method to notify the plug-in about certain events in Natural Studio that might be of interest for the plug-in. However, the plug-in does not have to use any of these notifications.

Parameters

Name Natural Data Format Variant Type Remark
Return value I4 VT_I4  
Notification I4 VT_I4  
LongParam I4 VT_I4 By reference
ObjectParam HANDLE OF OBJECT VT_DISPATCH By reference
StringParam A VT_BSTR By reference
Return value, LongParam, ObjectParam, StringParam

The usage and meaning of these parameters depends on the specific notification. Please refer to the specification of the individual notifications in the following.

Notification

A number that identifies the notification. The individual notifications are specified in the following. There are constant definitions available for the notification numbers in the local data area NSTPLG-L in the example library SYSEXPLG.

Top of page

Notifications

The following notifications are available:

PLUGIN-NOTIFY-ACTIVATE

Natural Studio sends this notification to plug-ins that have created tree view document windows, list view document windows or generic document windows. It sends it to inform the plug-in about the activation status of one of these windows.

Return value

Not used.

LongParam
0 if the window is being deactivated.
1 if the window is being activated.
2 if the window is already active and the user clicks a mouse button inside the window.
ObjectParam

A handle to the document window.

StringParam

A string that identifies the type of document window: INatAutoObjectTree, INatAutoObjectList or INatAutoGenericDocument.

PLUGIN-NOTIFY-QUERYCLOSE

Natural Studio sends this notification to plug-ins that created generic document windows. It sends it to inform the plug-in that the Natural Studio user is attempting to close one of these windows, or that the Close method has been called. The plug-in might use this notification to check if there are uncommitted changes in the document and to take appropriate actions if this is the case.

Return value

The plug-in returns:

0 if it accepts that the window is closed.
1 to prevent closing the window.
LongParam

Not used.

ObjectParam

A handle to the document window.

StringParam

A string that identifies the type of document window: INatAutoGenericDocument.

PLUGIN-NOTIFY-CLOSE

Natural Studio sends this notification to plug-ins that created tree view document windows, list view document windows or generic document windows. It sends it to inform the plug-in that the Natural Studio user is attempting to close one of these windows, or that the Close method has been called.

Return value

Not used.

LongParam

Not used.

ObjectParam

A handle to the document window.

StringParam

A string that identifies the type of document window: INatAutoObjectTree, INatAutoObjectList or INatAutoGenericDocument.

PLUGIN-NOTIFY-SAVE

Natural Studio sends this notification to plug-ins that have opened generic text objects in the program editor. It sends it to inform the plug-in that the user has triggered the Save command. This enables the plug-in to retrieve the edited text and to save it.

Return value

The plug-in returns:

1 to indicate that it has successfully saved the text.
0 otherwise.
LongParam

Not used.

ObjectParam

A handle to the document window.

StringParam

A string that identifies the type of document window: INatAutoGenericText.

PLUGIN-NOTIFY-EXPANDALL

Natural Studio sends this notification to plug-ins that have created tree view document windows. It sends it to inform the plug-in that an Expand All has been started or has finished on one of these windows. This enables the plug-in to apply possible optimizations when Natural Studio later calls it repetitively while performing the Expand All.

Note:
The user issues an Expand All by pressing the Multiply key on the numeric keypad while a tree view node is selected. This causes the tree view node to be expanded recursively.

Return value

Not used.

LongParam
1 if Expand All has started.
0 if Expand All has finished.
ObjectParam

A handle to the document window.

StringParam

A string that identifies the type of document window: INatAutoObjectTree.

PLUGIN-NOTIFY-SELECTEDOBJECTS

Natural Studio sends this notification to plug-ins that have created generic document windows. It sends it to retrieve the currently selected objects in the currently active generic document window.

Return value

Not used.

LongParam

Not used.

ObjectParam

Not used.

StringParam

The plug-in returns the set of selected objects formatted as an XML document. The document must comply to the DTD specified for the property SelectedObjects of the interface INatAutoSelectedObjects.

PLUGIN-NOTIFY-FOCUSOBJECT

Natural Studio sends this notification to plug-ins that have created a generic document window. It sends it to retrieve the object that currently has the focus in the currently active generic document window.

Return value

Not used.

LongParam

Not used.

ObjectParam

Not used.

StringParam

The plug-in returns the focus object formatted as an XML document. The document must comply with the DTD specified for the property SelectedObjects of the interface INatAutoSelectedObjects.

PLUGIN-NOTIFY-CONTEXTMENU

Natural Studio sends this notification to plug-ins that have created generic document windows. It sends it to inform the plug-in that the user tries to open a context menu on one of these windows by clicking the right mouse button or pressing the context menu key. This enables the plug-in to have different context menus displayed depending on the mouse position or to display a default context menu for the window as a whole.

Return value

The plug-in returns:

1 if a context menu is to be displayed.
0 otherwise.
LongParam

The current mouse position in the form x * (2**16) + y.

This means: If the mouse position is for instance, (50,100), the value in LongParam will be 50 * (2**16) + 100 = 3276900. A value of -1 indicates that the default (position independent) context menu was requested.

ObjectParam

The plug-in returns a INatAutoContextMenu interface to a context menu it has created or retrieved before.

StringParam

Not used.

PLUGIN-NOTIFY-REFRESH

Natural Studio sends this notification to plug-ins that have created tree view document windows, list view document windows or generic document windows. It sends it to inform the plug-in that one of these windows possibly needs to be refreshed. While handling this notification, the plug-in has access to the interface INatAutoRefreshObject. This interface and its properties allow retrieving the details about the object currently being refreshed.

Return value

The plug-in returns:

1 if the window is to be refreshed.
0 if it is not to be refreshed.
LongParam
On Input The value 0 indicates that Natural Studio just queries whether a refresh is to be performed. Natural Studio passes this value if the notification is sent with respect to a tree view document window or list view document window. In these cases Natural Studio can perform the refresh itself. The plug-in has just to decide whether it wants the view to be refreshed or not.

The value 1 indicates that Natural Studio advises the plug-in to refresh the window. Natural Studio passes this value if the notification is sent with respect to a generic document window. In this case, the plug-in is in charge of performing the refresh.

On Return The value 0 indicates that the plug-in wants to have this refresh executed as a specific refresh. This means: only the visualizations of the current refresh object (INatAutoRefreshObject) is to be refreshed.

The value 1 indicates that the plug-in wants to have this refresh executed as an unspecific refresh. This means: the whole window is to be refreshed.

Note:
For list view document windows Natural Studio currently makes no difference between a specific and an unspecific refresh. In both cases the whole window will be refreshed.

ObjectParam

A handle to the document window.

StringParam

A string that identifies the type of document window: INatAutoObjectTree, INatAutoObjectList or INatAutoGenericDocument.

PLUGIN-NOTIFY-HELP

Natural Studio sends this notification to plug-ins that have created tree view document windows or list view document windows. It sends it to inform the plug-in that the user has pressed the F1 key (and thus requested help), while one of these windows was active. While handling this notification, the plug-in has access to the interface INatAutoSelectedObjects. This interface and its properties allow retrieving details about the objects currently being selected and about the focus object, in order to display context-specific help. In order to display a specific help topic, the plug-in uses the method INatAutoStudio::ShowHelp.

Return value

The plug-in returns:

1 if it has handled the help request by displaying a help topic.
0 if not.
LongParam

Not used.

ObjectParam

A handle to the document window.

StringParam

A string that identifies the type of document window: INatAutoObjectTree or INatAutoObjectList.

PLUGIN-NOTIFY-OPTIONSVALIDATE

Natural Studio sends this notification to plug-ins that have specified options. It sends it to inform the plug-in that the user is attempting to modify the option values and allows the plug-in to validate the new values. The notification is sent when the user has pressed OK or Apply in the Options dialog or if the user switches to a different property page after having modified the plug-in options.

Note:
A plug-in can specify options by using the method INatAutoPlugIn::DefineOptions. It can retrieve and set the option values by using the property INatAutoPlugIn::OptionValues. The user can modify the option values interactively in the Natural Studio Options dialog.

Return value

The plug-in returns:

1 if the modified option values are valid.
0 if they are invalid.

Additionally it might do whatever necessary to alert the user, for instance, display a message box.

LongParam

Not used.

ObjectParam

Not used.

StringParam

Contains the modified option setting as an XML document according to the Option values DTD. This DTD is defined in INatAutoPlugIn::OptionValues.

PLUGIN-NOTIFY-OPTIONSMODIFIED

Natural Studio sends this notification to plug-ins that have specified options. It sends it to inform the plug-in that the user has successfully modified the option values and allows the plug-in to react to the change appropriately.

Note:
A plug-in can specify options through the method INatAutoPlugIn::DefineOptions. It can retrieve and set the option values through the property INatAutoPlugIn::OptionValues. The user can modify the option values interactively in the Natural Studio Options dialog.

Return value

Not used.

LongParam

Not used.

ObjectParam

Not used.

StringParam

Contains the modified option setting as an XML document according to the Option values DTD. This DTD is defined in INatAutoPlugIn::OptionValues.

Top of page