Version History

v0.73 Apr. 11, 2024 Corrected calculation of FCFontInfo.IsMacSymbolFont based on final guidance from MakeMusic.
Fix issue where sometimes the wrong line number is reported to FCLuaScriptItem when the script ends with an error.
Add clarifying comments around the use of FCNoteEntry.SetStemUp and SetFreezeStem.
Added FCMusicRegion.FixMeasureWidthsInScore. It is available to be called after modifying measure widths in a part (in any way, including executing Finale's Note Spacing menu options). This works around an issue where sometimes the score spacing is destroyed after undo/redo.
Refactored FCString to include better automatic options for UTF-16 surrogate pairs, as well as support for full-length Unicode codepoints where appropriate.
A number of C-string/Lua-string functions and properties have been updated to expect and return UTF-8 encoded strings. These are noted in the documentation of FCString for version 0.73.
(Optionally) use OS-level APIs for Mac version of FCUI::ExecuteOSMenuCommand.
Embedded luaosutils 2.5.0 (which adds menu.execute_command_id). This function adds OS-level API support for executing menu commands on either platform.
v0.72 Mar. 31, 2024 Added __FCUserWindow::MouseTrackingStarted/Stopped notifications for FCCtrlSlider.
Added FCLuaScriptItem.ControllingWindow property (with getter/setter) to allow Windows dialogs to launch from the controlling window instead of the Finale MDI window. (This prevents Finale crashes when using the console.)
Make RTF hyperlinks in FCCtrlTextEditor clickable with tooltips on Windows. This matches the default (and current) behavior on macOS.
Mac window activation now makes the window the key window, which matches Windows behavior.
Refactor beam identification methods in FCNoteEntry. They now work with grace note beams, V1/V2 beams, voiced parts, and rests (whether extending rests over beams or not).
Added FCNoteEntry.NextInBeamedGroup and PreviousInBeamedGroup to facilitate iterating over the entries in a beamed group.
Expanded FCChordPrefs to include all documented options in the PDK.
Added FCCustomKeyModeDef and FCCustomKeyModeDefs to allow managing of Finale's "Nonstandard Key Signatures" with Lua.
Replace 1-off template proxy constructors with explicit ones in PDK Framework source.
Source/Line number error tracking now works inside LuaBridge function callbacks.
Added missing properties to __FCStaffBase (and its subclasses). (These were mostly related to Tablature notation.) Also debugged many of the existing properties that were not working correctly.
v0.71 Feb. 9, 2024 Fixed bug where pre-selecting a row in FCCtrlDataList caused them all to be selected.
Added FCCtrlHorizontalLine and FCCtrlVerticalLine as subclasses of FCCtrlLine. This change should be invisible to most Lua scripts, but it could affect any that are comparing ClassName() to "FCCtrlLine".
Added horizontal auto-sizing methods to FCControl to facilitate localization.
RGP Lua now sends user locale code to plugindef function.
Added access to GetFullNamePosition and GetAbbreviatedNamePosition from FCStaffStyleDef.
Added FCCtrlTextEditor::SetLineSpacing and GetLineSpacing.
BREAKING CHANGE: Replace FCCtrlTextEditor::GetCharacterAtIndex with FCCtrlTextEditor::CreateCharacterAtIndex
Calls to plugindef() now run in untrusted mode.
Added LUA_ERROR message type to distinguish between a Lua error and a value returned by the script.
Console minor bug fixes and enhancements. Added line spacing option on macOS to mitigate issue with line number alignment when international characters are present in the text.
Added FCLuaScriptItem.GetFileName method to be able reliably to identify a script by its filename in any locale.
FCControl::SetKeyboardFocus now works correctly on macOS, and FCCtrlEdit::SetFocus is deprecated.
Hitting Enter on a read-only FCCtrlTextEditor now activates the default (OK) button, if there is one.
FCStrings::AddCopy now returns true when there is no error.
v0.70 Jan. 6, 2024 Hash-verify script files with filenames containing spaces.
Facilitate live update of hash-verified scripts (including live update of custom config file).
Added luaosutils.internet.url_escape function for percent-encoding url characters.
Modify reflection tables to facilitate showing first available Lua version and deprecation status in Class Browser.
Refactor AddMacroValue as AddConstantValue (in reflection) to make it easier to use with ad hoc macros.
Lua scripts can now detect double-clicks, enter key, and command keys on FCCtrlListBox and FCCtrlDataList.
Class browser now responds to double-click, cmd/ctrl-C, and enter key.
Class browser now includes enum values in the finale and tinyxml2 namespaces.
FCCtrlDataList can now hide its header and expand the last column to fill available space.
The macOS version of FCCtrlDataList now responds to the space-bar and ctrl-spacebar similarly to the built-in behavior on Windows. The macOS version also responds to shift-spacebar the same as ctrl-spacebar.
FCCtrlDataList can now be multi-select.
Allow hash-verified when internet is down.
Added luosutils.process.run_event_loop to allow scripts to wait on their callback functions.
Class browser now includes finenv namespace and sub-namespaces.
v0.69 Dec. 7, 2023 API Breaking Change: FCCtrlTextEditor.HandleSaveRequest is now FCCtrlTextEditor.HandleKeyboardCommand and notifies all keyboard commands, not just "Save".
Add Regular Expression search option to FCCtrlTextEditor.CreateRangesForString.
Add ENIGMASTYLES constants for specifying FCFontInfo styles.
Luaosutils 2.3.2 puts quotes around urls (if they are not already there) when you call internet.launch_website.
v0.68 Nov. 30, 2023 Fix issue where hash was not updated at initialization so ExecuteAtStartup script failed the first time after an update.
Add FCNoteEntry.ReverseDownStem and FCNoteEntry.ReverseUpStem properties.
Implement 3-state checkbox on Windows. (It was already implemented on macOS.)
Trust enforcement is now required.
Add FCBookmark and FCBookmarks.
Allow numbers to be assigned to FCString.LuaString
Fix Windows crash at startup.
Rewrite cryptography routines with IV and key tracking.
Add menu command monitor callback in FCCustomLuaWindow.
Add FCSmartShapeSegment.CalcMeasurePos and use it to allow entry-based smart shapes to work with FCSmartShape.IsWithinRegion and FCSmartShapeMeasureMarks.LoadAllForRegion.
Add FCMeasure.CreateNumberString and CreateNumberStringUnqualified methods.
Add FCCell.CreateVisibleKeySignature method.
Add FCNoteEntryCell.ReduceEntries method.
Add FCMusicRegion.Playback methods and FCSystemStaves methods for setting up temporary instrument list.
Add __FCUserWindow::CreateChildUI to allow creation of an FCUI instance that uses the __FCUserWindow as the parent window for launching built-in modeless dialogs. (Important on Windows Finale.)
Add FCUI::DisplayListenToMidiDialog to provide access to Finale's built-in ListenToMidi dialog.
Add all documented playback options to FCPlaybackPrefs.
Added FCCtrlTextEditor control for editing multiline text blocks.
Added FCActiveLyric for getting/setting the current lyric block and syllable.
Fix Unicode-encoding issues with FCSyllableBase text parsing.
Add syllable parsing to FCVerseLyricsText, FCChorusLyricsText, and FCSectionLyricsText
Enhance FCLuaScriptItem handling to allow execution of strings (plus other goodies).
Embed and pre-load luafilesystem ('lfs').
Added crypto namespace to luaosutils. Provides strong encryption with easy-to-use function calls.
Added FCPages.FindSystemNumber and FCPages.FindMeasureNumber.
Hooked up FCFretboardGroupDef and added supporting classes.
Added FCMiscDocPrefs.AlignMeasureNumbersWithBarline and FCMiscDocPrefs.LegacyDotPositionOnFlippedStems for Finale 27.4 support.
v0.67a Jul. 9, 2023 Windows Only: patched API call that caused some Windows systems to crash on initialization.
v0.67 May 2, 2023 Strip "&" on input to Win version of
Allow FCLuaScriptItem to return correct value after multiple executions.
Upgrade to Lua 5.4.
Fix Finale crash caused by saving FCRepeatPrefs, and add ShowOnTopStaffOnly and ShowOnStaffListID properties.
Allow in-line comments on lines of the plugindef() function.
Added __FCBaseData::RelinkToScore and RelinkToCurrentView.
Embedded Lua-CJSON library.
Added Lua access to already embedded TinyXML2 XML parser.
Added FCTransposer, which does the math for all your transposition needs, including transposition of FCChord instances.
Added finenv.LuaBridgeVersion for diagnostic purposes.
Upgrade to LuaBridge 3.1.
Added finenv.IsFinaleDemo to detect if we are running on the Finale demo.
FCEntryMetrics, FCCellMetrics, and most collections can be assigned with <close>
Added tinyxml2 classes to class browser and show more info about each class.
Add hash checking for trusted code and finenv.TrustedMode.
v0.66 Mar. 10, 2023 Scripts can now register to run when Finale starts up.
Report the 1st return value of a script, regardless of type. (Previously only strings were reported.) This behavior can be suppressed with a new finaleplugin.IgnoreReturnValue property.
Fix bug that prevented finenv.ExecuteLuaScriptItem from returning the script's 1st return value when the script had no error.
Fix FCMiscDocPrefs.SpecialExtractionID for Finale 25 and 26.1.
FCString now uses double for all floating point conversions.
Added FCUI::DisplayExpressionDialog to add support for choosing either text or shape expressions.
Added FCNote::CalcNumberOfLedgerLines
Added __FCStaffBase::CalcTopLineStaffPosition and __FCStaffBase::CalcBottomLineStaffPosition
FCTimeSignature and FCKeySignature now derive from __FCBase. They were never valid data structs, and calling Load or Save on them never had any effect.
Added FCAllotment and FCAllotments to lua classes.
Added functions to FCBeatChartElement and FCBeatChartElements.
Added FCArticulation.OnStemDistanceFromStemEnd property.
Embed and (optionally) preload the luaosutils library.
Added FCNoteheadMod.EnharmonicFlip property and support function FCNote::MatchSpellingToScore.
Added FCCustomLuaWindow::RegisterHandleActivate so that scripts can detect window activation/deactivation.
Upgrade utf8 library from Lua 5.3 version to Lua 5.4 version.
Change global script path string and global last undo string to be per-session.
v0.65 Dec. 7, 2022 Errors in Lua callback functions now cause the script to abort, same as if the error had occurred in any other Lua code.
Add new Finale 27.3 properties to FCGeneralPrefs.
Disallow self-execution with FCLuaScriptItem.
Add full smart shape prefs, including FCSlurContourPrefs
Add FCCellGraphic (edit-only, similar to FCPageGraphic)
Add visible flags for repeats
Add new playback types for FCTextExpressionDef
Add new methods for handling voiced parts, and update several FCNoteEntry calculations to take voicing exclusions into account.
v0.64 Aug. 28, 2022 Add FCString::EndsWithString
Add FCSeparateMeasureNumber::Get/SetIsAlternateNumber
Add missing properties to FCGeneralPrefs
Add FCCtrlComboBox class
Support RestorePosition with modal dialogs (Mac)
Add FCLuaScriptItem and FCLuaScriptItems to allow scripts to launch other scripts
Add FCUI::GetUserLocaleName
Add FCCtrlRadioButton and FCCtrlRadioButtonGroup
Add FCCtrlImage
Add __FCUserWindow::IsDarkModeAppearance and corresponding (mac-only) event handler
Add DPI-awareness for Windows dialogs.
Add FCControl::CreateFontInfo.
Add notifications to FCCtrlSlider.
Add full luasocket base (including both socket and socket.core) plus compatibility with the rest of luasocket, if finaleplugin.LoadLuaSocket = true specified.
Fix longstanding bug in FCSmartShape::CalcRightCellMetricPos
v0.63 Jul. 8, 2022 Add method FCMusicRegion::IsEmptyAndNotSinglePos and change FCLuaIterator to use it.
Implement SetFileFolder for macOS in FCFileSaveAsDialog.
Allow CreateDisplayFullNameString and other base-class functions that call FX_AutoNumberedName_UTF16 to work with FCCurrentStaffSpec.
Add methods CalcStaffInPageView, CalcStaffInScrollView, and CalcStaffInCurrentView to FCExpression.
Add method FCSmartShape::CalcLyricBased
Backport the utf8 library from Lua 5.3 into Lua 5.2. It is now added automatically in the RGP Lua environment.
Add eachstaff() standard iterator for FCMusicRegion instances.
Add FCSecondaryBeamMods collection to Lua, plus a few enhancements to make secondary beams easier to edit.
Added FCBeamExtensionMod class.
FCStaffNamePosition::SetJustification and GetJustification work as documented. To activate the record you now *must* set UsePositioning true.
Add FCUI::IsLayerVisible method.
Add FCControl::SetFont method.
Add FCCtrlStatic::SetTextColor method.
Add FCCustomWindow::MoveAllControls method.
Hooked up FCControl::MoveRelative, MoveAbsolute, and ResizeRelative to Lua.
v0.62 May 17, 2022 Add FCParts.GenerateParts()
Add FCLayerPrefs.GetMaxLayers()
Add support for auto-numbered names on staves (including multistaff names).
Add FCCellText.Visible property.
Remove sorting in Win config list.
Fixed FCBaselines::AssureSavedLyricNumberForPiece and FCBaselines::AssureSavedStaffForPiece to work as documented. (Previously they returned null unless the baseline record already existed.)
The Class Browser is now *much* faster and is no longer dependent on an external XML parser.
Add FCBrokenBeamMod support.
Add FCTieMod support.
Replaced FCNoteEntry.CalcMultiLayeredCell method with efficient fast version.
Add FCBaselines.LoadAllForSystemStaff method.
v0.61 Mar. 2, 2022 Added SetFocus and SetKeyboardFocus to Lua.
Fix issue with LoadString becoming LoadStringA on Windows.
Fix issue with Win dialog controls not scaling correctly with system settings.
Add new FCPartStaffVoicing class.
Add new properties to FCCustomSmartLineDef.
Add missing FCNote and FCNoteEntry bit settings.
Add missing static functions.
Add new StrechHorizontally property on multimeasure rests and prefs.
Add stand-alone configuration mode.
Add finenv.DebugEnabled and finenv.LoadedAsString.
Call plugindef() function before executing script (to match JW Lua behavior).
Feb. 1, 2022
Added finenv.RetainLuaState, which allows scripts to maintain state across calls.
Added finaleplugin.LoadAsString, which allows any script to request to be loaded as a string, overriding the RGP Lua setting.
Fixed bug in FCCell.CalcClefIndexAt
Added method FCGuides.SaveAll to work around Finale bug in Finale 26.2+ when saving FCGridsGuidesPrefs.
It is now possible to create new FCEnclosure instances.
RGP Lua Class Browser only builds the class index once and remembers its settings.
RGP Lua Class Browser now allows you to start editing the class field while the class index is building.
RGP Lua for Windows now reads text files correctly.
Added "Load As String" setting. This specifies that a script (or folder of scripts) should be loaded into a string and then passed to Lua. The main advantage is that if the file contains a NULL character, Lua interpretation stops at the NULL. (Otherwise the Lua interpreter would fail with a compiler error.)
Jan. 14, 2022
Correct window levels for modal file open and folder browser dialogs (Windows).
Add missing properties for cloned marks to FCArticulation.
Add methods to FCCell and FCCellClefChanges to allow modifying or deleting mid-measure clefs.
Add methods and properties to FCCell, FCCompositeTimeTop, and FCCompositeTimeBottom to allow full creating and editing of composite time signatures and time signatures for display (including independent time signatures for display).
Added optional System Prefix that RGP Lua adds to every script it runs. (One use case would be to add a common library path to package.path and/or package.cpath.)
Allow Auto Folders to have prefixes that affect all scripts in the folder. (Similar to the System Prefix, but only applied to the folder.)
Added finenv.QueryInvokedModifierKeys function to allow scripts to determine which (if any) modifier keys were pressed when the menu option was invoked.
Fixed memory leak in FCCell:CreateCellMetrics.
Added FCFontInfo:IsSMuFLFont, which works only on F27.1 and higher. (Always returns false otherwise.)
Added FCString.InsertStringAt to provide a type-safe version of InsertItemAt.
Added FCDistancePrefs.AccidentalCrossLayerPositioning property.
Added Download Scripts button to setup dialog.
v0.58 Dec. 23, 2021 New methods and properties for FCEntryMetrics and FCCellMetrics.
Obtain and execute OS menu commands directly.
Ability to create expression categories.
Support for custom key signatures for the purpose of transposing.
Support for stacking articulations.
All prefs now work correctly with Finale 26.2 and higher.
v0.57 Dec. 5, 2021 This was an emergency fix for 0.56.
Fixed bug that caused finale constants to be numbered sequentially instead of given their correct values.
Included improved focus handling for modeless dialogs on macOS.
v0.56 Dec. 4, 2021 Added FCCustomLuaWindow::ShowModeless and support routines for running modeless Lua scripts.
Fixed Finale crash on macOS due to CFRelease of a CFBundleRef we did not own. (In FCString::LoadResource)
Fixed macOS FCCustomWindows so that tab key works correctly in both keyboard navigation modes.
Added support for SetTimer/StopTimer on modal and modeless dialogs in Windows and macOS.
v0.55 Nov. 24, 2021 Initial version starting with next version number after last JW Lua version (which was 0.54). This facilitates backwards compatibility with existing scripts.

Return to RGP Lua main page.