cue_notes_create.lua

function plugindef()
    finaleplugin.RequireSelection = true
    finaleplugin.Author = "Carl Vine with additional coding by Aaron Sherber"
    finaleplugin.AuthorURL = "http://carlvine.com/lua/"
    finaleplugin.Copyright = "https://creativecommons.org/licenses/by/4.0/"
    finaleplugin.Version = "v0.92i"
    finaleplugin.Date = "2023/12/25"
    finaleplugin.AdditionalMenuOptions = [[
        Cue Notes Flip Frozen
    ]]
    finaleplugin.AdditionalUndoText = [[
        Cue Notes Flip Frozen
    ]]
    finaleplugin.AdditionalPrefixes = [[
        action = "flip"
    ]]
    finaleplugin.MinJWLuaVersion = 0.62
    finaleplugin.Notes = [[
        This script is designed to take music from one staff and create 
        "cue note" copies in the same measure on one or more empty staves. 
        The copy is smaller and muted, and can include chosen markings from the original. 
        It is copied to the chosen layer with a whole-note rest placed in the original layer.

        Preferences are preserved between each run. 
        This script uses an expression category called "Cue Names" which 
        will be created if needed. 

        An extra menu, "Cue Notes Flip Frozen", will look for notes in the 
        previously selected "cue note" layer and flip the direction of their 
        stems if they have been "frozen" up or down.
    ]]
    return "Cue Notes Create...", "Cue Notes Create", "Copy as cue notes to another staff"
end

action = action or ""

local info_notes = [[
This script is designed to take music from one staff and create
"cue note" copies in the same measure on one or more empty staves.
The copy is smaller and muted, and can include chosen markings from the original.
It is copied to the chosen layer with a whole-note rest placed in the original layer.
**
Preferences are preserved between each run.
This script uses an expression category called "Cue Names" which
will be created if needed.
**
An extra menu, "Cue Notes Flip Frozen", will look for notes in the
previously selected "cue note" layer and flip the direction of their
stems if they have been "frozen" up or down.
**
== Command Keys ==
*In the "Destination Staff" window,
hit the tab key to move the cursor into a numeric
field and these key commands are available:
*q @t show these script notes
*w @t flip [copy articulations]
*e @t flip [copy expressions]
*r @t flip [copy smartshapes]
*t @t flip [copy slurs]
*y @t flip [copy clef]
*u @t flip [copy lyrics]
*i @t flip [copy chords]
*o @t flip [mute cuenotes]
*– – –
*a @t all options checked
*s @t no options checked
*d @t select all staves
*f @t select no staves
*g @t select empty staves
*– – –
*z @t next stem direction
*x @t previous stem direction
]]
info_notes = info_notes:gsub("\n%s*", " "):gsub("*", "\n"):gsub("@t", "\t")

local config = { -- retained and over-written by the user's "settings" file
    copy_articulations  =   false,
    copy_expressions    =   false,
    copy_smartshapes    =   false,
    copy_slurs          =   true,
    copy_clef           =   false,
    copy_lyrics         =   false,
    copy_chords         =   false,
    mute_cuenotes       =   true,
    cuenote_percent     =   70,    -- (75% too big, 66% too small)
    source_layer        =   1,     -- layer the cue comes from
    cuenote_layer       =   3,     -- layer the cue ends up
    rest_layer          =   1,     -- layer for default wholenote rest
    freeze_up_down      =   0,     -- "0" for no stem freezing, "1" for up, "2" for down, "3" for away from middle
    cuename_item        =   0,     -- ItemNo of the last selected cue_name expression
    -- if creating a new "Cue Names" category ...
    cue_category_name   =   "Cue Names",
    cue_font_smaller    =   1, -- how many points smaller than the standard technique expression
    window_pos_x        =   false,
    window_pos_y        =   false,
    abbreviate          =   false
}
local option = {
    check = {   "copy_articulations", "copy_expressions", "copy_smartshapes",
                "copy_slurs", "copy_clef", "copy_lyrics", "copy_chords", "mute_cuenotes" },
    integer = { "cuenote_percent", "source_layer", "cuenote_layer" },
    stem = {  "normal", "freeze up", "freeze down", "away from middle" },
    button = { "Set All", "Clear All", "All Staves", "No Staves", "Empty Staves" }
 }

