This document covers the following topics:
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.
The following methods are available:
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.
| 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.
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.
| 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.
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.
| 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
Addof the interfaceINatAutoCommands.
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.
| 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
Addof the interfaceINatAutoCommands.- 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.
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.
| 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-Lin the example librarySYSEXPLG.
The following notifications are available:
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,INatAutoObjectListorINatAutoGenericDocument.
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.
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,INatAutoObjectListorINatAutoGenericDocument.
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.
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.
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
SelectedObjectsof the interfaceINatAutoSelectedObjects.
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.
Not used.
Not used.
Not used.
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.
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
INatAutoContextMenuinterface to a context menu it has created or retrieved before.- StringParam
Not used.
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,INatAutoObjectListorINatAutoGenericDocument.
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:
INatAutoObjectTreeorINatAutoObjectList.
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 or 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.
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.