LiquidToolbar™ Plugin/Hook API Reference

Notes This is the plugin API reference guide for the LiquidToolbar™. Please refer to the source code included with the sample plugins for further implementation details.

Contains TclBridge™ technology by Joseph Mistachkin. Copyright © 1999-2008 by Joseph Mistachkin. All rights reserved. Used with permission.

Plugin Interface Requirements The following methods must be defined in all plugins:

Declaration
Public Function About(ByVal plToolbarId As Long, ByRef psStatus As String) As Long
Name About
Description This method must modify the psStatus argument to contain the name and version of the plugin. Optionally, an about box containing plugin version information may be displayed.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.
Output Argument psStatus, which must contain either the name and version of the plugin or an error message describing the reason the plugin name and version cannot be obtained.
Returns Must return non-zero for success, zero on failure.
Notes It is highly recommended for the plugin to display a dialog box containing the plugin name and version when this method is called. The information returned in argument psStatus is primarily for use by Tcl scripts, whereas the dialog box presents this information to the end-user.

Declaration
Public Function Configure(ByVal plToolbarId As Long, ByRef psStatus As String) As Long
Name Configure
Description This method must show an interface allowing the user to configure options for the plugin, if any.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.
Output Argument psStatus, which must contain an appropriate error message if this method fails.
Returns Must return non-zero for success, zero on failure.
Notes None.

Declaration
Public Function Initialize(ByVal plToolbarId As Long, ByVal psFileName As String, ByVal psProgID As String, ByVal psCLSID As String, ByVal psArguments As String, ByRef psStatus As String) As Long
Name Initialize
Description This method is called after the plugin is created by the plugin manager. Any initialization steps that do not involve TclBridge should be done here. This method must be capable of being called even if the plugin has already been initialized. If this method fails, either by returning "False" or by raising an error, the plugin is immediately destroyed without calling the Terminate method.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument psFileName, the file name containing this plugin or an empty string if the file name is unknown.

Argument psProgID, the COM progID of this plugin.

Argument psCLSID, the COM CLSID of this plugin.

Argument psArguments, the arguments to this plugin, if any.
Output Argument psStatus, which must contain an appropriate error message if this method fails.
Returns Must return non-zero for success, zero on failure.
Notes None.

Declaration
Public Function CreateCommands(ByVal plToolbarId As Long, ByVal poObj As Object, ByVal plInterpreter As Long, ByRef psStatus As String) As Long
Name CreateCommands
Description This method is normally called after the Initialize method has been called by the plugin manager. Any initialization steps that involve the plugin manager or TclBridge should be done here. This method must be capable of being called even if the plugin has already been initialized. If this method fails, either by returning "False" or by raising an error, the plugin is immediately destroyed without calling the DeleteCommands method.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument poObj, the plugin manager that created this plugin. A reference to this object should be saved by the plugin for later use. If this argument is "Nothing", this method can choose to ignore it or return an error. Please see the clsToolbar object for more information.

Argument plInterpreter, the Tcl interpreter that the plugin should create commands in. This interpreter should be saved by the plugin for later use. If this argument is zero, this method can choose to ignore it or return an error.
Output Argument psStatus, which must contain an appropriate error message if this method fails.
Returns Must return non-zero for success, zero on failure.
Notes None.

Declaration
Public Function DeleteCommands(ByVal plToolbarId As Long, ByVal poObj As Object, ByVal plInterpreter As Long, ByRef psStatus As String) As Long
Name DeleteCommands
Description This method is normally called before the Terminate method is called by the plugin manager. Any termination steps that involve the plugin manager or TclBridge should be done here. This method must be capable of being called even if the plugin has already been terminated. If this method fails, either by returning "False" or by raising an error, the plugin will not be terminated.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument poObj, the plugin manager that created this plugin. Any saved references to this object or other plugin manager objects must be freed before returning from this method. If this argument is "Nothing", this method can choose to ignore it or return an error. Please see the clsToolbar object for more information.

Argument plInterpreter, the Tcl interpreter that the plugin should delete commands from. If this argument is zero, this method can choose to ignore it or return an error.
Output Argument psStatus, which must contain an appropriate error message if this method fails.
Returns Must return non-zero for success, zero on failure.
Notes None.