local freeze = {
    none = 0,
    up = 1,
    down = 2,
    away_from_middle = 3
}

local configuration = require("library.configuration")
local clef = require("library.clef")
local layer = require("library.layer")
local mixin = require("library.mixin")

local script_name = "cue_notes_create"
configuration.get_user_settings(script_name, config, true)

function show_error(error_code)
    local errors = {
        only_one_staff = "Please select just one staff \nas the source for the new cue",
        empty_region = "Please select a region \nwith some notes in it!",
        no_notes_in_source_layer = "The selected music contains\nno notes in layer " .. config.source_layer,
        first_make_expression_category = "You must first create a new Text Expression Category called \""..config.cue_category_name.."\" containing at least one entry",
        no_cue_notes = "The selected music contains \nno cue notes in layer " .. config.cuenote_layer,
        unknown = "Unknown error condition"
    }
    local msg = errors[error_code] or errors.unknown
    finenv.UI():AlertInfo(msg, "User Error")
    return -1
end

function dont_overwrite_existing_music(staff_number)
    local staff = finale.FCStaff()
    staff:Load(staff_number) -- staff number of this slot
    local msg = "Overwrite existing music on staff: " .. staff:CreateDisplayFullNameString().LuaString .. "?"
    local alert = finenv.UI():AlertOkCancel(msg, nil)
    return (alert ~= finale.OKRETURN)
end

function region_is_empty(region, layer_number)
    for entry in eachentry(region, layer_number) do
        if entry.Count > 0 then return false end
    end
    return true
end

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

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 info_dialog()
    finenv.UI():AlertInfo(info_notes, "About " .. plugindef())
end

local function make_info_button(dialog, x, y)
    dialog:CreateButton(x, y):SetText("?"):SetWidth(20)
        :AddHandleCommand(function() info_dialog() end)
end

function new_cue_name(source_staff)
    local dialog = mixin.FCXCustomLuaWindow():SetTitle(plugindef())
    dialog:CreateStatic(0, 0):SetText("New cue name:"):SetWidth(100)
    make_info_button(dialog, 180, 0)

    local staff = finale.FCStaff() -- copy the source Staff Name
    staff:Load(source_staff)
    local name = {
        full = staff:CreateDisplayFullNameString(),
        abbrev = staff:CreateDisplayAbbreviatedNameString()
    }
    local the_name = dialog:CreateEdit(0, 22):SetWidth(200)
        :SetText(config.abbreviate and name.abbrev or name.full)
    local abbrev_checkbox = dialog:CreateCheckbox(0, 47):SetText("Abbreviate staff name")
        :SetWidth(150):SetCheck(config.abbreviate and 1 or 0)
        :AddHandleCommand(function(self)
            the_name:SetText(self:GetCheck() == 1 and name.abbrev or name.full)
        end)
    dialog:CreateOkButton()
    dialog:CreateCancelButton()
    dialog_set_position(dialog)
    dialog:RegisterHandleOkButtonPressed(function()
        config.abbreviate = (abbrev_checkbox:GetCheck() == 1)
    end)
    dialog:RegisterInitWindow(function() the_name:SetFocus() end)
    dialog:RegisterCloseWindow(function(self) dialog_save_position(self) end)
    return (dialog:ExecuteModal(nil) == finale.EXECMODAL_OK), the_name:GetText()
end

