Edit

Invoking handlers from menus, toolbars, and other places

You can install a handler in the Command menu using the InstallMenuCommand function. You would normally do this from your script's Load handler. The command will be uninstalled automatically when the script is unloaded (or you can do so explicitly by calling the InstallMenuCommand function again with an empty handler name).

You can install a handler in the Transaction Entry and list windows using the InstallToolbarIcon function. Do this from the Before handler for the window. The icon will be automatically uninstalled prior to another Before (so you should reinstall it for every Before message). This is so that you can easily install a transaction-type-specific toolbar icon. Lists will get a Before every time the toolbar changes (such as for a change of selected view).

Public handlers

To make a handler accessible to reports, forms, the evaluate external command, different scripts, or the entry field expression parser, use the public attribute in the handler declaration.

    on MyHandlerName(myParam) public
        say("This is the public handler " + myParam)
    end

External invocations of the message will need to use its public name, consisting of the script name, a colon, and the handler name (e.g. My_Script:MyHandlerName(x)). If the script is not currently loaded, you won't be able to compile a script that calls it.

Elevating privileges

Scripts normally run with the privileges of the logged-in user. You can have a handler run with admin privileges by adding the elevated attribute to the handler declaration. Note that the extra privilege is dropped when the handler exits, so the operation requiring the privilege will have to be completed in its entirety.

    on MyHandlerName(myParam) elevated
        say("I'm running with admin privileges")
        // hmm what would be useful to do here?
        //   • post without elective posting privilege?
        //   • override the extension field with a discounted value
        //   • replace a value in a selection?
        //   • Clear the hold checkbox with SetFieldValue()?
    end

Uses statement for forward declarations

The compiler will normally only recognise your handlers that have already been defined earlier in your script (or for public handlers in other scripts, which must be currently loaded). In order to include calls to handlers that have not yet been defined, or are in other scripts that are not currently loaded, you can use a uses declaration to declare the name of a handler. It is up to you to make sure the handler is defined/loaded when the calling script code executes, otherwise you will get a runtime error.

This is somewhat like an extern declaration in C, or a forward declaration in Pascal, except no parameter list declaration is required since MWScript does no compile-time parameter checking.

e.g.

uses MyHandlerName
uses OtherScript:PublicHandler

on Foo
    MyHandlerName()    // not yet defined in script
end

on MyHandlerName    // now it is
    OtherScript:PublicHandler() // might not be loaded at compile time
end