Jump to content

FCMCustomLuaWindow

Summary of Modifications

  • Methods that returned a boolean to indicate success/failure now throw an error instead.
  • Window is automatically registered with finenv.RegisterModelessDialog when ShowModeless is called.
  • All Register* methods (apart from RegisterHandleControlEvent) have accompanying Add* and Remove* methods to enable multiple handlers to be added per event.
  • Handlers for all window events (ie not control events) recieve the window object as the first argument.
  • Control handlers are passed original object to preserve mixin data.
  • Added custom callback queue which can be used by custom events to add dispatchers that will run with the next control event.
  • Added HasBeenShown method for checking if the window has been previously shown.
  • Added methods for the automatic restoration of previous window position when showing (RGPLua > 0.60) for use with finenv.RetainLuaState and modeless windows.
  • Added DebugClose option to assist with debugging (if ALT or SHIFT key is pressed when window is closed and debug mode is enabled, finenv.RetainLuaState will be set to false).
  • Measurement unit can be set on the window or changed by the user through a FCXCtrlMeasurementUnitPopup.
  • Windows also have the option of inheriting the parent window’s measurement unit when opening.
  • Introduced a MeasurementUnitChange event.
  • All controls with an UpdateMeasurementUnit method will have that method called upon a measurement unit change to allow them to immediately update their displayed values without needing to wait for a MeasurementUnitChange event.

Functions

Init

fcmcustomluawindow.Init(self)

View source

[Internal]

Input Type Description
self FCMCustomLuaWindow

RegisterHandleCommand

fcmcustomluawindow.RegisterHandleCommand(self, callback)

View source

[Breaking Change] [Fluid] [Override]

Override Changes:

  • Ensures that the handler is passed the original control object.
  • Throws an error instead of returning a boolean for success/failure.
Input Type Description
self FCMCustomLuaWindow
callback function See FCCustomLuaWindow.HandleCommand in the PDK for callback signature.

AddHandleCommand

fcmcustomluawindow.AddHandleCommand(self, callback)

View source

[Fluid]

Adds a handler. Similar to the equivalent RegisterHandleCommand except there is no limit to the number of handlers that can be added. Added handlers are called in the order they are added after the registered handler, if there is one.

Input Type Description
self FCMCustomLuaWindow
callback function See FCCustomLuaWindow.HandleCommand in the PDK for callback signature.

RemoveHandleCommand

fcmcustomluawindow.RemoveHandleCommand(self, callback)

View source

[Fluid]

Removes a handler added by AddHandleCommand.

Input Type Description
self FCMCustomLuaWindow
callback function

RegisterHandleDataListCheck

fcmcustomluawindow.RegisterHandleDataListCheck(self, callback)

View source

[Breaking Change] [Fluid] [Override]

Override Changes:

  • Ensures that the handler is passed the original control object.
  • Throws an error instead of returning a boolean for success/failure.
Input Type Description
self FCMCustomLuaWindow
callback function See FCCustomLuaWindow.HandleDataListCheck in the PDK for callback signature.

AddHandleDataListCheck

fcmcustomluawindow.AddHandleDataListCheck(self, callback)

View source

[Fluid]

Adds a handler. Similar to the equivalent RegisterHandleDataListCheck except there is no limit to the number of handlers that can be added. Added handlers are called in the order they are added after the registered handler, if there is one.

Input Type Description
self FCMCustomLuaWindow
callback function See FCCustomLuaWindow.HandleDataListCheck in the PDK for callback signature.

RemoveHandleDataListCheck

fcmcustomluawindow.RemoveHandleDataListCheck(self, callback)

View source

[Fluid]

Removes a handler added by AddHandleDataListCheck.

Input Type Description
self FCMCustomLuaWindow
callback function

RegisterHandleDataListSelect

fcmcustomluawindow.RegisterHandleDataListSelect(self, callback)

View source

[Breaking Change] [Fluid] [Override]

Override Changes:

  • Ensures that the handler is passed the original control object.
  • Throws an error instead of returning a boolean for success/failure.
Input Type Description
self FCMCustomLuaWindow
callback function See FCCustomLuaWindow.HandleDataListSelect in the PDK for callback signature.

AddHandleDataListSelect

fcmcustomluawindow.AddHandleDataListSelect(self, callback)

View source

[Fluid]

Adds a handler. Similar to the equivalent RegisterHandleDataListSelect except there is no limit to the number of handlers that can be added. Added handlers are called in the order they are added after the registered handler, if there is one.

