This page discusses how you should read the [[http://www.finaletips.nu/frameworkref/|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 [[jwlua:development|development page]].

===== A Reference for C++ =====

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.

===== Objects =====

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 ''[[http://www.finaletips.nu/frameworkref/class_f_c_string.html|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).

===== Inheritance ======

{{ :wiki:jwlua:fcmeasures-parents.png|}}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 ''[[http://www.finaletips.nu/frameworkref/class_f_c_measure.html|FCMeasures]]'' class. However, it's not. Instead, it's implemented in the ''[[http://www.finaletips.nu/frameworkref/class_____f_c_collection_data.html|__FCCollectionData]]'' parent class and that method will affect many other child classes, such as ''[[http://www.finaletips.nu/frameworkref/class_f_c_pages.html|FCPages]]'', ''[[http://www.finaletips.nu/frameworkref/class_f_c_staff_systems.html|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.
===== Constructors =====

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:
<code lua>measure = finale.FCMeasure()</code>

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

===== Methods ======

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:
<code lya>
measure = finale.FCMeasure()  -- Creates a measure object (dot separator to constructor)
measure:Load(1)               -- Loads a measure (colon separator to method)</code>

===== Lua-supported Methods =====

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 =====

**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:
<code lua>measure:SetWidth(measure:GetWidth() + 10)     -- Setter/getter methods using colon separator</code>
(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):
<code lua>measure.Width = measure.Width + 10    -- Property access using dot separator </code>

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.


===== Constants =====

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''.


===== Limitations =====

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.