Next: Tutorial Up: Plugins Previous: Returning Values
To make life easier for plugin authors, a module, pluginUtils.py, has been added to MMA .5.1
When you access MMA internals, you have to care about MMA changes. For example, the names of the members could change, and you should check the compatibility of your plugin with every new version of MMA that comes out.
The functions defined in pluginUtils are guaranteed to not change and to be updated together with MMA lso, they help you with documentation and argument parsing.
To explain how to use pluginUtils, we have commented the source of the StrumPattern plugin.
# We import the plugin utilities
from MMA import pluginUtils as pu
# ###################################
# # Documentation and arguments #
# ###################################
# We add plugin parameters and documentation here.
# The documentation will be printed either calling printUsage() or
# executing "python mma.py -I pluginname".
# I suggest to see the output for this plugin to understand how code
# of this section will be formatted when printed.
# Minimum MMA required version.
pu.setMinMMAVersion(15, 12)
# A short plugin description.
pu.setDescription("Sets a strum pattern for Plectrum tracks.")
# A short author line.
pu.setAuthor("Written by Ignazio Di Napoli <neclepsio@gmail.com>.")
# Since this is a track plugin, we set the track types for which it can
# be used. You can specify more than one. To allow for all track types,
# call setTrackType with no arguments.
# For non-tracks plugin, don't call setTrackType at all.
# Whether the plugin is track or non-track is decided by the entry point,
# but help will use this information.
pu.setTrackType("Plectrum")
# We add the arguments for the command, each with name, default value and a
# small description. A default value of None requires specifying the argument.
pu.addArgument("Pattern", None, "see after")
pu.addArgument("Strum", "5", "strum value to use in sequence (see Plectrum docs)")
# Some arguments are omitted -- you can see the full source code if you're interested.
# We add a small doc. %NAME% is replaced by plugin name.
pu.setPluginDoc("""
The pattern is specified as a string of comma-separed values, that are equally spaced into the bar.
...... Use the command “mma -i strumpattern” to see the complete documentation!
Each time it's used, %NAME% creates a clone track of the provided one using the voice MutedGuitar for chucks and muted strums.
Its name is the name of the main track with an appended "-Muted", if you need to change it you must do so every time after using %NAME%.
This plugin has been written by Ignazio Di Napoli <neclepsio@gmail.com>.
Version 1.0.
""")
# ###################################
# # Entry points #
# ###################################
# This prints help when MMA is called with -I switch.
# Cannot import pluginUtils directly because it wouldn't recognize which
# plugin is executing it.
def printUsage():
pu.printUsage()
# This is a track plugin, so we define trackRun(trackname, line).
# For non-track plugins we use run(line).
# When using this library, only one of the two can be used.
def trackRun(trackname, line):
# We check if track type is correct.
pu.checkTrackType(trackname)
# We parse the arguments. Errors are thrown if something is wrong,
# printing the correct usage on screen. Default are used if needed.
# parseCommandLine also takes an optional boolean argument to allow
# using of arguments not declared with pu.addArgument, default is False.
args = pu.parseCommandLine(line)
# This is how we access arguments.
pattern = args["Pattern"]
strum = args["Strum"]
# [Omissis]
# Here I omit plugin logic, this is not interesting for explaining
# pluginUtils.
# Let's just pretend we have the result of the computation:
all_normal = "{1.0 +5 90 80 80 80 80 80;}"
all_muted = "z"
# If you don't send all the commands together the result is commands
# are reversed since each is pushed as the very next command to be executed.
# So we save all the commands (with addCommand) and send them at the end
# (with sendCommands).
pu.addCommand("{} Sequence {}".format(trackname, all_normal))
pu.addCommand("{}-Muted SeqClear".format(trackname))
pu.addCommand("{}-Muted Copy {}".format(trackname, trackname))
pu.addCommand("{}-Muted Voice MutedGuitar".format(trackname))
pu.addCommand("{}-Muted Sequence {}".format(trackname, all_muted))
pu.sendCommands()
|
Following are the available functions in the pluginUtil.py module.