JW Freeware Plug-ins Wiki

The PDK Framework documentation is a C++ reference. It's using the C++ syntax, and all types in the documentation are C++ types. That's why I refer to functions within the framework classes as “methods”, which is the C++ terminology.

The detailed C++ syntax is often of no importance to you as a Lua programmer. The only things that are really important are:

• The name of a Lua-supported method/constant and in which class it resides.
• The number of arguments to a Lua-supported method and their general type (mainly a check if the type is boolean, integer or an object).
• The return type of a Lua-supported method.
• The description details of a Lua-supported method/constant.

All top level classes that are available to JW Lua scripts are listed at http://www.finaletips.nu/frameworkref/group__lua__classes.html

If a method requires an object as a parameter, you need to create it. This might be specially important to note for the FCString class, which is the main class which the PDK Framework uses for string access (the FCString class objects is only compatible with Lua strings through some of its methods and properties).

Please note that the PDK Framework is object-oriented, so if you don't find a task in the class you're searching, try to look in the parent classes.

For example: if you want to load all the measures of a document, it's easy to think that the LoadAll() method would be available in the FCMeasures class. However, it's not. Instead, it's implemented in the __FCCollectionData parent class and that method will affect many other child classes, such as FCPages, FCStaffSystems, etc.

By using the JW Lua's Class Browser feature, it's easy to see which properties and methods a class actually has access to.

A constructor call is what creates an object of a class, to make it accessible to a Lua script. Only classes starting with the FC prefix should be created as objects (not the internal classes starting with _FC).

Constructors always use the dot separator, such as:

measure = finale.FCMeasure()

The created object is normally “clean” after the constructor call - you need to load it with data.

In C++, functions within a class context is called a method. The same terminology is used here.

All method calls are using a colon separator, such as:

measure = finale.FCMeasure()  -- Creates a measure object (dot separator to constructor)
measure:Load(1)               -- Loads a measure (colon separator to method)

All C++ methods in the PDK Framework will not be accessible through Lua. Some classes and methods are not needed in Lua, and others don't make sense to support in Lua script programming.

A Lua-supported method/constant will have a “Lua-supported” text in the remark. Use a text search of Lua-supported to fast find the elements of a class that you can use in your script.

Properties is a concept that isn't available in the C++ PDK Framework, but it's available in JW Lua.

In the framework documentation, you'll find getters and setters, such as GetWidth() and SetWidth() for the FCMeasure class. You could use the getter and setter to get/set the width, such as:

measure:SetWidth(measure:GetWidth() + 10)     -- Setter/getter methods using colon separator

(Use colon separator before the method names above.)

However, using properties it's much easier to read (please note the dot separator to access the property):

measure.Width = measure.Width + 10    -- Property access using dot separator 

If the setter/getter support properties in Lua, just remove the Get/Set prefix to access it as a property (using a dot separator). There is no separate documentation for the properties, but Lua-supported properties are marked with a “Lua-supported (also as property)” text in the documentation for the setter/getter method. Use a text search of (for example) property to find the Lua-available properties of a class fast.

Almost every property in JW Lua has both “read” and “write” access. However, a some few protected properties might only have “read” access.

In the PDK Framework (which is using the C++ syntax), constants are “enums” in the namespace of a class. For example, a constant for a barline style in a measure is called BARLINE_THICK in the FCMeasure class. In C++, it's in the FCMeasure::BARLINE_THICK namespace.

In JW Lua however, all such constants are at the finale namespace level (and without the enum type check that C++ provides). So, the correct way to access the same constant in Lua would be through finale.BARLINE_THICK.

Although the Lua language contains numerous advantages compared to programming directly in C++, there are some drawbacks as well:

• The currently used conversion layer between Lua and C++ doesn't support optional arguments in method calls (this might change in the future, though). So in Lua, you need to provide all the arguments to a PDK Framework method.
• Overloaded methods aren't supported, due to Lua's loose type checking. Only one version of a PDK Framework method will be available to JW Lua.