Running Custom Scripts

Overview

  • QML Scripts can be run

    • By selecting a file from disk, or

    • By installing the script in a specific folder structure and selecting its corresponding menu item from the Scripts menu.

Running Script From Disk

  • In version 1.0, custom scripts could be run via the LAUNCH SCRIPT From File… menu item in the Batch menu.

  • In version 1.1, the new Scripts menu contains the LAUNCH SCRIPT From File… menu item.

  • In either case, the menu item will open an open file dialog and let you select a .QML file to execute.

  • Any valid QML file can be picked from any folder in any disk or network location.

Installing Scripts As Menu Items

  • Sequoia v1.1 can install additional scripts in the Scripts menu.

  • The Scripts menu is populated from two alternative locations:

Shipping Scripts

  • The /Sequoia/Scripts/AllUsers/ folder contains shipping scripts in dedicated sub-folders

  • These scripts are installed by the Sequoia installer.

  • When Sequoia is re-installed, the scripts will be overwritten and could be updated automatically to newer versions.

User Scripts

  • The local user’s /Documents/Sequoia folder will be scanned for user-creared sub-folders.

  • If a sub-folder has the same name as a sub-folder in the /Scripts/AllUsers/ location, the User’s version will be used.

  • This can be useful for creating custom versions of shipping scripts and making modifications to them without the risk of being overwritten by a new Sequoia installation.

  • Note that the Shipping Scripts are visible to all users, while the User Scripts are only available to the current user as they are located in his own Documents folders.

Naming Rules And Conventions

  • The sub-folder name found in either of the two possible locations will be used as the name of the menu item.

    • For example, if the folder is called “My New Tool”, this is the name that will appear under the Scripts menu.

  • The folder must contain at least one .QML file which has exactly the same name as its parent folder.

  • This script will be the one to be executed when the menu item is activated.

    • In the above example, a file called “My New Tool.qml” must exist in the folder “My New Tool” and will be run when the “My New Tool” menu item is activated.

    • If such a file does not exist, the folder will be skipped and no menu item will be added for it in the Scripts menu!

  • The folder may contain further scripts that are loaded by the main script - they will not be run automatically.

  • The folder can contain an optional icon file, typically in .PNG format containing RGB and Alpha, named exactly the same as the parent folder and the main QML file.

    • In the above example, the icon file would be called “My New Tool.png”.

  • If no icon file is found, no icon will appear next to the menu item under the Scripts menu.

  • The icon will be resized to match the current menu icons resolution.

    • The default size is 16x16 pixels.

    • On macOS, menu icons are currently not supported.

  • The folder may contain other files and sub-folders, for example for image storage etc.

  • These can be referenced by the main script, but will be otherwise ignored by the Menu installation system.

Updating The Scripts Menu

  • The two scripts folders will be scanned each time Sequoia is started, and any new scripts that meet the above conditions will appear under the Scripts menu.

  • The Scripts menu can also be updated dynamically while Sequoia is running:

    • Create or copy the sub-folder with a .QML script with the same name plus an optional icon image and any other relevant files

    • Select the REFRESH User Scripts menu item in the Scripts menu - the menu will show the new menu items.

Test-Running Scripts During Development

  • Each time a custom script menu item is activated, the source code of the script will be reevaluated.

  • This allows you to edit a script’s source code in any external editor, save the changes, and re-run the script by simply selecting its menu item again.

    • Note that it is NOT necessary to execute the REFRESH User Scripts menu item to update the script once it has been added to the Scripts menu!