finaleplugin properties

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.)

RequireSelection (boolean)

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.

RequireScore (boolean)

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.

RequireDocument* (boolean)

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.

NoStore (boolean)

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.

HandlesUndo* (boolean)

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.

LoadAsString* (boolean)

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.

LoadLuaSocket* (boolean)

Setting this value to true tells RGP Lua to load the complete embedded luasocket package and change the require function to allow for easy loading of external lua files from the luasocket package. This happens even if Enable Debugging is not selected in the configuration dialog. See the this link for more information.

finaleplugin.LoadLuaSocket = true

Default is false.

MinFinaleVersion (number)

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 26 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.

MaxFinaleVersion (number)

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)

(JW Lua sees Finale 25 as 2025 whereas RGP Lua sees it as 10025.)

MinFinaleVersionRaw* (number)

The minimum raw version of Finale that can run the script. Example:

finaleplugin.MinFinaleVersionRaw = 0x1a200000 -- Finale 26.2: 0x1a == 26 in hexadecimal

MaxFinaleVersionRaw* (number)

The maximum raw version of Finale that can run the script. Example:

finaleplugin.MaxFinaleVersionRaw = 0x1b100000 -- Finale 27.1: 0x1b == 27 in hexadecimal

MinJWLuaVersion (number)

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

MaxJWLuaVersion (number)

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

Author (string)

The full name of the author. Example:

finaleplugin.Author = "John Smith"

One-line copyright string. Example:

finaleplugin.Copyright = "Copyright (c) John Smith, 2013"

Version (string or number)

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"

CategoryTags (string)

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"

Date (string)

The release date (in any text format). Example:

finaleplugin.Date = "July 28, 2013"

Notes (multiline string)

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.

RevisionNotes (multiline string)

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
]]

AuthorURL (string)

A URL to the script’s home page. Example:

finaleplugin.AuthorURL = "http://www.theurl.com"

AuthorEmail (string)

The contact e-mail to the author. Example:

finaleplugin.AuthorEmail = "john.smith@theurl.com"

Id (string)

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"

Additional Menu Options

Frequently you may wish to have shortcuts to functions that differ from each other by only one or a few variables. For example, you might wish to have a script that transposes a selected music region up an octave. If you then wanted another script to transpose a region down an octave, you might duplicate the up-octave script and change a single value in it. You could instead reuse the first script by defining the interval value in a variable. This would allow for separate configurations of the script in the configuration dialog, but it still would require end-users to set up the configurations for themselves. And they would have to be somewhat knowledgable of Lua syntax to do it.

RGP Lua version 0.62 introduces the concept of Additional Menu Options. These allow a script to configure multiple versions of itself to appear in Finale’s Plug-ins menu. The setup of Additional Menu Options is similar to the setup of the deprecated Parameters fields in JW Lua. Each of the necessary fields (menu option text, undo text, description, and prefix) appear in parallel lists delimited by line breaks. Each list is a multiline string value in the finaleplugin namespace.

JW Lua does not support Additional Menu Options. It loads only the base menu option of the script, even if Additional Menu Options are supplied.

AdditionalMenuOptions (multiline string)

The text for each of the menu options to be added (in addition to the main menu option returned by the plugindef() function. Each line of the string represents a menu option to be added. Whitespace is ignored.

finaleplugin.AdditionalMenuOptions = [[
    Transpose Octave Down
    Transpose Third Up
    Transpose Third Down
]]

AdditionalUndoText (multiline string)

The undo text corresponding to each of the additional menu options defined in the AdditionalMenuOptions field. This field may be omitted, and RGP Lua then uses each menu item text for its corresponding undo text.

finaleplugin.AdditionalUndoText = [[
    Transpose Octave Down
    Transpose Third Up
    Transpose Third Down
]]

AdditionalDescriptions (multiline string)

The description text corresponding to each of the additional menu options defined in the AdditionalMenuOptions field. If you omit these fields, RGP Lua uses the default description returned by the plugindef() function. It is highly recommended to supply separate description text for each additional menu option, but if your base description is generic enough to cover all the different menu options, then it is not necessary.

finaleplugin.AdditionalDescriptions = [[
    Transposes the selected region an octave lower
    Transposes the selected region a third higher
    Transposes the selected region a third lower
]]

AdditionalPrefixes (multiline string)

The prefixes corresponding to each of the additional menu options defined in the AdditionalMenuOptions field. Each prefix is a line of Lua code that defines how the script should behave for that menu option. Keep in mind that, if necessary, you can define more than one variable on a single line of Lua code, for example:

var_a = 1 var_b = true var_c = "EVPU"

Since each prefix can be any Lua code you wish, the sky is pretty much the limit on what you can do with it. In the example below it is a simple variable assignment, but it could instead (or in addition) be a string that the script then requires or that contains a function name to execute. Or if there are so many variables to assign that a single line of Lua is confusing, you could define a configuration table inside the script and use the prefix to supply an index into the configuration table.

Each additional prefix executes in addition to and after any prefix defined in the configuration dialog. (Note, however, that RGP Lua ignores the AdditionalMenuOptions fields if the configuration includes Optional Menu Text.) Each additional prefix also executes after any System Prefix, if defined.

finaleplugin.AdditionalPrefixes = [[
    input_interval = -7
    input_interval = 2
    input_interval = -2
]]

Group scripts

If you use additional menu properties, you’ll often want to categorize your script as a group script. That way, users trying to find and download your script on this website will see a title and description that represents the group of menu items, not just one of the individual menu items.

ScriptGroupName (string)

The name of the group script. Example:

finaleplugin.ScriptGroupName = "Hairpin creator"

ScriptGroupDescription (string)

The description of the group script. Example:

finaleplugin.ScriptGroupDescription = "Creates hairpins of all varieties"

Parameters (Deprecated)

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 and/or Additional Menu Options. The parameter properties described here are deprecated and ignored by RGP Lua.

ParameterTypes (multiline string)

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
]]

ParameterDescriptions (multiline string)

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
]]

ParameterLists (multiline string)

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
]]

ParameterInitValues (multiline string)

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.)