Declaration
Public Function Terminate(ByVal plToolbarId As Long, ByVal psFileName As String, ByVal psProgID As String, ByVal psCLSID As String, ByVal psArguments As String, ByRef psStatus As String) As Long
Name Terminate
Description This method is called before the plugin is destroyed by the plugin manager. Any termination steps that do not involve TclBridge should be done here. This method must be capable of being called even if the plugin has already been terminated. If this method fails, either by returning "False" or by raising an error, the plugin will not be terminated.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument psFileName, the file name containing this plugin or an empty string if the file name is unknown.

Argument psProgID, the COM progID of this plugin.

Argument psCLSID, the COM CLSID of this plugin.

Argument psArguments, the arguments to this plugin, if any.
Output Argument psStatus, which must contain an appropriate error message if this method fails.
Returns Must return non-zero for success, zero on failure.
Notes None.

Layout Plugin Interface Requirements The following methods must be defined in all layout plugins:

Declaration
Public Function GetThemes(ByVal plToolbarId As Long, ByRef psStatus As String) As Long
Name About
Description None.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.
Output None.
Returns Must return non-zero for success, zero on failure.
Notes None.

Declaration
Public Function LayoutToolbar(ByVal plToolbarId As Long, ByRef psStatus As String) As Long
Name Configure
Description None.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.
Output Argument psStatus, which must contain an appropriate error message if this method fails.
Returns Must return non-zero for success, zero on failure.
Notes None.

Class 'clsToolbar' Methods The following methods are provided to interface with the plugin manager:

Declaration
Public Function About(ByRef psStatus As String) As Long
Name About
Description This method modifies the psStatus argument to contain the name and version of the plugin manager.
Input None.
Output Argument psStatus, which contains either the name and version of the plugin manager or an error message describing the reason the plugin manager name and version cannot be obtained.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function GetSecureLevel(ByVal plToolbarId As Long, ByVal plClientData As Long, ByRef plSecureLevel As Long, ByRef psStatus As String) As Long
Name GetSecureLevel
Description This method modifies the plSecureLevel argument to contain the current security level of the plugin manager.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument plClientData, this is reserved for future use and must be zero.
Output Argument plSecureLevel, which will be updated to contain the current security level of the plugin manager.

Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function GetBridgeObject() As Object
Name GetBridgeObject
Description This method returns the primary TclBridge object in use by the plugin manager, if any. Plugins should use this object to interface with TclBridge. This method will return "Nothing" if the primary TclBridge object is unavailable.
Input None.
Output None.
Returns See above.
Notes None.

Declaration
Public Function GetInterpreter() As Long
Name GetInterpreter
Description This method returns the primary Tcl interpreter in use by the plugin manager. Plugins should use this interpreter to interface with Tcl/Tk. This method will return "TCLB_INVALID_INTERPRETER" if the primary Tcl interpreter is unavailable.
Input None.
Output None.
Returns See above.
Notes None.

Declaration
Public Function SetInterpreter(ByVal plInterpreter As Long, ByVal plClientData As Long, ByRef psStatus As String) As Long
Name SetInterpreter
Description This method sets the primary Tcl interpreter for the plugin manager.
Input Argument plInterpreter, this should be the new primary Tcl interpreter or zero.

Argument plClientData, this is reserved for future use and must be zero.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes Use of this method by plugins is not recommended because it may prevent proper operation of the toolbar if used incorrectly.

Declaration
Public Function GetSafeInterpreter() As Long
Name GetSafeInterpreter
Description This method returns the primary "safe" Tcl interpreter in use by the plugin manager. This method will return "TCLB_INVALID_INTERPRETER" if the primary "safe" Tcl interpreter is unavailable.
Input None.
Output None.
Returns See above.
Notes None.

Declaration
Public Function SetSafeInterpreter(ByVal plInterpreter As Long, ByVal plClientData As Long, ByRef psStatus As String) As Long
Name SetSafeInterpreter
Description This method sets the primary "safe" Tcl interpreter for the plugin manager.
Input Argument plInterpreter, this should be the new primary "safe" Tcl interpreter or zero.

Argument plClientData, this is reserved for future use and must be zero.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes Use of this method by plugins is not recommended because it may prevent proper operation of the toolbar if used incorrectly.

Declaration
Public Function HandleToolbarCommand(ByVal plToolbarId As Long, ByVal plClientData As Long, ByVal poObj As Object, ByVal plInterpreter As Long, ByRef psCommand() As String, ByVal plFlags As Long, ByVal piAsynchronous As Integer, ByVal piTokens As Integer, ByVal piHistory As Integer, ByRef psStatus As String) As Long
Name HandleToolbarCommand
Description This method is the low-level external entry point into the toolbar command processor.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument plClientData, this is reserved for future use and must be zero.

