This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
jwlua:frameworkdocs [2013/08/01 14:19] jariw [Methods] |
jwlua:frameworkdocs [2013/09/03 14:22] (current) jariw |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | This page discusses how you should read the PDK Framework documentation, so it makes sense in //JW Lua// scripts. | + | 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++ ===== | ===== A Reference for C++ ===== | ||
- | The PDK Framework 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 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 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 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 a class). | + | * 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 return type of a Lua-supported method. | ||
* The description details of a Lua-supported method/constant. | * 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 ====== | ===== Inheritance ====== | ||
- | Please note that the PDK Framework is object-oriented, so if you don't find a task in the class you're searching, try and look in the parent classes. | + | {{ :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 ''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. | + | 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 ===== | ===== Constructors ===== | ||
- | A **constructor** call is what creates an instance of a class, to make it accessible to a Lua script. Only instances of classes starting with the ''FC'' prefix should be created (not the internal classes starting with ''_FC''). | + | 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: | Constructors always use the **dot separator**, such as: | ||
<code lua>measure = finale.FCMeasure()</code> | <code lua>measure = finale.FCMeasure()</code> | ||
- | The created object is normally "clean" after the costructor call - you need to load it with data. | + | The created object is normally "clean" after the constructor call - you need to load it with data. |
===== Methods ====== | ===== Methods ====== | ||
Line 46: | Line 55: | ||
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: | 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)</code> | + | <code lua>measure:SetWidth(measure:GetWidth() + 10) -- Setter/getter methods using colon separator</code> |
(Use **colon separator** before the method names above.) | (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): | 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</code> | + | <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). | + | 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. | Almost every property in //JW Lua// has both "read" and "write" access. However, a some few protected properties might only have "read" access. | ||
- | Lua-supported properties are marked with a "//Lua-supported (also as property)//" text in the documentation. Use a text search of (for example) //property// to find the Lua-available properties of a class fast. | ||
===== Constants ===== | ===== Constants ===== | ||
Line 62: | Line 70: | ||
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 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. So, the correct way to access the same constant in Lua would be through ''finale.BARLINE_THICK''. | + | 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. |