Input Type Description
self FCMCustomLuaWindow
callback function See FCCustomLuaWindow.HandleDataListSelect in the PDK for callback signature.

RemoveHandleDataListSelect

fcmcustomluawindow.RemoveHandleDataListSelect(self, callback)

View source

[Fluid]

Removes a handler added by AddHandleDataListSelect.

Input Type Description
self FCMCustomLuaWindow
callback function

RegisterHandleUpDownPressed

fcmcustomluawindow.RegisterHandleUpDownPressed(self, callback)

View source

[Breaking Change] [Fluid] [Override]

Override Changes:

  • Ensures that the handler is passed the original control object.
  • Throws an error instead of returning a boolean for success/failure.
Input Type Description
self FCMCustomLuaWindow
callback function See FCCustomLuaWindow.HandleUpDownPressed in the PDK for callback signature.

AddHandleUpDownPressed

fcmcustomluawindow.AddHandleUpDownPressed(self, callback)

View source

[Fluid]

Adds a handler. Similar to the equivalent RegisterHandleUpDownPressed except there is no limit to the number of handlers that can be added. Added handlers are called in the order they are added after the registered handler, if there is one.

Input Type Description
self FCMCustomLuaWindow
callback function See FCCustomLuaWindow.HandleUpDownPressed in the PDK for callback signature.

RemoveHandleUpDownPressed

fcmcustomluawindow.RemoveHandleUpDownPressed(self, callback)

View source

[Fluid]

Removes a handler added by AddHandleUpDownPressed.

Input Type Description
self FCMCustomLuaWindow
callback function

CancelButtonPressed

fcmcustomluawindow.CancelButtonPressed(self)

View source

[Callback Template] [Override]

Override Changes:

  • Receives the window object as the first parameter.
Input Type Description
self FCMCustomLuaWindow

RegisterHandleCancelButtonPressed

fcmcustomluawindow.RegisterHandleCancelButtonPressed(self, callback)

View source

[Breaking Change] [Fluid] [Override]

Override Changes:

  • Uses overridden callback signature.
  • Throws an error instead of returning a boolean for success/failure.
Input Type Description
self FCMCustomLuaWindow
callback function See CancelButtonPressed for callback signature.

AddHandleCancelButtonPressed

fcmcustomluawindow.AddHandleCancelButtonPressed(self, callback)

View source

[Fluid]

Adds a handler. Similar to the equivalent RegisterCancelButtonPressed except there is no limit to the number of handlers that can be added. Added handlers are called in the order they are added after the registered handler, if there is one.

Input Type Description
self FCMCustomLuaWindow
callback function See CancelButtonPressed for callback signature.

RemoveHandleCancelButtonPressed

fcmcustomluawindow.RemoveHandleCancelButtonPressed(self, callback)

View source

[Fluid]

Removes a handler added by AddHandleCancelButtonPressed.

Input Type Description
self FCMCustomLuaWindow
callback function

OkButtonPressed

fcmcustomluawindow.OkButtonPressed(self)

View source

[Callback Template] [Override]

Override Changes:

  • Receives the window object as the first parameter.
Input Type Description
self FCMCustomLuaWindow

RegisterHandleOkButtonPressed

fcmcustomluawindow.RegisterHandleOkButtonPressed(self, callback)

View source

[Breaking Change] [Fluid] [Override]

Override Changes:

  • Uses overridden callback signature.
  • Throws an error instead of returning a boolean for success/failure.
Input Type Description
self FCMCustomLuaWindow
callback function See OkButtonPressed for callback signature.

AddHandleOkButtonPressed

fcmcustomluawindow.AddHandleOkButtonPressed(self, callback)

View source

[Fluid]

Adds a handler. Similar to the equivalent RegisterOkButtonPressed except there is no limit to the number of handlers that can be added. Added handlers are called in the order they are added after the registered handler, if there is one.

Input Type Description
self FCMCustomLuaWindow
callback function See OkButtonPressed for callback signature.

RemoveHandleOkButtonPressed

fcmcustomluawindow.RemoveHandleOkButtonPressed(self, callback)

View source

[Fluid]

Removes a handler added by AddHandleOkButtonPressed.

Input Type Description
self FCMCustomLuaWindow
callback function

InitWindow

fcmcustomluawindow.InitWindow(self)

View source

[Callback Template] [Override]

Override Changes:

  • Receives the window object as the first parameter.