Argument poObj, the TclBridge object to use.

Argument plInterpreter, the Tcl interpreter to use.

Argument psCommand, the array containing the name and arguments for the command to be handled. For a list of available commands, please refer to the online command reference by typing "#help" in the application.

Argument plFlags, which can contain one or more values from the "Command Flags" table.

Argument piAsynchronous, which indicates whether or not the command should be evaluated asynchronously, whenever possible.

Argument piTokens, which indicates whether or not pre-processing of tokens is performed prior to evaluating Tcl scripts.

Argument piHistory, which indicates whether or not the command should be added to the command history.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns A standard Tcl result, normally one of:
  • TCL_OK
  • TCL_ERROR
  • TCL_RETURN
  • TCL_BREAK
  • TCL_CONTINUE
Notes None.

Declaration
Public Function ExecuteCommand(ByVal plInterpreter As Long, ByVal plClientData As Long, ByRef psCommand() As String) As Long
Name ExecuteCommand
Description This method is the high-level external entry point into the toolbar command processor. It is the interface used by TclBridge to facilitate communication with Tcl.
Input Argument plInterpreter, the Tcl interpreter to use.

Argument plClientData, the Tcl "clientData" used when this command was created with CreateCommand method of the TclBridge object. All other callers of this method should pass zero for this argument.

Argument psCommand, the array containing the name and arguments for the command to be handled. For a list of available commands, please refer to the online command reference by typing "#help" in the application.
Output None.
Returns A standard Tcl result, normally one of:
  • TCL_OK
  • TCL_ERROR
  • TCL_RETURN
  • TCL_BREAK
  • TCL_CONTINUE
Notes This method modifies the result of the specified Tcl interpreter.

Declaration
Public Function AddHook(ByVal plToolbarId As Long, ByRef plId As Long, ByVal psName As String, ByVal psFlags As String, ByVal poObj As Object, ByVal psMethod As String, ByVal plCallType As VbCallType, ByVal pvArguments As Variant, ByVal plClientData As Long, ByRef psStatus As String) As Long
Name AddHook
Description This method creates a new plugin hook and adds it to the plugin manager's list of hooks. The plugin hook will call the object method specified by the poObj and psMethod arguments when any events matching the psFlags argument are encountered.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument psName, the descriptive name for the new plugin hook.

Argument psFlags, which should contain one or more values from the "Hook Types" table.

Argument poObj, the object for the new plugin hook to invoke.

Argument psMethod, the method for the new plugin hook to invoke.

Argument plCallType, the COM call type for the method specified by the psMethod argument.

Argument pvArguments, the array of arguments to pass to the method specified by the psMethod argument. May contain values from the "Hook Meta Arguments" table.

Argument plClientData, this is reserved for future use and must be zero.
Output Argument plId, upon successul completion of this method, this argument will contain the Id for the new plugin hook object.

Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function RemoveHook(ByVal plToolbarId As Long, ByVal plId As Long, ByVal plClientData As Long, ByRef psStatus As String) As Long
Name RemoveHook
Description This method removes an existing plugin hook from the plugin manager's list of hooks and then destroys it.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument plId, the Id of the plugin hook to remove and destroy. If the value "-1" is used, all plugin hooks will be removed and destroyed.

Argument plClientData, this is reserved for future use and must be zero.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function InvokingHooks(ByVal plClientData As Long, Optional ByRef psStatus As String) As Integer
Name InvokingHooks
Description This method can be used to determine if the plugin manager is currently invoking hooks.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument plClientData, this is reserved for future use and must be zero.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero if plugin hooks are currently being invoked by the plugin manager or zero if an error occurs.
Notes None.

Declaration
Public Function CountHooks(ByVal plToolbarId As Long, ByVal psFlags As String, ByVal plClientData As Long, ByRef psStatus As String) As Long
Name CountHooks
Description This method can be used to determine the number of plugin hooks currently registered with the plugin manager.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument psFlags, which should contain one or more values from the "Hook Types" table. Only plugin hooks matching these flags will be counted.

Argument plClientData, this is reserved for future use and must be zero.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns The number of hooks currently registered with the plugin manager or the value "-1" if an error occurs.
Notes None.

Declaration
Public Function FindHook(ByVal plToolbarId As Long, ByVal plId As Long, ByVal plClientData As Long, ByRef psStatus As String) As Long
Name FindHook
Description This method can be used to determine the index of the specified plugin hook.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument plId, the Id of the plugin hook to find.

