dynamic_levels.lua

function plugindef()
 finaleplugin.RequireSelection = false
 finaleplugin.HandlesUndo = true
 finaleplugin.Author = "Carl Vine"
 finaleplugin.AuthorURL = "https://carlvine.com/lua"
 finaleplugin.Copyright = "https://creativecommons.org/licenses/by/4.0/"
 finaleplugin.Version = "0.12"
 finaleplugin.Date = "2024/07/20"
 finaleplugin.MinJWLuaVersion = 0.70
 finaleplugin.Notes = [[
 Make dynamic marks in the selection louder or softer by stages. 
 This functionality is buried within the __JW Change__ plugin 
 but is useful enough to make it accessible more easily. 
 This script works similarly but allows jumping up to 9 _levels_ at once. 
 Dynamics range from __pppppp__ to __ffffff__, though scores using 
 older (non-__SMuFL__) fonts are restricted to the range __pppp__-__ffff__. 

 To repeat the previous level shift without a confirmation dialog 
 hold down [_Shift_] when starting the script. 
 ]]
 return "Dynamic Levels...",
 "Dynamic Levels",
 "Make dynamic marks in the selection louder or softer by stages"
end

local hotkey = { -- customise hotkeys (lowercase only)
 direction = "z", -- toggle Louder/Softer
 create_new = "e", -- toggle create_new
 show_info = "q",
}
local config = {
 direction = 0, -- 0 == "Louder", 1 = "Softer"
 levels = 1, -- how many "levels" louder or softer
 create_new = false, -- don't create new dynamics without permission
 window_pos_x = false,
 window_pos_y = false,
}
local configuration = require("library.configuration")
local mixin = require("library.mixin")
local expression = require("library.expression")
local utils = require("library.utils")
local library = require("library.general_library")
local script_name = library.calc_script_name()
local name = plugindef():gsub("%.%.%.", "")
local dyn_char = library.is_font_smufl_font() and
 { -- char numbers for SMuFL dynamics (1-14)
 0xe527, 0xe528, 0xe529, 0xe52a, 0xe52b, 0xe520, 0xe52c, -- pppppp -> mp
 0xe52d, 0xe522, 0xe52f, 0xe530, 0xe531, 0xe532, 0xe533, -- mf -> ffffff
 } or
 { -- char numbers for non-SMuFL dynamics (1-10)
 175, 184, 185, 112, 80, -- pppp -> mp
 70, 102, 196, 236, 235 -- mf -> ffff
 }
local function dialog_set_position(dialog)
 if config.window_pos_x and config.window_pos_y then
 dialog:StorePosition()
 dialog:SetRestorePositionOnlyData(config.window_pos_x, config.window_pos_y)
 dialog:RestorePosition()
 end
end

local function dialog_save_position(dialog)
 dialog:StorePosition()
 config.window_pos_x = dialog.StoredX
 config.window_pos_y = dialog.StoredY
 configuration.save_user_settings(script_name, config)
end

local function get_staff_name(staff_num)
 local staff = finale.FCStaff()
 staff:Load(staff_num)
 local str = staff:CreateDisplayAbbreviatedNameString().LuaString
 if not str or str == "" then
 str = "Staff" .. staff_num
 end
 return str
end

local function update_selection()
 local rgn = finenv.Region()
 if rgn:IsEmpty() then
 return ""
 else
 local s = get_staff_name(rgn.StartStaff)
 if rgn.EndStaff ~= rgn.StartStaff then
 s = s .. "-" .. get_staff_name(rgn.EndStaff)
 end
 s = s .. " m." .. rgn.StartMeasure
 if rgn.StartMeasure ~= rgn.EndMeasure then
 s = s .. "-" .. rgn.EndMeasure
 end
 return s
 end
end

local function create_dynamics_alert(dialog)
 local msg = "The required replacement dynamic doesn't exist in this file. "
 .. "Do you want this script to create "
 .. "additional dynamic expressions as required? "
 .. "(You can change this decision later in the dialog window.)"
 local ui = dialog and dialog:CreateChildUI() or finenv.UI()
 return ui:AlertYesNo(msg, name) == finale.YESRETURN
