  |
GoFiler Legato Script Reference
Legato v 1.5b Application v 5.24b
|
| Table of Contents | < < Previous | Next >> |
Chapter Seventeen — Application Integration Functions (continued)
A ‘hook’ allows a script to be inserted into the menu function process. Every menu/ribbon function within the application can be hooked at the function dispatcher. At the most basic level, a hook can be attached for the ‘preprocess’ and the ‘postprocess’. Depending on the function, there may be addition hook positions.
In addition to menu hooks, certain views may have function events. These operate in a similar manner but are covered in the specific section of the manual related to the event.
Functions are dispatched from the ribbon/menu or as commanded by a script. They are processed and exit normally or on error. An error can be a normal condition such as a user pressing ‘Cancel’ on a dialog, a requested exit or an actual error. Flow is as follows:
The first part of the process is to determine what view (or windows) the request was initiated from. The applicability of the function is not relevant at the juncture and if a window is not available (for example, an empty application desktop), then there is no requested source. The source is later used to direct the function to request the appropriate view. For example, a request to center text could go to a Text View, Data View or Page View. In addition, any parameters are setup and stored in a global location for later access by the Application Function Library.
The request is then logged in the application log. Permissions are checked with the UAC (User Account Control) and, if not allowed, an error is generated and the dispatch aborted. The actual view class is then retrieved.
If a script hook has been registered for the specific function, the script processor is called in “preprocess” mode. The servicing script hook can request an exit by returning ERROR_EXIT to stop any further processing of the function. Otherwise processing continues normally. The script’s last error code is returned up the caller chain eventually to the menu or calling function (such as RunMenuFunction). As such, programmers should set the last error with the SetLastError function to ensure the correct values are being returned.
The Collaboration Manager has the opportunity to present notifications or block functions if certain user-defined tasks have not been completed.
A preprocessor can be run if installed and can also force the dispatch to end.
Finally, the ribbon/menu function is dispatched to the base application (ie., FILE_OPEN), global static functions (ie., EDGAR_CHECK_MAIL_MESSAGES) or to a specific view. Certain application functions can also call the script hook processor depending on the nature of their operation. Upon complete, the error state is checked and the dispatch flow exits as directed. Error conditions may disable any repeat options to do not call the script post processor.
On error from the dispatch, the hook is called with “error: 0xEEEEEEEE” where EEEEEEEE is the error code in hex.
The Script Postprocessor is run with the mode “postprocess”.
The Collaboration Manager has the opportunity to present notifications with respect to completed functions such as an email on completion of filing.
The dispatcher then exits and returns to the caller such as the Windows dispatcher or a calling script.
Certain maintenance functions are also passed through the dispatcher such as ribbon checks. These are not subject to script hook processing.
17.6.2 Initialization and Persistence
When a hook is executed the serving script will be loaded as required. The script will remain in memory until the application is closed or the actual script file changes. In addition, the hook script must have a ‘main’ entry point which is executed the first time the hook is executed prior to executing the hook. This allows the script to setup connections and other handles as required.
If a script’s file modified time changes between calls, the current script will be released, errors will be cleared and the revised script is loaded. This includes running the ‘main’ entry point again.
Generally, hooks are established during the application startup. During development, the hook can be defined in the IDE and then tested.
The MenuSetHook function is used to define a hook. Calling the function repeatedly during testing is not an issue. The MenuIsHooked and MenuGetHook functions can be used to determine if a function has already been hooked.
To delete a hook, the MenuDeleteHook function removes the hook from the menu managers’ internal tables.
Runtime errors are logged in the application log.
When a hook is called, a mode string is passed as part of the hook parameters. There are three basic hook modes:
‘preprocess’ — This hook is called prior to dispatching the function. If the User Permission Level (UPL) within the application forbids the execution of the function, the preprocess will not be called. It does not matter if there is an edit active window or if the function is associated with any specific view. It is up to the script to make a determination as to or not to process the request. If the script desires to terminate the function, it returns ERROR_EXIT (0x89000000). Any other value and the dispatcher will continue. Note that the menu state may prohibit certain functions from being invoked by the user.
‘postprocess’ — This hook is called after the function has completed execution. If a function has been defined by a script (does not matter which script program), this call is never made. The return value is not relevant.
‘postprocess error: 0x00000000’ — If the function called ends in an error, the post process is called with this mode. This allows a hook to perform cleanup and other actions to wind down a function hook.
All application defined functions will be called with a different mode and are defined for the specific application.
17.6.5 Adjusting Menu Function Parameters
When a menu function is hooked, menu parameters can be added using the GetMenuFunctionParameters and SetMenuFunctionParameters functions. This allows the preprocess code to alter how a function operates. In addition, the results can be altered using the SetMenuResponseParameter function.
Runtime and load errors are displayed to the user and recorded in the application log.
| Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.