Argument plClientData, this is reserved for future use and must be zero.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns The index of the plugin hook or the value "-1" if the plugin hook cannot be found or an error occurs.
Notes None.

Declaration
Public Function EnableHook(ByVal plToolbarId As Long, ByVal plId As Long, ByVal plClientData As Long, ByVal piEnable As Integer, ByRef psStatus As String) As Long
Name EnableHook
Description This method can be used to enable or disable the specified plugin hook.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument plId, the Id of the plugin hook to enable or disable.

Argument plClientData, this is reserved for future use and must be zero.

Argument piEnable, which should be non-zero to indicate "enabled" or zero to indicate "disabled".
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function GetHook(ByVal plToolbarId As Long, ByVal plId As Long, ByVal plClientData As Long, ByRef poHook As Object, ByRef psStatus As String) As Long
Name GetHook
Description This method can be used to fetch the specified plugin hook.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument plId, the Id of the plugin hook to fetch.

Argument plClientData, this is reserved for future use and must be zero.
Output Argument poHook, this will contain the specified plugin hook object or "Nothing" after this method returns.

Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function ListHooks(ByVal plToolbarId As Long, ByVal plId() As Long, ByVal plClientData As Long, ByRef psStatus As String) As Long
Name ListHooks
Description This method can be used to obtain a list of all the plugin hook objects currently registered with the plugin manager.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument plClientData, this is reserved for future use and must be zero.
Output Argument plId, this will contain the Id array for the list of plugin hooks or an empty array.

Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function InvokeHooks(ByVal plToolbarId As Long, ByVal plId As Long, ByVal psFlags As String, ByVal plClientData As Long, ByRef psData() As String, ByRef psName() As String, ByRef psValue() As String, ByRef plHookId As Long, ByRef piContinue As Integer, ByRef psStatus As String) As Long
Name InvokeHooks
Description This method invokes zero or more plugin hooks matching the specified criteria.
Input Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument plId, the Id of the plugin hook to invoke. If the value "-1" is used, all plugin hooks with flags matching argument psFlags will be invoked.

Argument psFlags, which should contain one or more values from the "Hook Types" table. Only plugin hooks matching these flags will be invoked.

Argument plClientData, this is reserved for future use and must be zero.

Argument psData, the data array, if any, associated with this event. This argument is also used for output. This argument may be changed by one or more plugin hooks prior to this method returning.

Argument psName, the names array, if any, associated with this event. This argument is also used for output. This argument may be changed by one or more plugin hooks prior to this method returning.

Argument psValue, the values array, if any, associated with this event. This argument is also used for output. This argument may be changed by one or more plugin hooks prior to this method returning.

Argument piContinue, the continue flag associated with this event. This argument is also used for output. This argument should initially be set to "True". If, after this method returns, the variable passed in for this argument is "False" then the plugin hook identified by the plHookId argument caused further processing of this event to be halted.
Output Argument psData, the data array, if any, associated with this event. This argument is also used for input. This argument may be changed by one or more plugin hooks prior to this method returning.

Argument psName, the names array, if any, associated with this event. This argument is also used for input. This argument may be changed by one or more plugin hooks prior to this method returning.

Argument psValue, the values array, if any, associated with this event. This argument is also used for input. This argument may be changed by one or more plugin hooks prior to this method returning.

Argument plHookId, the Id for the last plugin hook, if any, that changed the psData argument, the piContinue argument, the psStatus argument, or any combination of these arguments.

Argument piContinue, the continue flag associated with this event. This argument is also used for input. This argument should initially be set to "True". If, after this method returns, the variable passed in for this argument is "False" then the plugin hook identified by the plHookId argument caused further processing of this event to be halted.

Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes Use of this method by plugins is not recommended because it could lead to unwanted recursion.

Declaration
Public Function GetBridgeAndInterpreter(ByRef poObj As Object, ByRef plInterpreter As Long, ByVal plFlags As Long, ByRef psStatus As String) As Long
Name GetBridgeAndInterpreter
Description This method fetches the primary TclBridge object and primary Tcl interpreter.
Input Argument plFlags, this is reserved for future use and must be zero.
Output Argument poObj, this will contain the primary TclBridge object or "Nothing" after this method returns.

