User Tools
jwlua:development
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
jwlua:development [2014/03/19 14:45] jariw [Memory Management] |
jwlua:development [2015/04/17 09:59] (current) jariw [The 'finenv' namespace] |
||
|---|---|---|---|
| Line 51: | Line 51: | ||
| | finenv.UI() | Returns the global "user interface" object (of the FCUI class). The FCUI class contains Finale and system-global tasks, such as displaying alert boxes, sounding a system beep, or getting the width of the screen, etc. | | | finenv.UI() | Returns the global "user interface" object (of the FCUI class). The FCUI class contains Finale and system-global tasks, such as displaying alert boxes, sounding a system beep, or getting the width of the screen, etc. | | ||
| | finenv.UserValueInput() | Creates and returns a dialog object to be used for [[jwlua:uservalueinput|simple user input]]. | | | finenv.UserValueInput() | Creates and returns a dialog object to be used for [[jwlua:uservalueinput|simple user input]]. | | ||
| + | | finenv.StartNewUndoBlock() | Ends the currently active Undo/Redo block in Finale and starts a new one with a new undo text. First parameter (a Lua string) is the name of the new Undo/Redo block. Second parameter (optional, default is ''true'') is a boolean, indicating if the edits in the previous Undo/Redo block should be stored (=true) or cancelled (=false). Finale will only store Undo/Redo blocks that contains edit changes to the documents. Available in beta 0.36 and above. | | ||
| | finenv.FinaleVersion | A read-only property with the running Finale "year" version, such as 2011, 2012, etc. | | | finenv.FinaleVersion | A read-only property with the running Finale "year" version, such as 2011, 2012, etc. | | ||
| | finenv.RawFinaleVersion | A read-only property with the full Finale version number. It's constructed as 4 bytes with different version info. The highest byte is the major version, the next is subversion, etc. Use this only if you need the revision number of a specific major Finale version. | | | finenv.RawFinaleVersion | A read-only property with the full Finale version number. It's constructed as 4 bytes with different version info. The highest byte is the major version, the next is subversion, etc. Use this only if you need the revision number of a specific major Finale version. | | ||
| Line 56: | Line 57: | ||
| | finenv.MinorVersion | A read-only property with the minor version number of JW Lua. A version 1.07 would give 7, etc. | | | finenv.MinorVersion | A read-only property with the minor version number of JW Lua. A version 1.07 would give 7, etc. | | ||
| | finenv.StringVersion | A read-only property with the full "printed" version number of JW Lua, as a string. | | | finenv.StringVersion | A read-only property with the full "printed" version number of JW Lua, as a string. | | ||
| + | | finenv.ConsoleIsAvailable | A read-only property that will return true if there's a console available for ''print()'' statements. Scripts that runs from the Finale menu don't have a console. Available in beta v0.28 and above. | | ||
| Line 129: | Line 131: | ||
| The plugindef() function can return a maximum of 3 return values (all of them should be strings): | The plugindef() function can return a maximum of 3 return values (all of them should be strings): | ||
| - | * The **first** return value is the //name// of the plug-in. | + | * The **first** return value is the //name// of the plug-in. On Windows, the ''&'' character can be used before a letter to specify that letter as a mnemonic character keystroke when the script appears in Finale's plug-in menu. //(Example: "My &Plug-in" would make ''p'' the shortcut mnemonic key.)// |
| * The **second** return value is the //undo text// for the plug-in. The undo string will get a " [JW Lua]" text appended after it when Finale gets the undo record. | * The **second** return value is the //undo text// for the plug-in. The undo string will get a " [JW Lua]" text appended after it when Finale gets the undo record. | ||
| * The **third** return value is a //brief description text// (for the status/message bar in //Finale// and the //JW Lua// user interface). | * The **third** return value is a //brief description text// (for the status/message bar in //Finale// and the //JW Lua// user interface). | ||
| Line 188: | Line 190: | ||
| allpages:LoadAll() | allpages:LoadAll() | ||
| for v in each(allpages) do | for v in each(allpages) do | ||
| + | print ("Page", v.ItemNo, "has the width", v.Width) | ||
| + | end</code> | ||
| + | |||
| + | ==== eachbackwards() ==== | ||
| + | |||
| + | ''eachbackwards()'' does the same as the ''each()'' iterator, but parses the elements backwards starting from the end of the collection. It feeds the ''for'' loop with all the elements of the collection. This iterator is available in beta version 0.31 and later. | ||
| + | |||
| + | <code lua>-- Print the widths for all the pages, starting from the last page | ||
| + | allpages = finale.FCPages() | ||
| + | allpages:LoadAll() | ||
| + | for v in eachbackwards(allpages) do | ||
| print ("Page", v.ItemNo, "has the width", v.Width) | print ("Page", v.ItemNo, "has the width", v.Width) | ||
| end</code> | end</code> | ||
| Line 193: | Line 206: | ||
| ==== eachentry() ==== | ==== eachentry() ==== | ||
| - | ''eachentry()'' feeds a ''for'' loop with all the note entry objects in a region, without saving them back. | + | ''eachentry()'' feeds a ''for'' loop with all the note entry objects in a region, without saving them back. Mirror entries are processed with ''eachentry()''. |
| First parameter to this function is the region to process, where you could use ''finenv.Region()'' to get the current selection. | First parameter to this function is the region to process, where you could use ''finenv.Region()'' to get the current selection. | ||
| Line 217: | Line 230: | ||
| ==== eachentrysaved() ==== | ==== eachentrysaved() ==== | ||
| - | ''eachentrysaved()'' feeds a ''for'' loop with all the note entry objects in a region and automatically saves the entries back to Finale after processing. Only use this function when the entries actually needs to be saved. It requires the same parameter(s) as ''eachentry()'' (see above). | + | ''eachentrysaved()'' feeds a ''for'' loop with all the note entry objects in a region and automatically saves the entries back to Finale after processing. Only use this function when the entries actually needs to be saved. It requires the same parameter(s) as ''eachentry()'' (see above). Mirror entries are __not__ processed with ''eachentrysaved()''. |
| One other task that can be automatically done with ''eachentrysaved()'' is to delete entries. Just set the duration to 0, and ''eachentrysaved()'' will automatically delete the entry prior to saving it. | One other task that can be automatically done with ''eachentrysaved()'' is to delete entries. Just set the duration to 0, and ''eachentrysaved()'' will automatically delete the entry prior to saving it. | ||
| Line 273: | Line 286: | ||
| The Lua language handles memory through a garbage collection: the memory are handled automatically by Lua. However, there are a couple of points that a plug-in programmer should be aware of. | The Lua language handles memory through a garbage collection: the memory are handled automatically by Lua. However, there are a couple of points that a plug-in programmer should be aware of. | ||
| - | * Define variables as ''local'' as often as possible. This becomes particularly important when group scripts are used (global variables survives to the subsequent scripts in the group as well). | + | * Define variables as ''local'' as often as possible. This becomes particularly important when group scripts are used (global variables survives to the subsequent scripts in the group as well), or when using libraries. |
| - | * The memory allocated by JW Lua's ''Create'' methods are handled by JW Lua (and not by the Lua interpreter) and those memory objects are released __after__ the full script has been run. | + | * The memory allocated by JW Lua's ''Create'' methods are handled automatically by JW Lua (and not by the Lua interpreter) and those memory objects are released __after__ the full script has been run. |
| * Since the ''Create'' methods could sometimes result in a huge number of object waiting for release (for example in a tight loop), ''Lookup'' classes (classes that ends with ''Lookup'') are available as a faster and more memory-efficient approach. | * Since the ''Create'' methods could sometimes result in a huge number of object waiting for release (for example in a tight loop), ''Lookup'' classes (classes that ends with ''Lookup'') are available as a faster and more memory-efficient approach. | ||
| + | * When using the ''FCCellMetrics'' or ''FCNoteEntryMetrics'' class, make sure to call the ''FreeMetrics()'' method separately for the loaded object as soon as the data is no longer is needed. Finale allocate loaded metrics data internally, and metrics with a garbage collector can otherwise lead to problems in scripts where lots of metrics data are loaded without release. | ||
| ===== Tips ===== | ===== Tips ===== | ||
| - | * If you don't need a collection object anymore, you can set it to ''nil''. That might benefit performance in large scripts with huge collections of data (since it signals to the garbage collector that it can free the allocated memory). | + | * If you don't need a collection object anymore, you can set it to ''nil''. That might benefit the performance in large scripts with huge collections of data (since it signals to the garbage collector that it can free the allocated memory). |
| * There's virtually no performance penalty to put lots of comments in the script code. Once the script has been loaded into the Lua engine, the code resides in (quite efficient) bytecode where only the actual execution code appears. | * There's virtually no performance penalty to put lots of comments in the script code. Once the script has been loaded into the Lua engine, the code resides in (quite efficient) bytecode where only the actual execution code appears. | ||
| + | * An alternative syntax for properties is to use the property name as a string table index with the object as a table. For example, the syntax ''mymeasure.Width'' is equivalent to ''mymeasure["Width"]''. This alternative syntax might be useful when referencing properties dynamically through the code. | ||
jwlua/development.1395240357.txt.gz · Last modified: 2014/03/19 14:45 by jariw
Page Tools