end

local function create_dynamic_def(expression_text, hidden)
 local cat_def = finale.FCCategoryDef()
 cat_def:Load(1) -- default "DYNAMIC" category
 local finfo = finale.FCFontInfo()
 cat_def:GetMusicFontInfo(finfo)
 finfo.EnigmaStyles = finale["ENIGMASTYLE_" .. (hidden and "HIDDEN" or "PLAIN")]
 local str = finale.FCString()
 str.LuaString = "^fontMus"
 .. finfo:CreateEnigmaString(finale.FCString()).LuaString
 .. expression_text
 local ted = mixin.FCMTextExpressionDef()
 ted:SaveNewTextBlock(str)
 :AssignToCategory(cat_def)
 :SetUseCategoryPos(true)
 :SetUseCategoryFont(true)
 :SaveNew()
 return ted:GetItemNo() -- save new item number
end

local function is_hidden_exp(exp_def)
 local str = exp_def:CreateTextString()
 return str:CreateLastFontInfo().Hidden
end

local function change_dynamics(dialog)
 local selection = update_selection()
 if selection == "" then -- empty region
 local ui = dialog and dialog:CreateChildUI() or finenv.UI()
 ui:AlertError("Please select some music\nbefore running this script", name)
 return
 end
 local found = { show = {}, hide = {} } -- collate matched dynamic expressions
 local match_count = { show = 0, hide = 0 }
 local shift = config.levels -- how many dynamic levels to move?
 if config.direction == 1 then shift = -shift end -- softer not louder
 local dyn_len = library.is_font_smufl_font() and 3 or 2 -- dynamic max string length

 -- match all target dynamics within existing dynamic expressions
 local function match_dynamics(hidden) -- hidden is true or false
 local mode = hidden and "hide" or "show"
 local exp_defs = mixin.FCMTextExpressionDefs()
 exp_defs:LoadAll()
 for exp_def in each(exp_defs) do
 if exp_def.CategoryID == 1 and hidden == is_hidden_exp(exp_def) then
 local str = exp_def:CreateTextString()
 str:TrimEnigmaTags()
 if str.LuaString:len() <= dyn_len then -- within max dynamic length
 for i, v in ipairs(dyn_char) do -- check all dynamic glyphs
 if not found[mode][i] and str.LuaString == utf8.char(v) then
 found[mode][i] = exp_def.ItemNo -- matched char
 match_count[mode] = match_count[mode] + 1
 end
 end
 end
 end
 if match_count[mode] >= #dyn_char then break end -- all collected
 end
 end
 match_dynamics(true)
 match_dynamics(false)
 -- start
 finenv.StartNewUndoBlock(string.format("Dynamics %s%d %s",
 (config.direction == 0 and "+" or "-"), config.levels, selection)
 )
 -- scan the selection for dynamics and change them
 for e in loadallforregion(mixin.FCMExpressions(), finenv.Region()) do
 if expression.is_dynamic(e) then
 local exp_def = e:CreateTextExpressionDef()
 if exp_def then
 local hidden = is_hidden_exp(exp_def)
 local mode = hidden and "hide" or "show"
 local str = exp_def:CreateTextString()
 str:TrimEnigmaTags()
 if str.LuaString:len() <= dyn_len then -- dynamic length
 for i, v in ipairs(dyn_char) do -- look for matching dynamic
 local target = math.min(math.max(1, i + shift), #dyn_char)
 if str.LuaString == utf8.char(v) then -- dynamic match
 if found[mode][target] then -- replacement exists
 e:SetID(found[mode][target]):Save()
 else -- create new dynamic
 if not config.create_new then -- ask permission
 config.create_new = create_dynamics_alert(dialog)
 end
 if config.create_new then -- create missing dynamic exp_def
 if dialog then -- update checkbox condition
 dialog:GetControl("create_new"):SetCheck(1)
 end
 local t = utf8.char(dyn_char[target]) -- dynamic text char
 found[mode][target] = create_dynamic_def(t, hidden)
 e:SetID(found[mode][target]):Save()
 end
 end
 break -- all done for this target dynamic
 end
 end
 end
 end
 end
 end
 finenv.EndUndoBlock(true)
 finenv.Region():Redraw()
end

local function run_the_dialog()
 local y, m_offset = 0, finenv.UI():IsOnMac() and 3 or 0
 local save = config.levels
 local ctl = {}
 local dialog = mixin.FCXCustomLuaWindow():SetTitle("Dynamics")
 -- local functions
 local function yd(diff) y = y + (diff or 20) end
 local function show_info()
 utils.show_notes_dialog(dialog, "About " .. name, 330, 160)
 end
 local function cstat(horiz, vert, wide, str) -- dialog static text
 return dialog:CreateStatic(horiz, vert):SetWidth(wide):SetText(str)
 end
 local function key_subs()
 local s = ctl.levels:GetText():lower()
 if s:find("[^1-9]") then
 if s:find(hotkey.show_info) then show_info()
 elseif s:find(hotkey.direction) then
 local n = ctl.direction:GetSelectedItem()
 ctl.direction:SetSelectedItem((n + 1) % 2)
 elseif s:find(hotkey.create_new) then
 local n = ctl.create_new:GetCheck()
 ctl.create_new:SetCheck((n + 1) % 2)
 end
 else
 save = s:sub(-1) -- save last entered char only
 end
 ctl.levels:SetText(save)
 end
 ctl.title = cstat(10, y, 120, name:upper())
 yd()
 -- RadioButtonGroup
 local labels = finale.FCStrings()
 labels:CopyFromStringTable{ "Louder", "Softer" }
 ctl.direction = dialog:CreateRadioButtonGroup(0, y + 1, 2)
 :SetText(labels):SetWidth(55):SetSelectedItem(config.direction)
 local softer = ctl.direction:GetItemAt(1) -- 2nd button
 softer:SetTop(y + 24)
 cstat(23, y + 11, 25, "(" .. hotkey.direction .. ")")
 -- levels
 cstat(65, y, 55, "Levels:")
 ctl.levels = dialog:CreateEdit(110, y - m_offset):SetText(config.levels):SetWidth(20)
 :AddHandleCommand(function() key_subs() end)
 yd()
 ctl.q = dialog:CreateButton(110, y):SetText("?"):SetWidth(20)
 :AddHandleCommand(function() show_info() end)
 yd(23)
 ctl.create_new = dialog:CreateCheckbox(0, y, "create_new")
 :SetWidth(145):SetCheck(config.create_new and 1 or 0)
 :SetText("Enable Creation of New")
 yd(13)
 cstat(13, y, 135, "Dynamic Expressions (" .. hotkey.create_new .. ")")
 -- wrap it up
 dialog:CreateOkButton() :SetText("Apply")
 dialog:CreateCancelButton():SetText("Close")
 dialog:RegisterInitWindow(function()
 local bold = ctl.q:CreateFontInfo():SetBold(true)
 ctl.q:SetFont(bold)
 ctl.title:SetFont(bold)
 end)
 dialog_set_position(dialog)
 dialog:RegisterHandleOkButtonPressed(function()
 config.direction = ctl.direction:GetSelectedItem()
 config.levels = ctl.levels:GetInteger()
 config.create_new = (ctl.create_new:GetCheck() == 1)
 change_dynamics(dialog)
 end)
 dialog:RegisterCloseWindow(function(self)
 dialog_save_position(self)
 end)
 dialog:RunModeless()
end

local function dynamic_levels()
 configuration.get_user_settings(script_name, config, true)
 local qim = finenv.QueryInvokedModifierKeys
 local mod_key = qim and (qim(finale.CMDMODKEY_ALT) or qim(finale.CMDMODKEY_SHIFT))

 if mod_key then
 change_dynamics(nil)
 else
 run_the_dialog()
 end
end

dynamic_levels()