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:34] jariw [A Reference for C++] |
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: | ||
Line 10: | Line 12: | ||
* 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 61: | 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. |