Argument plInterpreter, this will contain the primary Tcl interpreter or zero after this method returns.

Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function SetBridgeAndInterpreter(ByVal poObj As Object, ByVal plInterpreter As Long, ByVal plFlags As Long, ByRef psStatus As String) As Long
Name SetBridgeAndInterpreter
Description This method sets the primary TclBridge object and primary Tcl interpreter.
Input Argument poObj, this should be the new primary TclBridge object or "Nothing".

Argument plInterpreter, this should be the new primary Tcl interpreter or zero.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes Use of this method by plugins is not recommended because it may prevent proper operation of the toolbar if used incorrectly.

Declaration
Public Function CheckApplicationCommands(ByVal plFlags As Long, ByVal piExist As Integer, ByRef psStatus As String) As Long
Name CheckApplicationCommands
Description This method checks for the specified Tcl commands in the primary Tcl interpreter via the primary TclBridge object.
Input Argument plFlags, which can contain one or more values from the "Command Flags" table. This argument is used to determine which commands to check for.

Argument piExist, which is the value to return if the specified commands exist. If the specified commands do not exist, the value of this argument is logically negated prior to being returned.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes Use of this method by plugins is not recommended because it may prevent proper operation of the toolbar if used incorrectly.

Declaration
Public Function AddApplicationCommands(ByVal plFlags As Long, ByRef psStatus As String) As Long
Name AddApplicationCommands
Description This method adds the specified Tcl commands to the primary Tcl interpreter via the primary TclBridge object.
Input Argument plFlags, which can contain one or more values from the "Command Flags" table. This argument is used to determine which commands to add.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes Use of this method by plugins is not recommended because it may prevent proper operation of the toolbar if used incorrectly.

Declaration
Public Function RemoveApplicationCommands(ByVal plFlags As Long, ByRef psStatus As String) As Long
Name RemoveApplicationCommands
Description This method removes the specified Tcl commands from the primary Tcl interpreter via the primary TclBridge object.
Input Argument plFlags, which can contain one or more values from the "Command Flags" table. This argument is used to determine which commands to remove.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes Use of this method by plugins is not recommended because it may prevent proper operation of the toolbar if used incorrectly.

Declaration
Public Property ToolbarId(ByVal plClientData As Long, ByVal plToolbarId As Long) As Long
Name ToolbarId
Description This property contains the Id of the toolbar that owns this instance of the plugin manager (read/write).
Input Argument plClientData, this is reserved for future use and must be zero.

Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.
Output None.
Returns The Id of the toolbar that owns this instance of the plugin manager.
Notes Modification of this property by plugins is not recommended because it may prevent proper operation of the toolbar if used incorrectly.

Class 'clsHook' Methods The following methods are provided to interface with hook objects:

Declaration
Public Function Initialize(ByVal psName As String, ByVal psFlags As String, ByVal plToolbarId As Long, ByVal poObj As Object, ByVal psMethod As String, ByVal plCallType As VbCallType, ByVal pvArguments As Variant, ByRef psStatus As String) As Long
Name Initialize
Description This method is used to initialize the plugin hook. Please see the AddHook method of the clsToolbar object for more information.
Input Argument psName, the descriptive name for the new plugin hook.

Argument psFlags, which should contain one or more values from the "Hook Types" table.

Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument poObj, the object for the new plugin hook to invoke.

Argument psMethod, the method for the new plugin hook to invoke.

Argument plCallType, the COM call type for the method specified by the psMethod argument.

Argument pvArguments, the array of arguments to pass to the method specified by the psMethod argument. May contain values from the "Hook Meta Arguments" table.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes This method is used by the plugin manager during the AddHook method.

Declaration
Public Function Invoke(ByVal psFlags As String, ByRef psData() As String, ByRef psName() As String, ByRef psValue() As String, ByRef plHookId As Long, ByRef piContinue As Integer, ByRef psStatus As String) As Long
Name Invoke
Description This method is used to invoke the plugin hook. However, calling this method does not guarantee that the contained method will be called. Please see the InvokeHooks method of the clsToolbar object for more information.
Input Argument psFlags, which should contain one or more values from the "Hook Types" table. The contained method will only be invoked if the contained flags match these flags.

Argument psData, the data array, if any, associated with this event. This argument is also used for output.

Argument psName, the names array, if any, associated with this event. This argument is also used for output.

Argument psValue, the values array, if any, associated with this event. This argument is also used for output.

Argument piContinue, the continue flag associated with this event. This argument is also used for output. If, after this method returns, the variable passed in for this argument is "False" then this plugin hook wants further processing of this event to be halted.
Output Argument psData, the data array, if any, associated with this event. This argument is also used for input.

