How Sibelius Plugins Store their Settings for User Data

Some Sibelius plugins (for example, Respell Sharps as Flats) run without taking any input from a user. They do not display a dialog, but just run and do what they were designed to do.

Other plugins take input from users by putting up a dialog box that has boxes to type into, or check boxes, list boxes, or radio buttons. You might see a dialog that looks like this:

In this dialog there is a great deal of data, but the initial values in the edit boxes will change every time the plugin is run, because they are pulled out of the current score. The plugin does not save anything from the previous run, but instead always starts fresh.

Other plugins, however, remember what a user typed in the last time the plugin was run, assuming that the same settings might be used again. Here are some different ways plugins can save these settings.

Dialog settings and dialog variables

Every control in a plugin dialog that can accept user input, such as edit boxes, list boxes, check boxes, and radio buttons, has an associated piece of data, a variable, from which the initial value is taken and into which the user input is stored. In a fairly simple dialog like this one,

each of the radio buttons, Copy Only Notes and Copy All Objects (except system objects), has an associated variable. Sibelius looks at the variables to set the controls before the dialog comes up, and then saves what is in the controls to the variables when the dialog is closed.

Plugins are text files that can be edited. When a plugin is edited and saved, the current values of all dialog variables are saved in the text file, and these values will be what the dialog shows the first time it appears in a Sibelius session. If a plugin is simply run, the dialog variables in the file will not be changed.

Saving settings only during a Sibelius session

When Sibelius starts up, it will load all the plugin files it knows about into memory, and from that point on it deals only with the copy of the plugin that is in memory, and not with the plugin text files.

The period of time between when Sibelius first starts and when Sibelius is closed is called a Sibelius session.

The first time a plugin is run in a Sibelius session, the values of the dialog variables will be what had been stored in the plugin text file. If you change the dialog settings in a running plugin, however, those changes are retained in the computer memory, and will be preserved the next time the plugin is run, as long as the plugin stays loaded into memory.

If you change a checkbox that was True to be False, and then later run the plugin again in the same session, the initial value of the control will be False.

If you close and then restart Sibelius, it will not remember that you changed that checkbox, and will display what had last been saved in the text file.

Saving plugin settings across Sibelius sessions

Sometimes one of the purposes of a plugin is to remember what you have done before, even across Sibelius sessions. Run Plugins By Name provides a sorted list of plugins that you can run, but it keeps the previous 12 or so plugins you have run at the top of the list, in the order in which they were run, so that is it easy to find the plugins you have run recently. This plugin wants to save those plugin names even across Sibelius sessions, so it will use a different mechanism to accomplish this.

Sibelius and the ManuScript programming language do not provide a mechanism for saving settings across sessions, so Hans-Christoph Wirth wrote the plugin Preferences, which has shipped with Sibelius since version 4. Preferences provides code that other plugins can call to save and then restore saved settings from a data file that Preferences uses as a database.

When this mechanism is used, a plugin will call SavePreferences() after a dialog is finished, and will call GetPreferences() just before a dialog is brought up. GetPreferences() looks to see if any preferences have been saved, and uses any that it finds. If there are none, the dialog will get its initial values from the appropriate dialog variables in the plugin file.

It is a fair bit of work to save and restore settings via this mechanism, so it is not always done.

There are only about 10 plugins that ship with Sibelius that use Preferences, but it has been used extensively in downloadable plugins, and there are over 100 plugins there that save settings in the Preferences database.

The Preferences database is the text file SibeliusPluginPreferences.dat that is stored in your Sibelius user data folder.

For Windows Vista or later, the folder for Sibelius 4 to 6 is:

%appdata%\Sibelius Software\Sibelius 4\
%appdata%\Sibelius Software\Sibelius 5\
%appdata%\Sibelius Software\Sibelius 6\

or, for Sibelius 7 and later,

%appdata%\Avid\Sibelius 7\
%appdata%\Avid\Sibelius 7.5\

For Mac OSX, the folder will be at:

~/Library/Application Support/Sibelius Software/Sibelius 4/
~/Library/Application Support/Sibelius Software/Sibelius 5/
~/Library/Application Support/Sibelius Software/Sibelius 6/
~/Library/Application Support/Avid/Sibelius 7/
~/Library/Application Support/Avid/Sibelius 7.5/

For Sibelius 8, the “Sibelius” subfolder will not have a number, so you will see:

%appdata%\Avid\Sibelius\
~/Library/Application Support/Avid/Sibelius/

The file will be generated by the first plugin run that stores settings into the database.

Hans-Christoph also made Preferences directly runnable (from the Others menu) so that users can view or edit the data that a plugin saves. Most users will never look at it. Each user will have different database contents based on the plugins that have been run; at the moment mine looks like this:

If you want to know if a particular plugin saves its settings in Preferences, run Preferences directly and look in the Plug-in column. If the name is not there, the plugin is not saving its settings in Preferences.

There are some examples of plugins that save data in separate data files as well, but the Preferences data base is the most common mechanism used to preserve settings across sessions.

Modifying saved records in the plugin Preferences database

Finally, for the really adventurous, you can edit the Preferences data base file. You can do it in the Preferences plugin by choosing a plugin and using the Edit button, as shown in the screenshot above. You can also directly edit the text file SibeliusPluginPreferences.dat in a text editor. If you do this, it is wise to save an unedited copy of this file before you mess with it. The database was never really intended for direct manipulation, but it is pretty straightforward to do it.

Here is an example of what the file might look like. There are some header records, then the data for each plugin starts with a “plugin” record, then the values for that plugin are indented below the record, and then the plugin data is terminated by an empty line.

You might want to transfer some plugin settings from one machine to another, and this is a way you could do it. In the source machine, open SibeliusPluginPreferences.dat in a text editor, and find the data for the plugin you want to transfer. If you wanted to transfer the There It Is! settings, you would copy the text

to the clipboard. Then go to your other machine, and run Preferences to make sure there is no data for that plugin, or that there is data you want to replace. Then edit that machine’s copy of SibeliusPluginPreferences.dat, and go to the end of the file, or to the place where you want to replace records. If replacing, delete the existing records. Paste the copied data into the database file, ensuring that you have a blank line at the end of it, and save it. Close and reopen Sibelius and then run the Preferences plugin, and you should see data for There It Is!, and if you run There It Is!, you should see the saved setting when the dialog appears.

If you get garbage, restore your backup copy (you made one, right?) and try again, being especially careful to retain the indentation levels and to have a terminating final line.

If you can’t get this to work, transfer settings by taking a screen shot of the plugin dialog(s) on the source machine, and enter the values into the same dialog on the other machine.

And that is probably everything you need to know about this.

---

About the author

Bob Zawalich is a composer, guitarist, and software designer who lives near Seattle, Washington. He has studied both computer science and music, and has written software at Microsoft. Bob has authored several hundred plugins for Sibelius notation software.