INaturalStudioPlugIn

#### Search Results

Search

# INaturalStudioPlugIn

This document covers the following topics:

- Purpose

- Methods

- Notifications

## 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`.

## Methods

The following methods are available:

- OnActivate

- OnDeactivate

- OnCommand

- OnCommandStatus

- OnNotify

### 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`.

## Notifications

The following notifications are available:

- PLUGIN-NOTIFY-ACTIVATE

- PLUGIN-NOTIFY-QUERYCLOSE

- PLUGIN-NOTIFY-CLOSE

- PLUGIN-NOTIFY-SAVE

- PLUGIN-NOTIFY-EXPANDALL

- PLUGIN-NOTIFY-SELECTEDOBJECTS

- PLUGIN-NOTIFY-FOCUSOBJECT

- PLUGIN-NOTIFY-CONTEXTMENU

- PLUGIN-NOTIFY-REFRESH

- PLUGIN-NOTIFY-HELP

- PLUGIN-NOTIFY-OPTIONSVALIDATE

- PLUGIN-NOTIFY-OPTIONSMODIFIED

### 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`.

### On this page

- Purpose
- Methods
- Notifications