This page discusses how you should read the PDK Framework documentation, so it makes sense in JW Lua scripts.
For discussions on specific programming topics related to JW Lua, please refer to the general development page.
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:
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).
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
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
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
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
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
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
Although the Lua language contains numerous advantages compared to programming directly in C++, there are some drawbacks as well: