What's New In Macros

The Scripting Workbench Automation Library introduces an object oriented architecture which differs substantially from the procedural layout that Image-Pro Plus Auto-Pro was using. Instead of chaining function calls with many parameters, macros now deal with objects which represent the various elements of the software. Objects are self contained, allow to persist the application state in a much more consistent manner and have the ability to expose their characteristics as well as the actions that they support in a very flexible and organized manner. Macros mostly interact with 2 classes of objects: data objects and commands.

Data objects represent the data being processed such as documents (IMcDocument), images (McImage), image sets (McImageSet) or image features (McRegions). They can also abstract elements of the software like the application object which is the root of the object model (see McApplication often refered to as ThisApplication in macros) or the window objects for instance (McWindow).

On the other hand, command objects represent the actions that can be performed on data objects. Commands expose properties used to specify their behavior, inputs and outputs (see Input for instance) which point to data objects, and methods used to control their execution (Run(InputType, OutputType) for example).

Unlike in Image-Pro Plus, Scripting Workbench macros are primarly edited using a graphical macro designer which makes the process of creating and configuring automation scripts much easier. The designer allows you to construct macros using drag & drop in addition to recording, as well as to adjust macro parameters interactively instead of having to do it all in code.

Of course the macro code is still accessible and can be edited directly as well, however this dual editing capability comes with a few requirements to maintain designer compatibility. Here are a few hints regarding this new environment.

• In order to create its graphical macro representation, the designer runs macros in a special mode where commands are processed to build a script (SimpleScript). This preprocessing happens whenever a project is loaded.

• Since the macro can run for designer support purpose, breakpoints inserted in macro code can be hit during that step as well.

• In order to maintain compatibility with the designer, macro customization has to be done carefully and follow the syntax explained in the following section.

• For maximum flexibility, code commands (CodeCommand) are provided, which allow the macro writer to insert any code in a macro. These commands are available in the Toolbox as well as in code snippets.

• Ultimately, when designer support is not required it is also possible to write plain macros which have full access to the Scripting Workbench Automation Library including the lower level IQL objects. This approach is often used when building Apps.

As explained in the previous paragraph, designer friendly macros impose a few rules when it comes to manual editing. One such rule is that the designer has to be able to generate the code based on its own interpretation of the macro. Since the designer would otherwise have no knowledge of the code added manually, it has the ability to detect such code at parsing time using the following rules.

• Any comment after the script creation (New) and before the first With starts the script user code region.

• Any comment after the With beginning a command starts a user code region which ends at the .Run statement.

Function MyScript() As SimpleScript 
    MyScript = New SimpleScript
    Dim var1

    ' Beginning User Code
    Dim userVar

    With Application.Document.Open(MyScript)
        .Filenames = {"C:\image.tif"}

        ' Beginning User Code
        .UserProperty = True

        .Run(list)
    End With
End Function

Macros created by Scripting Workbench are usually made of sequences of commands where each command represents one step of the process. In the following example, each code block starting with With and ending with End With configures and runs one command, while the beginning of the macro declaration includes the creation of the macro object itself (New SimpleScript) followed by the declaration of the variables which will be used to store the command inputs and outputs, thus driving the data flow.

Public Function ExampleMacro() As SimpleScript
    ExampleMacro = New SimpleScript
    Dim docList1 = New List(1), doc1

    With Application.DocumentCommands.Open(ExampleMacro)
        .Filenames = New String() {ThisApplication.Path(mcPathType.mcptSampleImages) & "Count and Size\SPOTS.TIF"}
        .Run(docList1)
    End With

    With Application.DocumentCommands.Activate(ExampleMacro)
        .Run(docList1(0), doc1)
    End With

    With Process.Filter.EnhancementCommands.Sharpen(ExampleMacro)
        .Passes = 1
        .KernelSize = Filters.mcKernelSize.mcks3x3
        .Strength = 100
        .Run(doc1, doc1)
    End With

End Function

Basic macros or plain macros are simple subroutines or functions that implement custom code without allowing editing using the code designer. As such they do not need to follow the syntax of "SimpleScript" macros and can implement any construct supported by the Scripting Workbench macro language. They can use commands (simply by passing Nothing instead of the SimpleScript instance) and can access any of the low level IQL objects described in the next section, such as ThisApplication and all of its properties such as ActiveImage, ActiveWindow or ActiveDocument.

Public Sub LowLevelMacro

    Dim docList1

    With Application.DocumentCommands.Open(Nothing)
        .Filenames = New String() {ThisApplication.Path(mcPathType.mcptSampleImages) & "Filter\Sharpening\FPRINT2.TIF"}
        .Run(docList1)
    End With

    Dim image As McImage
    image = docList1(0).Data

    ThisApplication.Output.Show
    ThisApplication.Output.PrintMessage(image.Name & " loaded",True)

End Sub

Scripting Workbench scripting projects are interpreted by default, which means that rather than being compiled into binary code, the macros contained in these projects are interpreted at runtime. This allows for quick prototyping, enables single stepping in macro code and variable inspection, while also maintaining user interface responsiveness. However the syntax of these macros is not guarenteed to be the same as Microsoft's VB.NET.

• Execution is restricted to a single thread.

• Type inference is not supported.

• Anonymous methods are not supported.

• LINQ is not supported.

• XML literal expressions are not supported.

• Methods implemented by modules/macros can't be overloaded.

• Classes implemented by WWB.NET are not true .NET class. (Only COM interfaces are supported.)

• Generic methods calls are not supported. (Generic types are supported.)

• String variables can't be set to Nothing and are never Nothing.

• { array } syntax is only supported for one dimensional arrays.

• < attribute > syntax is allowed, but ignored.

• Preprocessor directives like #if are not supported.

• Array dimensions cannot refer to variables.

On the other hand, when the flexibility of interpreted macros is not required, projects can be changed to a compiled mode which speeds up macro execution very substantially. Compiled mode can be enabled on the Project Properties panel. Although faster, compiled projects have their own limitations.

• No single stepping or variable inspection.

• No user interface refresh during macro execution.

• Multiple versions of a compiled project remain in memory until the end of a session.

• Object model events like those of ThisApplication or ThisProject are not supported.

• Only supports standard Microsoft .NET class libraries, some proprietary scripting APIs are not available (see Language Reference).

Other Resources