  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Seventeen — Application Integration Functions (continued)
Overview
The MenuSetHook function sets a top-level hook for a menu function. The hook is attached to the main menu/ribbon function processing and allows for a minimum of a preprocess hook and additional hooks if supported.
Syntax/Parameters
Syntax
int = MenuSetHook ( int id | string code, [string script, string function] );
Parameters
id
An int that specifies the function ID as returned to the script from various menu functions. This id code can be dynamic, thus programmers should not use fixed values for functions. When id is supplied, code cannot be used.
code
A string containing the specific code for a function (for example, “EDGAR_SUBMIT_TEST”). When code is supplied, id cannot be used.
script
A string containing the filename and path name of the script servicing the menu hook. If script is empty or not supplied, it is implied that any existing hook will be deleted. When deleting, function should also be empty.
function
A string specifying the name of the function servicing the menu hook. If script is not supplied, function should also not be supplied.
Return Value
Returns an int as ERROR_NONE or a formatted error code on failure.
Remarks
The id or code value must be defined prior to setting the hook. See MenuAddFunction to add custom functions. The MenuSetHook function can also delete a hook if the script and function names are empty or not provided as parameters.
Once a script is hooked, any script runtime error (or load error) will result in the hook being disabled. The hook manager will reload the script and try again if the date/time stamp on the file changes. This can aid in debugging. Programmers should always run the hook code in the IDE to check for obvious syntax and naming errors.
There can be only one hook attached to a function id/code. To replace an existing hook, the first hook must be deleted either by calling with no script and function parameters or using the MenuDeleteHook function.
The Hook Code
When the hook is executed, the function is called with two parameters in the following form:
int function (int id, string mode) { ... }
Where:
function
The function parameter specified above when setting the hook. The function can serve more than one hook.
id
An int that specifies the function ID of the function that called the hook. If the hook is attached to a single function, this parameter can be ignored. Otherwise it gives the option of having a hook support multiple menu functions. For example, one hook might support all hooked clipboard functions.
mode
A string specifying the context with which the hook was called. All menu hooks will receive a “preprocess” context where the script receives control prior to the menu function being dispatched. Most menu functions will also pass a “postprocess” context after the function completes. Script defined menu functions do not produce a postprocess context because they are by definition not dispatched within the application. Depending on the menu function, other hook contexts may be used.
The function should return an int containing a formatted error code. The value will depend on the mode the function is processing. For example, if the value ERROR_EXIT is returned during the “preprocess” mode, it will stop any further processing (the application’s menu dispatcher will not be run). Any other value and the processing will continue. Semantically, returning ERROR_NONE would indicate that the function should continue. (It is also possible at some point in the future that an error could be logged into the application error log.)
Example:
int run(int f_id, string mode) {
if (mode != "preprocess") {
return ERROR_NONE;
}
. . . perform hook processing . . .
return ERROR_EXIT;
}
If the supporting hook function fails to run, check the spelling. By default, if the hook manager cannot find the specific hook function, it will run the script default entry point (for example, main()).
Related Functions
Platform Support
Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL
Legato IDE
| 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.