Input Type Description
self FCMCustomLuaWindow

RegisterInitWindow

fcmcustomluawindow.RegisterInitWindow(self, callback)

View source

[Breaking Change] [Fluid] [Override]

Override Changes:

  • Uses overridden callback signature.
  • Throws an error instead of returning a boolean for success/failure.
Input Type Description
self FCMCustomLuaWindow
callback function See InitWindow for callback signature.

AddInitWindow

fcmcustomluawindow.AddInitWindow(self, callback)

View source

[Fluid]

Adds a handler. Similar to the equivalent RegisterInitWindow except there is no limit to the number of handlers that can be added. Added handlers are called in the order they are added after the registered handler, if there is one.

Input Type Description
self FCMCustomLuaWindow
callback function See InitWindow for callback signature.

RemoveInitWindow

fcmcustomluawindow.RemoveInitWindow(self, callback)

View source

[Fluid]

Removes a handler added by AddInitWindow.

Input Type Description
self FCMCustomLuaWindow
callback function

CloseWindow

fcmcustomluawindow.CloseWindow(self)

View source

[Callback Template] [Override]

Override Changes:

  • Receives the window object as the first parameter.
Input Type Description
self FCMCustomLuaWindow

RegisterCloseWindow

fcmcustomluawindow.RegisterCloseWindow(self, callback)

View source

[Breaking Change] [Fluid] [Override]

Override Changes:

  • Uses overridden callback signature.
  • Throws an error instead of returning a boolean for success/failure.
Input Type Description
self FCMCustomLuaWindow
callback function See CloseWindow for callback signature.

AddCloseWindow

fcmcustomluawindow.AddCloseWindow(self, callback)

View source

[Fluid]

Adds a handler. Similar to the equivalent RegisterCloseWindow except there is no limit to the number of handlers that can be added. Added handlers are called in the order they are added after the registered handler, if there is one.

Input Type Description
self FCMCustomLuaWindow
callback function See CloseWindow for callback signature.

RemoveCloseWindow

fcmcustomluawindow.RemoveCloseWindow(self, callback)

View source

[Fluid]

Removes a handler added by AddCloseWindow.

Input Type Description
self FCMCustomLuaWindow
callback function

QueueHandleCustom

fcmcustomluawindow.QueueHandleCustom(self, callback)

View source

[Fluid] [Internal] Adds a function to the queue which will be executed in the same context as an event handler at the next available opportunity. Once called, the callback will be removed from tbe queue (i.e. it will only be called once). For multiple calls, the callback will need to be added to the queue again. The callback will not be passed any arguments.

Input Type Description
self FCMCustomLuaWindow
callback function

RegisterHandleControlEvent

fcmcustomluawindow.RegisterHandleControlEvent(self, control, callback)

View source

[>= v0.56] [Breaking Change] [Fluid] [Override]

Override Changes:

  • Ensures that the handler is passed the original control object.
  • Throws an error instead of returning a boolean for success/failure.
Input Type Description
self FCMCustomLuaWindow
control FCMControl
callback function See FCCustomLuaWindow.HandleControlEvent in the PDK for callback signature.

HandleTimer

fcmcustomluawindow.HandleTimer(self, timerid)

View source

[Breaking Change] [Callback Template] [Override]

Override Changes:

  • Receives the window object as the first parameter.
Input Type Description
self FCMCustomLuaWindow
timerid number

RegisterHandleTimer

fcmcustomluawindow.RegisterHandleTimer(self, callback)

View source

[>= v0.56] [Breaking Change] [Fluid] [Override]

Override Changes:

  • Uses overridden callback signature.
  • Throws an error instead of returning a boolean for success/failure.
Input Type Description
self FCMCustomLuaWindow
callback function See HandleTimer for callback signature (note the change in arguments).

AddHandleTimer

fcmcustomluawindow.AddHandleTimer(self, timerid, callback)

View source

[>= v0.56] [Fluid]

Adds a handler for a timer. Handlers added by this method will be called after the registered handler, if there is one. If a handler is added for a timer that hasn’t been set, the timer ID will no longer be available to GetNextTimerID and SetNextTimer.

Input Type Description
self FCMCustomLuaWindow
timerid number
callback function See HandleTimer for callback signature.

RemoveHandleTimer

fcmcustomluawindow.RemoveHandleTimer(self, timerid, callback)

View source

[>= v0.56] [Fluid]

Removes a handler added with AddHandleTimer.

