You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/rgp-lua.md
+20-4Lines changed: 20 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -62,7 +62,7 @@ print (math.random(1, 10))
62
62
63
63
### The 'finale' namespace
64
64
65
-
All functionality that accesses Finale through the [Lua/PDK Framework](https://pdk.finalelua.com/) resides within the `finale` namespace. (Namespaces use the dot separator.)
65
+
All functionality that accesses Finale through the [Finale PDK Framework](https://pdk.finalelua.com/) resides within the `finale` namespace. (Namespaces use the dot separator.)
66
66
67
67
For example:
68
68
@@ -80,6 +80,18 @@ local sel_rgn = finenv.Region()
80
80
81
81
It also allows for direct interaction with the Lua plugin itself. A full description of available functions and properties can be found on the [finenv properties](/docs/rgp-lua/finenv-properties) page.
82
82
83
+
### The 'luosutils' library
84
+
85
+
_RGP Lua_ (starting in version 0.66) optionally preloads an embedded version of the [`luaosutils`](https://github.com/finale-lua/luaosutils) library. This is a library of functions specifically written to help Lua scripts running on Finale. It allows them to interact with the host operating system or the Finale executable in ways that are not directly supported by either the Lua language or the PDK Framework.
86
+
87
+
For _RGP Lua_ to preload `luaosutils`, set `finaleplugin.LoadLuaOSUtils = true` in your `plugindef` function. _RGP Lua_ does not load the library into a global namespace, however. You must explicitly `require` it into a varable of your choosing similar to what is shown in the following example.
88
+
89
+
```lua
90
+
localosutils=require('luaosutils')
91
+
```
92
+
93
+
The advantage to this approach is that you do not need to change the body of your script if you wish to use an external version of `luaosutils` instead of the version embedded in _RGP Lua_. Simply disable the `LoadLuaOSUtils` option in `plugindef` and the script will pick up the external version instead, provided it is in your `cpath` list. (_RGP Lua_ automatically adds the script’s running folder path to the `cpath` list.)
94
+
83
95
### The 'socket' namespace
84
96
85
97
_RGP Lua_ contains an embedded version of [`luasocket`](https://aiq0.github.io/luasocket/index.html). You can elect for it to be available in the `socket` namespace in one of the following ways.
@@ -126,7 +138,7 @@ If you are planning to use the standard installation of `luasocket`, you may be
126
138
127
139
### The 'utf8' namespace
128
140
129
-
Lua 5.3 added a standard `utf8` library for parsing utf8-encoded strings. Especially with the addition of SMuFL font support in Finale 27, parsing utf8 characters is an essential requirement for Finale scripts. _RGP Lua_(beginning in version 0.63) embeds the utf8 library from Lua 5.3 back-ported into Lua 5.2. The [Lua 5.3 Reference Manual](https://www.lua.org/manual/5.3/manual.html) describes how to use these functions. Any code you write for this version of `utf8` is source-compatible with Lua 5.3 and beyond.
141
+
Lua 5.3 and higher added a standard `utf8` library for parsing utf8-encoded strings. Especially with the addition of SMuFL font support in Finale 27, parsing utf8 characters is an essential requirement for Finale scripts. _RGP Lua_ embeds the `utf8` library from Lua 5.4.4 back-ported into Lua 5.2. The [Lua 5.4 Reference Manual](https://www.lua.org/manual/5.4/manual.html) describes how to use these functions. Any code you write for this version of `utf8` is source-compatible with Lua 5.4 and beyond. (This version is also backwards compatible with Lua 5.3 code.)
130
142
131
143
Dialog Boxes
132
144
------------
@@ -274,10 +286,14 @@ end
274
286
275
287
`dumpproperties()` creates a table consisting of all available properties for an object and their values. The keys in the table is the property names; the values in the table are the property values. Use the `pairsbykeys()` iterator (see below) to get the properties sorted in alphabetical order.
276
288
289
+
The first parameter to the function is an instance of a PDK Framework class.
290
+
291
+
The second parameter is optional, but can be used to specify if properties from base classes should be included as well. If omitted, properties from base classes are not included.
292
+
277
293
```lua
278
294
page=finale.FCPage()
279
295
page:Load(1)
280
-
properties=dumpproperties(page)
296
+
properties=dumpproperties(page, true) -- true: include base class properties
281
297
fork, vinpairsbykeys(properties) do
282
298
print (k, "=", v)
283
299
end
@@ -325,7 +341,7 @@ end
325
341
326
342
`eachentry()` feeds a `for` loop with all the note entry objects in a region, without saving them back. Mirror entries are processed with `eachentry()`.
327
343
328
-
First parameter to this function is the region to process, where you could use `finenv.Region()` to get the current selection.
344
+
The first parameter to this function is the region to process, where you could use `finenv.Region()` to get the current selection.
329
345
330
346
The second parameter is optional, but can be used to indicate the note entry layer(s) to load in Finale. The default is to load all visible layers. These values are available:
Copy file name to clipboardExpand all lines: docs/rgp-lua/finaleplugin-properties.md
+50Lines changed: 50 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -44,6 +44,22 @@ finaleplugin.NoStore = true
44
44
45
45
Default is `false`.
46
46
47
+
#### ExecuteAtStartup\* (boolean)
48
+
49
+
If this value is `true`_RGP Lua_ executes the script during Finale initialization. The script executes after the Finale application has completely finished initializing and is ready for user input. However, there is no guarantee in which order scripts will run if multiple scripts have requested to execute at startup. Some other 3rd-party plugins (notably TGTools, Patterson Plugins, and JWLuaMenu) rearrange Finale's menus at this time, and there is no guarantee in which order they run.
50
+
51
+
You can check if a script is running at startup with `finenv.QueryInitializationInProgress()`. Only the primary script runs at startup. If the script specifies `AdditionalMenuOptions`, the additional options are added to Finale's plugin menu, but they do not run at startup.
52
+
53
+
You can set `IncludeInPluginMenu` to `false` to suppress the script from Finale's plugin menu. In this case the script *only* runs at startup.
54
+
55
+
Example:
56
+
57
+
```lua
58
+
finaleplugin.ExecuteAtStartup=true
59
+
```
60
+
61
+
Default is `false`.
62
+
47
63
#### HandlesUndo\* (boolean)
48
64
49
65
Both _JW Lua_ and _RGP Lua_ (by default) automatically run scripts within an undo block named according the undo string returned by the `plugindef()` function. However, it is possible for a script to notify _RGP Lua_ that it will handle undo blocks on its own by setting this value to `true`. One primary reason a script might enable this option is to open a modeless dialog window. Example:
_RGP Lua_ displays to the user any non-nil value returned by a script, regardless of whether an error occurred. You can suppress this display when there is no error by setting this value to `true`. Example:
76
+
77
+
```lua
78
+
finaleplugin.IgnoreReturnValue=true
79
+
```
80
+
81
+
Default is `false`.
82
+
83
+
#### IncludeInPluginMenu\* (boolean)
84
+
85
+
If this value is `false`, _RGP Lua_ does not include the script in Finale's plugin menu. A typical case where your might do this is in combination with `ExecuteAtStartup` set to `true`. This would allow your script to run at startup but not be accessible for the user to run from the menu.
86
+
87
+
This value applies only to the primary menu option. Any additional menu items specified with `AdditionalMenuOptions`*are* included in Finale's plugin menu.
88
+
89
+
Example:
90
+
91
+
```lua
92
+
finaleplugin.IncludeInPluginMenu=false
93
+
```
94
+
95
+
Default is `true`.
96
+
57
97
#### LoadAsString\* (boolean)
58
98
59
99
Setting this value to `true` tells _RGP Lua_ to load the script into an internal string and then send it to Lua. One reason to do this might be if the script file contains an embedded `NULL` character. This option would cause the Lua interpreter to stop at the `NULL`. It overrides the **Load As String** setting in the [configuration dialog](/docs/rgp-lua/rgp-lua-configuration).
Setting this value to `true` tells _RGP Lua_ to pre-load its embedded version of `luaosutils` package. Note that you must still `require` it to use it. See the [this link](/docs/rgp-lua#the-luaosutils-library) for more information.
120
+
121
+
```lua
122
+
finaleplugin.LoadLuaOSUtils=true
123
+
```
124
+
125
+
Default is `false`.
126
+
77
127
#### MinFinaleVersion (number)
78
128
79
129
The minimum version of Finale that can run the script. The number should match that returned by `finenv.FinaleVersion`. _JW Lua_ reads this value every time a script runs and displays an error message if the running Finale version is too low. _RGP Lua_ reads the value once and omits it from Finale's Plug-in menu if the running Finale version is too low. Examples:
Copy file name to clipboardExpand all lines: docs/rgp-lua/finenv-properties.md
+18Lines changed: 18 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -188,6 +188,24 @@ if not success then
188
188
end
189
189
```
190
190
191
+
#### QueryInitializationInProgress\* (function)
192
+
193
+
A function that returns `true` if the script is currently running at Finale startup. You can request your script to run at startup with `finaleplugin.ExecuteAtStartup = true` in your `plugindef` function.
194
+
195
+
|Output Type|Description|
196
+
|------|------|
197
+
|boolean|True if Finale startup in progress.|
198
+
199
+
Example:
200
+
201
+
```lua
202
+
iffinenv.QueryInitializationInProgress() then
203
+
-- execute expensive global variable initialization here
204
+
finenv.RetainLuaState=true-- retain their values so that it only happens once
205
+
return
206
+
end
207
+
```
208
+
191
209
#### QueryInvokedModifierKeys\* (function)
192
210
193
211
A function that returns `true` if the input modifier key(s) were pressed when the menu item was invoked that started the script. The input value is any combination of [COMMAND\_MOD\_KEYS](https://pdk.finalelua.com/class_____f_c_user_window.html#af07ed05132bac987ff3acab63a001e47). You can create combinations by adding together the key codes.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments