finaleplugin properties

This page contains a detailed description of the finaleplugin properties that can be set in the plugindef() function. Normally these values are set by using the Plug-in Def dialog box in 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. Example:

finaleplugin.RequireSelection = true

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. Example:

finaleplugin.RequireScore = 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

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:

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

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)

An 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. This is required if the plug-in should be shared through the JW Lua repository. 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"

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