Input Type Description
self FCMCustomLuaWindow
timerid number
callback function

SetTimer

fcmcustomluawindow.SetTimer(self, timerid, msinterval)

View source

[>= v0.56] [Fluid] [Override]

Override Changes:

  • Add setup to allow multiple handlers to be added for a timer.
Input Type Description
self FCCustomLuaWindow
timerid number
msinterval number

GetNextTimerID

fcmcustomluawindow.GetNextTimerID(self)

View source

[>= v0.56]

Returns the next available timer ID.

Input Type Description
self FCMCustomLuaWindow
Return type Description
number

SetNextTimer

fcmcustomluawindow.SetNextTimer(self, msinterval)

View source

[>= v0.56]

Sets a timer using the next available ID (according to GetNextTimerID) and returns the ID.

Input Type Description
self FCMCustomLuaWindow
msinterval number
Return type Description
number The ID of the newly created timer.

SetEnableAutoRestorePosition

fcmcustomluawindow.SetEnableAutoRestorePosition(self, enabled)

View source

[>= v0.60] [Fluid]

Enables/disables automatic restoration of the window’s position on subsequent openings. This is disabled by default.

Input Type Description
self FCMCustomLuaWindow
enabled boolean

GetEnableAutoRestorePosition

fcmcustomluawindow.GetEnableAutoRestorePosition(self)

View source

[>= v0.60]

Returns whether automatic restoration of window position is enabled.

Input Type Description
self FCMCustomLuaWindow
Return type Description
boolean true if enabled, false if disabled.

SetRestorePositionData

fcmcustomluawindow.SetRestorePositionData(self, x, y, width, height)

View source

[>= v0.60] [Fluid] [Override]

Override Changes:

  • If this method is called while the window is closed, the new position data will be used in automatic position restoration when window is next shown.
Input Type Description
self FCMCustomLuaWindow
x number
y number
width number
height number

SetRestorePositionOnlyData

fcmcustomluawindow.SetRestorePositionOnlyData(self, x, y)

View source

[>= v0.60] [Fluid] [Override]

Override Changes:

  • If this method is called while the window is closed, the new position data will be used in automatic position restoration when window is next shown.
Input Type Description
self FCMCustomLuaWindow
x number
y number

SetEnableDebugClose

fcmcustomluawindow.SetEnableDebugClose(self, enabled)

View source

[Fluid]

If enabled and in debug mode, when the window is closed with either ALT or SHIFT key pressed, finenv.RetainLuaState will be set to false. This is done before CloseWindow handlers are called. This is disabled by default.

Input Type Description
self FCMCustomLuaWindow
enabled boolean

GetEnableDebugClose

fcmcustomluawindow.GetEnableDebugClose(self)

View source

Returns the enabled state of the DebugClose option.

Input Type Description
self FCMCustomLuaWindow
Return type Description
boolean true if enabled, false if disabled.

SetRestoreControlState

fcmcustomluawindow.SetRestoreControlState(self, enabled)

View source

[Fluid]

Enables or disables the automatic restoration of control state on subsequent showings of the window. This is disabled by default.

Input Type Description
self FCMCustomLuaWindow
enabled boolean true to enable, false to disable.

GetRestoreControlState

fcmcustomluawindow.GetRestoreControlState(self)

View source

Checks if control state restoration is enabled.

Input Type Description
self FCMCustomLuaWindow
Return type Description
boolean true if enabled, false if disabled.

HasBeenShown

fcmcustomluawindow.HasBeenShown(self)

View source

Checks if the window has been shown at least once prior, either as a modal or modeless.

Input Type Description
self FCMCustomLuaWindow
Return type Description
boolean true if it has been shown, false if not

ExecuteModal

fcmcustomluawindow.ExecuteModal(self, parent)

View source

[Override]

Override Changes:

  • If a parent window is passed and the UseParentMeasurementUnit setting is enabled, this window’s measurement unit is automatically changed to match the parent window.
  • Restores the previous position if AutoRestorePosition is enabled.
