Further reducing duplicate code with FCXCustomLuaWindow

[rpatters1]

This is mainly an issue for discussion with @ThistleSifter.

I feel pretty strongly about all the following as usability features.

1. All dialogs should be modeless.
2. All scripts should nevertheless support JW Lua unless using features from the PDK Framework that are not available in JW Lua. In JW Lua they must be modal and the rest of these items do not apply. However for modal dialogs, there may be a requirement that a selected region exist when modeless dialogs probably do not have the same requirement.
3. All dialogs should remember their previous values and position. (Already implemented.)
4. Use of the modifier keys when the script is first called should cause the OK button to close the dialog. Otherwise not. If the user cancels out, it is as if the dialog were never called.
5. Use of the modifier keys after the script is first called should skip the dialog altogether and use the last settings from the dialog.
6. Use of the modifier keys when closing the dialog sets RetainLuaState to false so that the script can start fresh. (Already implemented.)

To clarify point 4: it allows two modes for using the script. One basically sets the value you want the first time and then you never have to see the dialog again. The other mode leaves the dialog open on the desktop at all times for easy access. Point 4 allows for instant removal of the dialog the first time after the values are set.

To implement these, I am finding that I always need a block of code something like this:

function do_my_plugin()
 local keys_on_invoke = finenv.QueryInvokedModifierKeys and (finenv.QueryInvokedModifierKeys(finale.CMDMODKEY_ALT) or finenv.QueryInvokedModifierKeys(finale.CMDMODKEY_SHIFT))
 if keys_on_invoke and global_dialog then
 global_dialog:on_ok()
 return
 end
 if not global_dialog then
 global_dialog = create_dialog_box()
 end
 if finenv.IsRGPLua then
 if global_dialog.OkButtonCanClose then -- OkButtonCanClose will be nil before 0.56 and true (the default) after
 global_dialog.OkButtonCanClose = keys_on_invoke
 end
 if global_dialog:ShowModeless() then
 finenv.RetainLuaState = true
 end
 else
 if finenv.Region():IsEmpty() then
 finenv.UI():AlertInfo("Please select a music region before running this script.", "Selection Required")
 return
 end
 global_dialog:ExecuteModal(nil)
 end
end

Is there a sensible way to move this code into FCXCustomLuaWindow so that all we have to do is this?

function do_my_plugin()
 if not global_dialog then
 global_dialog = create_dialog_box()
 end
 global_dialog:ShowFunction() -- this could be ShowModeless if it makes sense to put it there. Otherwise some new function name.
end

[ThistleSifter]

Sure, that's easy to do. Pretty much anything is possible, the question is whether it's a good idea (seems okay to me) and how to implement it. In my mind, it's mainly a question of how much should be configurable and how opinionated to make it. I admit that I'm hardly a power user and I'm not overly familiar with what goes on in the plugin community and what the accepted practices are, so I'm flying somewhat blind here.

To keep it simple, I'm just going to call the proposed new method Run().

1. All plugins should be modeless
I dunno, I guess there could be some situations where someone might want a modal. It'd only take an extra 30 characters to add support for that in Run() anyway.

2. All scripts should nevertheless support JW Lua...
Agreed, but what about plugins that don't require music region selection? Presumably Run() should take that into account in some fashion.

3. All dialogs should remember their previous values and position.
Just a quick note that technically this is WIP, since we still need a real solution for controls that isn't a workaround. I have a big project taking up my time at the moment but that should be done in about a week and a half, so I'll work on it then.

4. Use of the modifier keys...
5. Use of the modifier keys after the script is first called...
It's never actually occurred to me to use modifier keys when using a plugin (not that I've used many) so I'll take your word for it.

The main issue that came up in my quick mental sketching of Run() was what happens if the author wants to do something with the modal result, if it's shown as a modal?

Also, a quick question about these lines from the snippet above:

 if global_dialog:ShowModeless() then
 finenv.RetainLuaState = true
 end

Since FCXCustomLuaWindow.ShowModeless takes care of modeless registration, do we have to wait until after ShowModeless returns in order to set RetainLuaState?

[rpatters1]

I imagine Run() would have to have options. Whether they are optional parameters or properties on the dialog is an open question. I would hate to see many of either, if I'm honest. But on balance I think I prefer property settings. Others may feel the reverse.

I've already thought of a future project that ought to be modal, so yes there are times the dialog should be modal in any case. This could be an explicit call to ExecuteModal of course, which also gives access to the result. For Run(), I was imagining ExecuteModal only as a substitute for JW Lua support. In that case, the code that does work is likely tied to the ok button event and so the modal result is not important. But perhaps there is a reason to return it.

Use of modifier keys to skip dialogs is a convention that Tobias, Jari, and I came up with early on in plugin development (now over 20 years ago...yikes.) I am not certain how far either of them went with it, but all my plugins behave that way. I'm a strong believer that no UI is better than any conceivable other UI. BTW I've been extending this concept over the years to allow other mod-key based behavior. For example my Beam Selection plugin (and now the beam_selection.lua script on this repo) actually unbeam the selection if the modifier key is held when invoked.

Another feature that perhaps should be an option is to allow for the OK button to always close the dialog, not just if modifier keys are held down. I mean, tbh I'm not sure if under my scenario opening it with modifier keys the first time should not cause OK to close the dialog every time it's opened until the Lua state ends. If the goal is to have no-modifier and with-modifier use be two different usage modes, under my conditions there is no way to open the dialog after the first time and have OK close the dialog. OTOH, as-is allows for transition between the two modes. I'm not sure which is more important.

ShowModeless always returns basically immediately, so I don't think it matters. But if for whatever reason it fails, I think it is better not to retain the state. It was more important when FCXCustomLuaWindow.ShowModeless was not automatically registering the dialog. (Fwiw: the reason RGP Lua can't do this automatically itself is that ShowModeless is a PDK Framework call. The PDK Framework does not know about RGP Lua, but it has to call back into RGP Lua to notify it when the dialog closes. What registration does is set up a callback function inside the dialog instance that calls back into RGP Lua.)