Differences

This shows you the differences between two versions of the page.

--- jwlua:frameworkdocs [2013/08/01 14:19]
jariw [Methods]
+++ jwlua:frameworkdocs [2013/09/03 14:21]
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 [[jwlua:development|general development page]].
 ===== 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 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 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 ======
-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 =====
-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:
 <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 ======
@@ 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:
-<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.)
 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.
-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 =====
@@ 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 //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.

JW Freeware Plug-ins Wiki

User Tools

Site Tools

Differences

Page Tools