This page contains a detailed description of the finaleplugin properties that can be set in the plugindef() function. For RGP Lua use a text editor to set them. For JW Lua you can use the Plug-in Def dialog box in JW Lua to set many of them.
(Items with an asterisk are recognized by RGP Lua but not JW Lua.)
If this is set to true, the script will not execute if a selection region isn’t available for the current document. Instead, a user alert will display with information that the user should first select a region. (RGP Lua grays it out rather than showing an alert.) Example:
finaleplugin.RequireSelection = true
Default is false.
If this is set to true, the script will not execute if a part is viewed for the current document. Instead, a user alert will display with information that the user should first switch to the score view. (RGP Lua grays it out rather than showing an alert.) Example:
finaleplugin.RequireScore = true
Default is false.
If this is set to false, the script will be available in RGP Lua even if no documents are open in Finale. JW Lua ignores this value. Example:
finaleplugin.RequireDocument = false
Default is true.
If this is set to true, the script will run in “sandbox mode”. After the script has run, any saves made to Finale’s database are automatically rolled back, so such a script will never do any permanent edits to a document. This might be useful for example when creatin diagnostic scripts, or during development to check that the script syntax will work. Example:
finaleplugin.NoStore = true
Default is false.
Both JW Lua and RGP Lua (by default) automatically run scripts within an undo block named according the undo string returned by the plugindef() function. However, it is possible for a script to notify RGP Lua that it will handle undo blocks on its own by setting this value to true. One primary reason a script might enable this option is to open a modeless dialog window. Example:
finaleplugin.HandlesUndo = true
Default is false.
Setting this value to true tells RGP Lua to load the script into an internal string and then send it to Lua. One reason to do this might be if the script file contains an embedded NULL character. This option would cause the Lua interpreter to stop at the NULL. It overrides the Load As String setting in the configuration dialog.
finaleplugin.LoadAsString = true
Default is the script’s “Load As String” setting in the RGP Lua configuration dialog.
Setting this value to true tells RGP Lua to load luasocket into global variable socket, even if Enable Debugging is not selected in the configuration dialog. If debugging is enabled, this value is ignored and luasocket is loaded. Example:
finaleplugin.LoadLuaSocket = true
Default is false.
The minimum version of Finale that can run the script. The number should match that returned by finenv.FinaleVersion. JW Lua reads this value every time a script runs and displays an error message if the running Finale version is too low. RGP Lua reads the value once and omits it from Finale’s Plug-in menu if the running Finale version is too low. Examples:
finaleplugin.MinFinaleVersion = 2014 -- Finale 2014 (recognized by both RGP Lua and JW Lua)
or
finaleplugin.MinFinaleVersion = 10026 -- Finale 26 (recognized by RGP Lua but not JW Lua)
Note that JW Lua sees all versions of Finale starting with Finale 25 as being version 9999. Therefore the above example of 10026 for MinFinaleVersion will prevent JW Lua from running the script at all. It will produce a somewhat confusing error message, however, so it is recommended to use MinFinaleVersionRaw along with MinJWLuaVersion to prevent JW Lua from running a script that requires Finale 26. (Or handle it yourself in the script.) This produces a better error message in JW Lua.
The minimum version of Finale that can run the script. The number should match that returned by finenv.FinaleVersion. JW Lua reads this value every time a script runs and displays an error message if the running Finale version is too high. RGP Lua reads the value once and omits it from Finale’s Plug-in menu if the running Finale version is too high. Examples:
finaleplugin.MaxFinaleVersion = 2012 -- Finale 2012 (recognized by both RGP Lua and JW Lua)
or
finaleplugin.MaxFinaleVersion = 10025 -- Finale 25 (recognized by RGP Lua but not JW Lua)
The minimum raw version of Finale that can run the script. Example:
finaleplugin.MinFinaleVersionRaw = 0x1a020000 -- Finale 26.2
The maximum raw version of Finale that can run the script. Example:
finaleplugin.MaxFinaleVersionRaw = 0x1b010000 -- Finale 27.1
The minimum version of JW/RGP Lua that can run the script. This is a decimal number of the form <major>.<minor>. The highest JW Lua version is 0.54 and the lowest RGP Lua version is 0.55. JW Lua reads this value every time a script runs and displays an error message if the running JW Lua version is too low. RGP Lua reads the value once and omits it from Finale’s Plugin menu if the running RGP Lua version is too low. Example:
finaleplugin. MinJWLuaVersion = 0.55
The maximum version of JW/RGP Lua that can run the script. This is a decimal number of the form <major>.<minor>. The highest JW Lua version is 0.54 and the lowest RGP Lua version is 0.55. JW Lua reads this value every time a script runs and displays an error message if the running JW Lua version is too high. RGP Lua reads the value once and omits it from Finale’s Plugin menu if the running RGP Lua version is too high. Example:
finaleplugin. MaxJWLuaVersion = 0.54
The full name of the author. Example:
finaleplugin.Author = "John Smith"
One-line copyright string. Example:
finaleplugin.Copyright = "Copyright (c) John Smith, 2013"
The version number of the current plug-in. Examples:
finaleplugin.Version = 1.01
or
finaleplugin.Version = "1.5.2"
or
finaleplugin.Version = "1.01, build 14"
The tags that would categorize the plug-in script. Each tag is separated by a spaces and/or commas, and each category name is case insensitive and can contain the characters a-z only. A category name is used to filter the scripts that should be displayed in a JW Lua file folder (which helps the user to organize the scripts based on each script’s functionality). The categories in the table below are considered to be “standard categories” and should be used whenever possible. (However, there is no restriction on the keywords you may use for tags.)
| Tag | Description |
|---|---|
| Articulation | Affects character or shape articulations. |
| Chord | Affects chords. |
| Debug | Debug-only tasks for developers. |
| Development | Tasks aimed at script development. |
| Diagnose | Diagnostics tasks. |
| Expression | Affects text or shape expressions. |
| Layout | Layout tasks. |
| Lyric | Affects lyrics. |
| Measure | Affects measures (such as measure attributes). |
| MIDI | Affects MIDI data. |
| Note | Affects notes entries. |
| Page | Affects pages. |
| Percussion | Affects percussion notation. |
| Playback | Affects playback. |
| Pitch | Affects note pitches. |
| Region | Tasks that require region selections. |
| Rest | Affects rests. |
| Report | Report-only tasks. |
| Smartshape | Affects smart shapes. |
| Staff | Affects staves. |
| System | Affects staff systems. |
| Tempo | Affects tempo (notated or playback). |
| Test | Plug-ins for test purposes. |
| Text | Affects text blocks. |
| UI | Contains a user interface. |
Example:
finaleplugin.CategoryTags = "Page, Layout"
The release date (in any text format). Example:
finaleplugin.Date = "July 28, 2013"
Longer description of the plug-in and user instructions. The string can contain multiple lines. Example:
finaleplugin.Notes = [[
This plug-in hides all rests in the selected region.
Select the region before running the plug-in.
]]
Notes may contain simple Markdown syntax for creating paragraph breaks (two newlines), line breaks (two spaces at the end of lines), and numbered or bullet lists. These will be interpreted correctly at the Finale Lua site if the script is uploaded there.
Revision history text that might be of interest to an end user. The string can contain multiple lines. Example:
finaleplugin.RevisionNotes = [[
July 26, 2013: Version 1.00
July 28, 2013: Version 1.01
]]
A URL to the script’s home page. Example:
finaleplugin.AuthorURL = "http://www.theurl.com"
The contact e-mail to the author. Example:
finaleplugin.AuthorEmail = "john.smith@theurl.com"
A unique identifier that is specific to the plug-in. It may someday be useful if the plug-in should be shared through the Finale Lua repository. (Note: this repository is still a work-in-progress, so the use of an id is currently not required.) The id is case insenitive and can contain the characters abcdefghijklmnopqrstuvwxyz0123456789_.-. Suggested identifiers are a author.pluginname syntax, or a true GUID. Examples:
finaleplugin.Id = "johnsmith.hiderests"
or
finaleplugin.Id = "742d0ea0-c109-4b81-87ae-d059f27cb028"
NOTE: Parameters are not well supported by JW Lua and not supported at all by RGP Lua. For RGP Lua you can have a similar type of flexibility with a prefix. The parameter properties described here are deprecated and ignored by RGP Lua.
NOTE: Parameters are not well supported on JW Lua and not supported at all on RGP Lua. For RGP Lua you can get a similar type of funcitonality with a prefix. The parameter properties described here are deprecated..
The types to the script parameters. The syntax is similar to the SetTypes() method when using UserInputValue dialog input. Use one line for each parameter. Don’t use quotation marks around the types. The number of types must be identical to the number of descriptions.
Valid types are Number, String, Boolean and NumberedList. Example:
finaleplugin.ParameterTypes = [[
Number
Boolean
]]
The syntax is similar to the SetDescriptions() method when using UserInputValue dialog input. Use one line for each parameter. Don’t put quotation marks around the descriptions. The number of descriptions must be identical to the number of types. Example:
finaleplugin.ParameterDecriptions = [[
Resize (in percent)
Resize relative
]]
The syntax is similar to the SetLists() method when using UserInputValue dialog input. These settings are optional for script parameters. Use one line for each parameter, but don’t put {} around the list. If a list isn’t required for a parameter, set it to nil. If a comma is needed within a list item, quotation marks can be used around that list item. Example:
finaleplugin.ParameterLists = [[
nil
Yes, No
]]
The syntax is similar to the SetInitValues() method when using UserInputValue dialog input. These settings are optional for script parameters. Use one line for each parameter. If a user value isn’t required for a parameter, set it to nil. Example:
finaleplugin.ParameterInitValues = [[
nil
true
]]
(Much of this content was copied from Jari Williamsson’s site and will be removed or revised if so requested.)