function choose_name_index(name_list)
    local dialog = mixin.FCXCustomLuaWindow():SetTitle(plugindef())
    dialog:CreateStatic(0, 0):SetText("Select cue name:"):SetWidth(100)
    -- menu item [0] is "*** new name ***"
    local staff_list = dialog:CreateListBox(0, 22):SetWidth(200):AddString("*** new name ***")
    for i, v in ipairs(name_list) do -- add all names in the extant list
        staff_list:AddString(v[1])
        if v[2] == config.cuename_item then staff_list:SetSelectedItem(i) end
    end
    make_info_button(dialog, 180, 0)
    dialog:CreateOkButton()
    dialog:CreateCancelButton()
    dialog_set_position(dialog)
    dialog:RegisterHandleOkButtonPressed(function()
        local idx = staff_list:GetSelectedItem()
        if idx ~= 0 then -- existing cuename chosen
            config.cuename_item = name_list[idx][2]
        end
    end)
    dialog:RegisterInitWindow(function() staff_list:SetKeyboardFocus() end)
    dialog:RegisterCloseWindow(function(self) dialog_save_position(self) end)
    return (dialog:ExecuteModal(nil) == finale.EXECMODAL_OK), staff_list:GetSelectedItem()
end

function create_new_expression(exp_name, category_number)
    local cat_def = finale.FCCategoryDef()
    cat_def:Load(category_number)
    local tfi = cat_def:CreateTextFontInfo()
    local str = finale.FCString()
    str.LuaString = "^fontTxt"
        .. tfi:CreateEnigmaString(finale.FCString()).LuaString
        .. exp_name
    local ted = mixin.FCMTextExpressionDef()
    ted:SaveNewTextBlock(str)
        :AssignToCategory(cat_def)
        :SetUseCategoryPos(true)
        :SetUseCategoryFont(true)
        :SaveNew()
    config.cuename_item = ted:GetItemNo() -- save new item number
end