Argument psName, the names array, if any, associated with this event. This argument is also used for input.

Argument psValue, the values array, if any, associated with this event. This argument is also used for input.

Argument plHookId, which will be updated to contain the Id of this hook if the psData argument, the piContinue argument, the psStatus argument, or any combination of these arguments are modified.

Argument piContinue, the continue flag associated with this event. This argument is also used for input. If, after this method returns, the variable passed in for this argument is "False" then this plugin hook wants further processing of this event to be halted.

Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes This method is used by the plugin manager during the InvokeHooks method.

Declaration
Public Function Terminate(ByRef psStatus As String) As Long
Name Terminate
Description This method is used to terminate the plugin hook. Please see the RemoveHook method of the clsToolbar object for more information.
Input None.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes This method is used by the plugin manager during the RemoveHook method.

Class 'clsHook' Properties
These properties represent various aspects of how the plugin hook will be handled. They are initially set via the Initialize method and cannot be modified later.
Name Type Attributes Description
Initialized Boolean read-only Returns non-zero if the plugin hook has been initialized.
Enabled Boolean read-only Returns non-zero if the plugin hook is enabled (disabled plugin hooks cannot be invoked).
Id Long Integer read-only Returns the unique Id for this plugin hook.
Name String read-only Returns the plugin supplied descriptive name for this plugin hook.
Flags String read-only Returns the flags for this plugin hook.
Object Object read-only Returns the object to be invoked by this plugin hook.
Method String read-only Returns the method to be invoked by this plugin hook.
CallType VbCallType read-only Returns the call type to be invoked by this plugin hook. Will be one of the following: vbMethod, vbGet, vbLet, or vbSet.
Arguments Variant read-only Returns the arguments that will be used for the next invocation of this plugin hook.
Result Variant read-only Returns the result from the last invocation of this plugin hook.

Class 'clsAlias' Methods The following methods are provided to interface with alias objects:

Declaration
Public Function Initialize(ByVal psName As String, ByVal psFlags As String, ByVal plToolbarId As Long, ByRef psScript() As String, ByRef psStatus As String) As Long
Name Initialize
Description This method is used to initialize the command alias.
Input Argument psName, the descriptive name for the new command alias.

Argument psFlags, which may contain one or more alphanumeric flag values to be matched against the psFlags argument passed to the Invoke method.

Argument plToolbarId, which is Id of the toolbar that owns this instance of the plugin manager.

Argument psScript, the array of command strings to evaluate when the new command alias is invoked.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function Invoke(ByVal psFlags As String, ByRef psArguments() As String, ByVal poObj As Object, ByVal plFlags As Long, ByVal piInteractive As Integer, ByVal piAsynchronous As Integer, ByVal piTokens As Integer, ByVal piHistory As Integer, ByRef psStatus As String) As Long
Name Invoke
Description This method is used to invoke the command alias. However, calling this method does not guarantee that the contained command strings will be evaluated.
Input Argument psFlags, which may contain one or more alphanumeric flag values to be matched against the contained flags. The contained command strings will only be evaluated if the contained flags match these flags.

Argument psArguments, the arguments, if any, to be substituted into each command string prior to evaluation.

Argument poObj, the command console, if any, associated with this command alias invocation.

Argument plFlags, which can contain one or more values from the "Command Flags" table.

Argument piAsynchronous, which indicates whether or not the command should be evaluated asynchronously, whenever possible.

Argument piTokens, which indicates whether or not pre-processing of tokens is performed prior to evaluating Tcl scripts.

Argument piHistory, which indicates whether or not the command should be added to the command history.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function Terminate(ByRef psStatus As String) As Long
Name Terminate
Description This method is used to terminate the command alias.
Input None.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function Import(ByVal psLine As String, ByRef psStatus As String) As Long
Name Import
Description This method is used to import a well-formed command alias string.
Input Argument psLine, the well-formed command alias string to be imported. Please refer to the provided "aliases.tcl" file for examples of the format.
Output Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Declaration
Public Function Export(ByRef psLine As String, ByRef psStatus As String) As Long
Name Export
Description This method is used to export a well-formed command alias string.
Input None.
Output Argument psLine, the well-formed command alias string to be exported. Please refer to the provided "aliases.tcl" file for examples of the format.

Argument psStatus, which contains either the output of the command or an error message describing the reason why the command failed.
Returns Non-zero for success, zero on failure.
Notes None.