Input Type Description
self FCMCustomLuaWindow
parent `FCCustomWindow FCMCustomWindow
Return type Description
number

ShowModeless

fcmcustomluawindow.ShowModeless(self)

View source

[Override]

Override Changes:

  • Automatically registers the dialog with finenv.RegisterModelessDialog.
  • Restores the previous position if AutoRestorePosition is enabled.
Input Type Description
self FCMCustomLuaWindow
Return type Description
boolean

RunModeless

fcmcustomluawindow.RunModeless(self, selection_not_required, default_action_override)

View source

[Fluid]

Runs the window as a self-contained modeless plugin, performing the following steps:

  • The first time the plugin is run, if ALT or SHIFT keys are pressed, sets OkButtonCanClose to true
  • On subsequent runnings, if ALT or SHIFT keys are pressed the default action will be called without showing the window
  • The default action defaults to the function registered with RegisterHandleOkButtonPressed
  • If in JWLua, the window will be shown as a modal and it will check that a music region is currently selected
Input Type Description
self FCMCustomLuaWindow
selection_not_required (optional) boolean If true and showing as a modal, will skip checking if a region is selected.
default_action_override (optional) `boolean function`

GetMeasurementUnit

fcmcustomluawindow.GetMeasurementUnit(self)

View source

Returns the window’s current measurement unit.

Input Type Description
self FCMCustomLuaWindow
Return type Description
number The value of one of the finale MEASUREMENTUNIT constants.

SetMeasurementUnit

fcmcustomluawindow.SetMeasurementUnit(self, unit)

View source

[Fluid]

Sets the window’s current measurement unit. Millimeters are not supported.

All controls that have an UpdateMeasurementUnit method will have that method called to allow them to immediately update their displayed measurement unit immediately without needing to wait for a MeasurementUnitChange event.

Input Type Description
self FCMCustomLuaWindow
unit number One of the finale MEASUREMENTUNIT constants.

GetMeasurementUnitName

fcmcustomluawindow.GetMeasurementUnitName(self)

View source

Returns the name of the window’s current measurement unit.

Input Type Description
self FCMCustomLuaWindow
Return type Description
string

GetUseParentMeasurementUnit

fcmcustomluawindow.GetUseParentMeasurementUnit(self)

View source

Returns a boolean indicating whether this window will use the measurement unit of its parent window when opened.

Input Type Description
self FCMCustomLuaWindow
Return type Description
boolean

SetUseParentMeasurementUnit

fcmcustomluawindow.SetUseParentMeasurementUnit(self, enabled)

View source

[Fluid]

Sets whether to use the parent window’s measurement unit when opening this window. Default is enabled.

Input Type Description
self FCMCustomLuaWindow
enabled boolean

HandleMeasurementUnitChange

fcmcustomluawindow.HandleMeasurementUnitChange(self, last_unit)

View source

[Callback Template]

Template for MeasurementUnitChange handlers.

Input Type Description
self FCMCustomLuaWindow
last_unit number The window’s previous measurement unit.

AddHandleMeasurementUnitChange

fcmcustomluawindow.AddHandleMeasurementUnitChange(self, callback)

View source

[Fluid]

Adds a handler for a change in the window’s measurement unit. The even will fire when:

  • The window is created (if the measurement unit is not finale.MEASUREMENTUNIT_DEFAULT)
  • The measurement unit is changed by the user via a FCXCtrlMeasurementUnitPopup
  • The measurement unit is changed programmatically (if the measurement unit is changed within a handler, that same handler will not be called again for that change.)
Input Type Description
self FCMCustomLuaWindow
callback function See HandleMeasurementUnitChange for callback signature.

RemoveHandleMeasurementUnitChange

fcmcustomluawindow.RemoveHandleMeasurementUnitChange(self, callback)

View source

[Fluid]

Removes a handler added with AddHandleMeasurementUnitChange.

Input Type Description
self FCMCustomLuaWindow
callback function

CreateMeasurementEdit

fcmcustomluawindow.CreateMeasurementEdit(self, x, y, control_name)

View source

Creates an FCXCtrlMeasurementEdit control.

Input Type Description
self FCMCustomLuaWindow
x number
y number
control_name (optional) string
Return type Description
FCXCtrlMeasurementEdit

CreateMeasurementUnitPopup

fcmcustomluawindow.CreateMeasurementUnitPopup(self, x, y, control_name)

View source

Creates a popup which allows the user to change the window’s measurement unit.

Input Type Description
self FCMCustomLuaWindow
x number
y number
control_name (optional) string
Return type Description
FCXCtrlMeasurementUnitPopup

CreatePageSizePopup

fcmcustomluawindow.CreatePageSizePopup(self, x, y, control_name)

View source

Creates a popup which allows the user to select a page size.

Input Type Description
self FCMCustomLuaWindow
x number
y number
control_name (optional) string
Return type Description
FCXCtrlPageSizePopup
Edit page on GitHub