function choose_destination_staff(source_staff)
    local staff_list = {} -- save number and name of other staves in the score
    local rgn = finale.FCMusicRegion()
    local max = layer.max_layers()
    rgn:SetCurrentSelection()
    rgn:SetFullMeasureStack() -- scan the whole stack
    local staff = finale.FCStaff()
    for staff_number in eachstaff(rgn) do
        if staff_number ~= source_staff then
            staff:Load(staff_number)
            local full_name = staff:CreateDisplayFullNameString().LuaString
            table.insert(staff_list, { staff_number, full_name } )
        end
    end
    local answer, saved, buttons = {}, {}, {}

    -- make the dialog
    local x_grid = { 210, 310, 370 }
    local y_step = 19
    local y_offset = finenv.UI():IsOnMac() and 3 or 0 -- + vertical offset for Mac edit boxes

    local dialog = mixin.FCXCustomLuaWindow():SetTitle(plugindef())
    dialog:CreateStatic(0, 20):SetText("Select cue name:"):SetWidth(100)
    local max_rows = #option.check + #option.integer + 2
    local num_rows = (#staff_list > (max_rows + 2)) and max_rows or (#staff_list + 2)
    local data_list = dialog:CreateDataList(0, 0):SetUseCheckboxes(true)
        :SetHeight(num_rows * y_step):AddColumn("Destination Staff(s):", 120)
    if finenv.UI():IsOnMac() then
        data_list:UseAlternatingBackgroundRowColors()
    end
    for _, v in ipairs(staff_list) do -- list all staff names
        local row = data_list:CreateRow()
        row:GetItemAt(0).LuaString = v[2]
    end

        local function set_check_state(state)
            for _, v in ipairs(option.check) do
                answer[v]:SetCheck(state)
            end
            data_list:SetKeyboardFocus()
        end
        local function set_list_state(state)
            for i, v in ipairs(staff_list) do
                local list_row = data_list:GetItemAt(i - 1)
                if state > -1 then -- "No Staves" = 0 / "All Staves" = 1
                    list_row.Check = (state == 1)
                else
                    rgn.StartStaff = v[1] -- is this staff number empty?
                    rgn.EndStaff = v[1]
                    list_row.Check = region_is_empty(rgn, 0)
                    if list_row.Check then
                        data_list:SelectLine(i - 1) -- update menu list visually
                    end
                end
            end
        end
        local function flip_check(idx)
            local ctl = answer[option.check[idx]]
            ctl:SetCheck((ctl:GetCheck() + 1) % 2)
        end
        local function flip_direction(add)
            local item = answer.stem_direction:GetSelectedItem() + add
            item = (item < 0) and 3 or (item % 4)
            answer.stem_direction:SetSelectedItem(item)
        end
        local function key_check(name)
            local ctl = answer[name]
            local s = ctl:GetText():lower()
            if  (   s:find("[^0-9]") or
                    (name:find("layer") and s:find("[^1-" .. max .. "]"))
                ) then
                if     s:find("[q?]") then info_dialog()
                elseif s:find("w") then flip_check(1)
                elseif s:find("e") then flip_check(2)
                elseif s:find("r") then flip_check(3)
                elseif s:find("t") then flip_check(4)
                elseif s:find("y") then flip_check(5)
                elseif s:find("u") then flip_check(6)
                elseif s:find("i") then flip_check(7)
                elseif s:find("o") then flip_check(8)
                elseif s:find("a") then set_check_state(1) -- check all
                elseif s:find("s") then set_check_state(0) -- check none
                elseif s:find("d") then set_list_state(1) -- all staves
                elseif s:find("f") then set_list_state(0) -- no staves
                elseif s:find("g") then set_list_state(-1) -- empty staves
                elseif s:find("z") then flip_direction(1) -- up/down stem
                elseif s:find("x") then flip_direction(-1)
                end
                ctl:SetText(saved[name]):SetKeyboardFocus()
            elseif s ~= "" then
                if name:find("layer") then s = s:sub(-1) -- 1-digit layer numbers
                else s = s:sub(1, 3) -- 3-digit percentage
                end
                ctl:SetText(s)
                saved[name] = s
            end
        end

    local y = y_step
    dialog:CreateStatic(x_grid[1], 0):SetText("Cue Options:"):SetWidth(150)
    for _, v in ipairs(option.check) do -- run through config boolean list
        answer[v] = dialog:CreateCheckbox(x_grid[1], y):SetText(v:gsub("_", " "))
        :SetWidth(120):SetCheck(config[v] and 1 or 0)
        y = y + y_step
    end
    for i, v in ipairs(option.integer) do -- run through config integer list
        dialog:CreateStatic(x_grid[1], y):SetText(v:gsub("_", " ") .. ":"):SetWidth(150)
        answer[v] = dialog:CreateEdit(x_grid[2], y - y_offset):SetInteger(config[v])
            :AddHandleCommand(function() key_check(v) end)
        answer[v]:SetWidth(i == 1 and 40 or 20) -- layer numbers thinner
        saved[v] = config[v]
        y = y + y_step
    end

    answer.stem_direction = dialog:CreatePopup(x_grid[1], y + 5):SetWidth(160)
    for _, v in ipairs(option.stem) do
        answer.stem_direction:AddString("Stems: " .. v)
    end
    answer.stem_direction:SetSelectedItem(config.freeze_up_down) -- 0-based index configure value

    -- buttons to PRESET checkboxes/data_list items
    for i, name in ipairs(option.button) do
        buttons[name] = dialog:CreateButton(x_grid[3], y_step * 2 * (i - 1)):SetWidth(80):SetText(name)
        if i < 3 then
            buttons[name]:AddHandleCommand(function() set_check_state(2 - i) end)
        else
            buttons[name]:AddHandleCommand(function() set_list_state(4 - i) end)
        end
    end
    make_info_button(dialog, x_grid[3] + 60, y_step * 11 + 3)

    -- run the dialog
    dialog:CreateOkButton()
    dialog:CreateCancelButton()
    dialog_set_position(dialog)
    local chosen_staves = {} -- save user choice of destination staves

    dialog:RegisterHandleOkButtonPressed(function()
        local selection = data_list:GetSelectedLine() + 1
        if selection > 0 then -- user selected a line (not necessairly the line's checkbox)
            table.insert(chosen_staves, staff_list[selection][1])
        end
        for i, v in ipairs(staff_list) do -- check every staff for ticked boxes
            local list_row = data_list:GetItemAt(i - 1)
            if list_row.Check and i ~= selection then
                table.insert(chosen_staves, v[1])
            end
        end
        -- save config values
        for _, v in ipairs(option.check) do
            config[v] = (answer[v]:GetCheck() == 1)
        end
        for _, v in ipairs(option.integer) do
            config[v] = answer[v]:GetInteger()
        end
        if config.source_layer ~= config.cuenote_layer then
            config.rest_layer = config.source_layer
        else -- make sure the whole-bar rest is in a different layer from the cuenotes
            config.rest_layer = (config.source_layer % max) + 1
        end
        config.freeze_up_down = answer.stem_direction:GetSelectedItem() -- 0-based index
    end)
    dialog:RegisterInitWindow(function() data_list:SetKeyboardFocus() end)
    dialog:RegisterCloseWindow(function(self) dialog_save_position(self) end)
    return (dialog:ExecuteModal(nil) == finale.EXECMODAL_OK), chosen_staves
end

function fix_text_expressions(region)
    local expressions = finale.FCExpressions()
    expressions:LoadAllForRegion(region)
    for expression in eachbackwards(expressions) do
        if expression.StaffGroupID == 0 then -- note-attached expressions only
            if config.copy_expressions then -- keep them and switch to cuenote layer
                expression.LayerAssignment = config.cuenote_layer
                expression.ScaleWithEntry = true -- and scale to smaller noteheads
                expression:Save()
            else
                expression:DeleteData() -- otherwise delete them
            end
        end
    end
end

function get_away_from_middle_is_up(region)
    if config.freeze_up_down ~= freeze.away_from_middle then return false end
    local total_displacement = 0
    for entry in eachentry(region) do
        if entry:IsNote() then
            for note in each(entry) do
                total_displacement = total_displacement + (note:CalcStaffPosition() + 4)
            end
        end
    end
    return total_displacement >= 0
end

function freeze_tuplets_and_ties(entry, up)
    if entry:IsNote() and entry:IsTied() then
        for note in each(entry) do
            if note.Tie then
                local tie_mod = finale.FCTieMod(finale.TIEMODTYPE_TIESTART)
                tie_mod.TieDirection = up and finale.TIEMODDIR_OVER or finale.TIEMODDIR_UNDER
                tie_mod:SaveAt(note)
            end
        end
    end

    if entry.TupletStartFlag then
        for tuplet in each(entry:CreateTuplets()) do
            tuplet.PlacementMode = finale.TUPLETPLACEMENT_STEMSIDE
            tuplet:Save()
        end
    end
end

function freeze_slurs(region, up)
    local marks = finale.FCSmartShapeMeasureMarks()
    marks:LoadAllForRegion(region, true)
    for m in each(marks) do
        local shape = m:CreateSmartShape()
        if shape:IsSolidSlur() then
            shape:SetShapeType(up and finale.SMARTSHAPE_SLURUP or finale.SMARTSHAPE_SLURDOWN)
            shape:Save()
        elseif shape:IsDashedSlur() then
            shape:SetShapeType(up and finale.SMARTSHAPE_DASHEDSLURUP or finale.SMARTSHAPE_DASHEDSLURDOWN)
            shape:Save()
        end
    end
end

function copy_to_destination(source_region, destination_staff)
    local destination_region = mixin.FCMMusicRegion()
    destination_region:SetRegion(source_region):CopyMusic() -- copy the original
    destination_region:SetStartStaff(destination_staff):SetEndStaff(destination_staff)

    if not region_is_empty(destination_region, 0)
        and dont_overwrite_existing_music(destination_staff) then
            destination_region:ReleaseMusic() -- clear memory
            return false -- and go home
    elseif region_is_empty(source_region, config.source_layer) then
        destination_region:ReleaseMusic() -- clear memory
        show_error("no_notes_in_source_layer")
        return false -- and go home
    end
    -- otherwise carry on ...
    destination_region:PasteMusic()   -- paste the copy
    destination_region:ReleaseMusic() -- and release memory
    for layer_number = 1, layer.max_layers() do     -- clear out non-source layers
        if layer_number ~= config.source_layer then
            layer.clear(destination_region, layer_number)
        end
    end

    -- swap source_layer with cuenote_layer & fix clef
    layer.swap(destination_region, config.source_layer, config.cuenote_layer)
    if not config.copy_clef then
        clef.restore_default_clef(destination_region.StartMeasure, destination_region.EndMeasure, destination_staff)
    end

    local away_from_middle_is_up = get_away_from_middle_is_up(destination_region)

    -- mute / set to % size / delete articulations? / freeze stems? / delete lyrics?
    for entry in eachentrysaved(destination_region) do
        if entry:IsNote() and config.mute_cuenotes then
            entry.Playback = false
        end
        entry:SetNoteDetailFlag(true)
        mixin.FCMEntryAlterMod()
            :SetNoteEntry(entry)
            :SetResize(config.cuenote_percent)
            :Save()
        if entry.ArticulationFlag and not config.copy_articulations then
            for articulation in each(entry:CreateArticulations()) do
                articulation:DeleteData()
            end
            entry.ArticulationFlag = false
        end
        if entry.LyricFlag and not config.copy_lyrics then -- delete lyrics from copy
            local lyrics = { finale.FCChorusSyllable(), finale.FCSectionSyllable(), finale.FCVerseSyllable() }
            for _, v in ipairs(lyrics) do
                v:SetNoteEntry(entry)
                while v:LoadFirst() do
                    v:DeleteData()
                end
            end
        end
        if config.freeze_up_down > freeze.none then -- frozen stems requested
            entry.FreezeStem = true
            local freeze_stem_up = {
                true,
                false,
                away_from_middle_is_up
            }
            entry.StemUp = freeze_stem_up[config.freeze_up_down]
        else
            entry.FreezeStem = false
        end
        -- freeze ties and tuplets for "away from middle" stems
        if config.freeze_up_down == freeze.away_from_middle then
            freeze_tuplets_and_ties(entry, away_from_middle_is_up)
        end
    end

    -- delete or amend text expressions
    fix_text_expressions(destination_region)
    -- check smart shapes
    if not config.copy_smartshapes or not config.copy_slurs then
        for mark in loadallforregion(finale.FCSmartShapeMeasureMarks(), destination_region) do
            local shape = mark:CreateSmartShape()
            if  (shape:IsSlur() and not config.copy_slurs) or
                (not shape:IsSlur() and not config.copy_smartshapes) then
                shape:DeleteData()
            end
        end
    end
    if config.copy_slurs and config.freeze_up_down == freeze.away_from_middle then
        freeze_slurs(destination_region, away_from_middle_is_up)
    end
    -- delete chord symbols?
    if not config.copy_chords then
        for chord in loadallforregion(finale.FCChords(), destination_region) do
            if chord then chord:DeleteData() end
        end
    end

    -- create whole-note rest in rest_layer in each measure
    for measure = destination_region.StartMeasure, destination_region.EndMeasure do
        local notecell = finale.FCNoteEntryCell(measure, destination_staff)
        notecell:Load()
        local whole_note = notecell:AppendEntriesInLayer(config.rest_layer, 1) --   Append to rest_layer, add 1 entry
        if whole_note then
            whole_note.Duration = finale.WHOLE_NOTE
            whole_note.Legality = true
            whole_note:MakeRest()
            notecell:Save()
        end
    end
    return true
end

function new_expression_category(new_name)
    local category_id = 0
    if not finenv.IsRGPLua then  -- SaveNewWithType only works on RGPLua 0.58+
        return false, category_id   -- and crashes on JWLua
    end

    local new_category = mixin.FCMCategoryDef()
    new_category:Load(finale.DEFAULTCATID_TECHNIQUETEXT)
    local str = finale.FCString()
    str.LuaString = new_name
    new_category:SetName(str)
        :SetVerticalAlignmentPoint(finale.ALIGNVERT_STAFF_REFERENCE_LINE)
        :SetVerticalBaselineOffset(30)
        :SetHorizontalAlignmentPoint(finale.ALIGNHORIZ_CLICKPOS)
        :SetHorizontalOffset(-18)
    -- make font slightly smaller than standard TECHNIQUE expression
    local tfi = new_category:CreateTextFontInfo()
    tfi.Size = tfi.Size - config.cue_font_smaller
    new_category:SetTextFontInfo(tfi)
    local ok = new_category:SaveNewWithType(finale.DEFAULTCATID_TECHNIQUETEXT)
    if ok then
        category_id = new_category:GetID()
    end
    return ok, category_id
end

function create_cue_notes()
    local cue_names = { } -- compile NAME/ItemNo of all pre-existing CUE_NAME expressions
    local source_region = finenv.Region()
    local start_staff = source_region.StartStaff
    -- declare other local variables
    local ok, name_index, new_expression, destination_staves

    if source_region:CalcStaffSpan() > 1 then
        return show_error("only_one_staff")
    elseif region_is_empty(source_region, 0) then
        return show_error("empty_region")
    end

    local cat_ID = -1 -- assume the CUE_NAMES category doesn't exist
    local cat_defs = finale.FCCategoryDefs()
    cat_defs:LoadAll()
    for cat in each(cat_defs) do
        if cat:CreateName().LuaString == config.cue_category_name then
            cat_ID = cat.ID
            break
        end
    end

    local expression_defs = finale.FCTextExpressionDefs()
    expression_defs:LoadAll()
    if cat_ID > -1 then -- expression category already exists
        for text_def in each(expression_defs) do -- collate existing cue names
            if text_def.CategoryID == cat_ID then
                local str = text_def:CreateTextString()
                str:TrimEnigmaTags()
                table.insert(cue_names, { str.LuaString, text_def.ItemNo } ) -- save expresion NAME and ItemNo
            end
        end
        table.sort(cue_names, function(a, b) return string.lower(a[1]) < string.lower(b[1]) end)
    end

    -- test for pre-existing names
    if cat_ID < 0 then -- create a new Text Expression Category
        ok, cat_ID = new_expression_category(config.cue_category_name)
        if not ok then -- creation failed
            return show_error("first_make_expression_category")
        end
    end
    -- choose cue name
    ok, name_index = choose_name_index(cue_names) -- saved in config.cuename_item
    if not ok then return end
    if name_index == 0 then	-- USER wants to provide a new cue name
        ok, new_expression = new_cue_name(start_staff)
        if not ok or new_expression == "" then return end
        create_new_expression(new_expression, cat_ID) -- ID saved in config.cuename_item
    end
    -- choose destination staff
    ok, destination_staves = choose_destination_staff(start_staff)
    if not ok then return end
    if region_is_empty(source_region, config.source_layer) then
        return show_error("no_notes_in_source_layer")
    end
    -- make the cue copy
    for _, one_staff in ipairs(destination_staves) do
        if copy_to_destination(source_region, one_staff) then
            mixin.FCMExpression() -- "name" the cue
                :SetStaff(one_staff)
                :SetVisible(true)
                :SetMeasurePos(0)
                :SetScaleWithEntry(false) -- could also (possibly) be true!  
                :SetPartAssignment(true)
                :SetScoreAssignment(true)
                :SetID(config.cuename_item)
                :SaveNewToCell(finale.FCCell(source_region.StartMeasure, one_staff))
        end
    end
    source_region:SetInDocument()
end

function flip_cue_notes()
    local region = finenv.Region()
    if region_is_empty(region, config.cuenote_layer) then
        show_error("no_cue_notes")
        return
    end

    for staff = region.StartStaff, region.EndStaff do
        local freeze_up = nil
        local staff_region = mixin.FCMMusicRegion()
            :SetRegion(region)
            :SetStartStaff(staff)
            :SetEndStaff(staff)
        for entry in eachentrysaved(staff_region, config.cuenote_layer) do
            if entry:IsNote() and not entry.FreezeStem then goto next_staff end
            entry.StemUp = not entry.StemUp
            if freeze_up == nil then freeze_up = entry.StemUp end
            freeze_tuplets_and_ties(entry, freeze_up)
        end
        freeze_slurs(staff_region, freeze_up)
        ::next_staff::
    end
end

if action == "flip" then
    flip_cue_notes()
else
    create_cue_notes()
end