Class 'clsAlias' Properties
These properties represent various aspects of how the command alias will be handled. They are initially set via the Initialize method and cannot be modified later.
Name Type Attributes Description
Initialized Boolean read-only Returns non-zero if the command alias has been initialized.
Enabled Boolean read-only Returns non-zero if the command alias is enabled (disabled command aliases cannot be invoked).
Id Long Integer read-only Returns the unique Id for this command alias.
Name String read-only Returns the plugin supplied descriptive name for this command alias.
Flags String read-only Returns the flags for this command alias.
Script Variant read-only Returns the script associated with this command alias as an array of command strings.
ToolbarId Long read-only Returns the Id of the toolbar that owns this command alias.
Wired Boolean read-only Returns non-zero if the command alias has been "wired" to a command in the primary Tcl interpreter.
Result Variant read-only Returns the result from the last invocation of this command alias.

Command Flags
These constants are used in conjunction with the HandleToolbarCommand, CheckApplicationCommands, AddApplicationCommands, and RemoveApplicationCommands methods of the clsToolbar object in the plFlags argument.
Name Description
TCLB_F_NONE This value represents default command handling.
TCLB_F_CUSTOM This value indicates that application specific commands have been added into the interpreter or that it should be assumed that they have been added into the interpreter. When used with the AddApplicationCommands or RemoveApplicationCommands methods, it indicates this set of commands needs to be added or removed.
TCLB_F_COM This value indicates that TCL2COM commands have been added into the interpreter or that it should be assumed that they have been added into the interpreter. When used with the AddApplicationCommands or RemoveApplicationCommands methods, it indicates this set of commands needs to be added or removed.
TCLB_F_VBS This value indicates that TCL2VBS commands have been added into the interpreter or that it should be assumed that they have been added into the interpreter. When used with the AddApplicationCommands or RemoveApplicationCommands methods, it indicates this set of commands needs to be added or removed.
TCLB_F_ONLY This value indicates that RemoveApplicationCommands should not perform any cleanup other than removing commands from the primary Tcl interpreter.
TCLB_F_FORCE This value indicates that RemoveApplicationCommands should fail if it cannot remove application specific commands. This situation would normally arise if the commands were locked while in use.
TCLB_F_DIRECT This value indicates that, whenever possible, application specific commands should be handled without going through TclBridge.
TCLB_F_VALID This value indicates that all Tcl commands are considered to be valid and that they should not be checked for validity.

Security Levels
These constants are used in conjunction with the GetSecureLevel method of the clsToolbar object in the plSecureLevel argument.
Name Description
TOOLBAR_SECURITY_INVALID This value represents an invalid security level. This value should always be interpreted as an error.
TOOLBAR_SECURITY_DEFAULT This value represents the default security level. This normally means that the security level has not been explicitly configured by the user.
TOOLBAR_SECURITY_AUTOMATIC This value is reserved for future use and should not be used.
TOOLBAR_SECURITY_NONE By default, at this security level, no functionality is disabled. This behavior may be changed based on user preferences.
TOOLBAR_SECURITY_MINIMUM By default, at this security level, all functionality that requires direct access to the primary TclBridge object and primary Tcl interpreter is forbidden. If the plugin previously had access to the primary TclBridge object or primary Tcl interpreter, it should discard any references to them; this guideline may be strictly enforced in the future. This behavior may be changed based on user preferences.
TOOLBAR_SECURITY_LOW By default, at this security level, all functionality that requires indirect access to the primary Tcl interpreter is forbidden. This behavior may be changed based on user preferences.
TOOLBAR_SECURITY_MEDIUM_LOW By default, at this security level, no additional functionality is specifically disabled. This behavior may be changed based on user preferences.
TOOLBAR_SECURITY_MEDIUM By default, at this security level, all command invocation and hook management related functionality is disabled. This behavior may be changed based on user preferences.
TOOLBAR_SECURITY_MEDIUM_HIGH By default, at this security level, all functionality that could result in potentially unwanted information disclosure is disabled. This behavior may be changed based on user preferences.
TOOLBAR_SECURITY_HIGH By default, at this security level, almost all functionality is disabled. This behavior may be changed based on user preferences.
TOOLBAR_SECURITY_MAXIMUM By default, at this security level, all functionality is disabled. This behavior may be changed based on user preferences.

Security Adjustment Levels
These constants are used internally by the plugin manager to dynamically adjust the security level of trusted and untrusted plugins. They are listed here for informational purposes only.
Name Description
TOOLBAR_SECURITY_ADJUST_NONE This value indicates that no adjustment is made to the security level.
TOOLBAR_SECURITY_ADJUST_TRUSTED This value indicates the security level adjustment multiplier for trusted plugins.
TOOLBAR_SECURITY_ADJUST_UNTRUSTED This value indicates the security level adjustment multiplier for untrusted plugins.
TOOLBAR_SECURITY_ADJUST_MAXIMUM This value represents the maximum possible security level adjustment.

Hook Types
These constants are used in conjunction with the AddHook method of the clsToolbar object in the psFlags argument. They are also used in conjunction with the Initialize method of the clsHook object in the psFlags argument. In addition, strings containing these constants may be returned from the Flags property of the clsHook object.
Name Description
TOOLBAR_HOOK_FLAG_COMMAND This type of plugin hook is called when an internal toolbar command (any command starting with "con_toolbar") is about to be processed. The data for this type of plugin hook is the command string about to be processed.
TOOLBAR_HOOK_FLAG_EXECUTE This type of plugin hook is called when an external application or shortcut is about to be executed. The data for this type of plugin hook is the command string about to be executed.
TOOLBAR_HOOK_FLAG_INPUT This type of plugin hook is reserved for future use.
TOOLBAR_HOOK_FLAG_OUTPUT This type of plugin hook is called when output is about to be displayed to the user, either via the status window or a message box. The data for this type of plugin hook is the output about to be displayed.
TOOLBAR_HOOK_FLAG_TRIGGER This type of plugin hook is called when the user is about to trigger a toolbar command. The data for this type of plugin hook is the command Id about to be triggered.
TOOLBAR_HOOK_FLAG_SCRIPT This type of plugin hook is called when a Tcl script is about to be evaluated by the toolbar. The data for this type of plugin hook is the Tcl script about to be evaluated.
TOOLBAR_HOOK_FLAG_LOAD This type of plugin hook is called when a toolbar related file is about to be loaded from disk. The data for this type of plugin hook is the name of the resource to be loaded.
TOOLBAR_HOOK_FLAG_SAVE This type of plugin hook is called when a toolbar related file is about to be saved to disk. The data for this type of plugin hook contains the name/value pairs to save and the name of the resource to save them to.
TOOLBAR_HOOK_FLAG_DYNAMIC_ARGUMENTS This indicates that the plugin hook is dynamic. The internal plugin hook arguments are updated after each successful invocation.

Hook Meta Arguments
These constants are used in conjunction with the AddHook method of the clsToolbar object in the pvArguments array of arguments. They are also used in conjunction with the Initialize method of the clsHook object in the pvArguments array of arguments. In addition, strings containing these constants may be returned from the Arguments property of the clsHook object.
Name Description
HOOK_CONTINUE This meta argument is a "ByRef Boolean" during plugin hook invocations. Changes to this argument will be reflected in subsequent plugin hooks. If this argument is set to "False" by a plugin hook, all further processing of the current event is halted.
HOOK_DATA This meta argument is a "ByRef String" array during plugin hook invocations. Changes to this argument will be reflected in subsequent plugin hooks. After all matching plugin hooks have been invoked, the final values of the "data" will be used for the default processing of the event, if any.
HOOK_NAME This meta argument is a "ByRef String" array during plugin hook invocations. Changes to this argument will be reflected in subsequent plugin hooks. After all matching plugin hooks have been invoked, the final values of the "names" will be used for the default processing of the event, if any.
HOOK_VALUE This meta argument is a "ByRef String" array during plugin hook invocations. Changes to this argument will be reflected in subsequent plugin hooks. After all matching plugin hooks have been invoked, the final values of the "values" will be used for the default processing of the event, if any.
HOOK_STATUS This meta argument is a "ByRef String" during plugin hook invocations. Changes to this argument will be reflected in subsequent plugin hooks. If "False" is returned from the plugin hook, presumably due to a failure of some kind, this value will be interpreted as the reason for the error. Otherwise, if the HOOK_CONTINUE meta argument is set to "False", this value will be interpreted as the reason for halting further processing.
HOOK_OBJECT This meta argument is a "ByVal Object" during plugin hook invocations. This is the object that was responsible for invoking the plugin hook. All the properties of this object may be queried for their values. Please see the above table "Class 'clsHook' Properties" for more detailed information about the properties of the clsHook object.