EventShortcuts holds default and user-defined dictionaries of shortcuts for events and event patterns
Part of: miSCellaneous
Inherits from: Object
Container for dictionaries of shortcuts for the event framework, which can be defined by the user. Shortcuts might be for event keywords or any other (e.g. synth args). At every time one shortcut dictionary is current, but it's only active if EventShortcuts is turned on. Dictionaries are encapsulated and can only be accessed via copies and posting to prevent unintended changes. For event keywords see James Harkins' Practical Guide to Patterns (especially chapters PG_07_Value_Conversions and PG_08_Event_Types_and_Parameters).
See also: Other event and pattern shortcuts
Some Important Issues
Implementation of shortcuts works like this: if you don't turn EventShortcuts on at all, nothing is changed in the event framework – if you turn it on a mapping function is prepended to every event type function, if this has not been done before in this session and the event type function hasn't been newly defined since last prepending – if you turn it off the prepended function is still there, but does no mapping.
Therfore shortcuts won't work automatically after new definitions of event types. You'd have to turn EventShortcuts on again or apply the method prefixEventTypes. Quite obviously, switching between different shortcut dictionaries might cause a mess while playing (or pausing and resuming) patterns with these shortcuts. But these are exceptional cases, a typical usage would be defining your personal shortcut dictionary (e.g. in the startup file), turning EventShortcuts on and playing therewith, then maybe turning it off and on again on occasion.
Class Methods
*add (name, dict, overwrite)
Adds a new named IdentityDictionary of shortcuts.
name - Symbol or String.
dict - IdentityDictionary of abbreviations (keys given as Symbols) and original names (values given as Symbols).
overwrite - Boolean. Determines if a shortcut dictionary of that name – if existing at all – is overwritten. Defaults to false.
*addOnBase (baseName, newName, dict, overwrite)
Adds a new named IdentityDictionary of shortcuts based on the copy of an existing one.
baseName - Symbol or String. Name of the shortcut dictionary to build upon.
newName - Symbol or String. Name of the new shortcut set.
dict - IdentityDictionary of new or/and additional abbreviations (keys given as Symbols)
and original names (values given as Symbols).
overwrite - Boolean. Determines if a shortcut dictionary of that name – if existing at all – is overwritten. Defaults to false.
Attention: overwrite only determines overwriting of an old dictionary of the same name. It doesn't influence
the overwriting in the copy of the base dictionary itself, as exactly this is a main aim of the method
(you might want to replace the association 's'-> 'strum' by 's' -> 'server').
*remove (name)
Removes a named IdentityDictionary of that name.
name - Symbol or String.
*removeAll
Removes all IdentityDictionaries except \default.
*copyDict (name)
Returns a copy of a shortcut dictionary of that name (if stored).
name - Symbol or String.
*copyCurrentDict (name)
Returns a copy of the current shortcut dictionary of that name.
name - Symbol or String.
*copyAllDicts
Returns an IdentityDictionary of copies of all stored shortcut dictionaries.
*post (name)
Posts the shortcut dictionary of that name (if stored).
name - Symbol or String.
*postCurrent
Posts the current shortcut dictionary.
*postAll
Posts all shortcut dictionaries.
*makeCurrent (name)
Makes the shortcut dictionary of that name current (if stored).
name - Symbol or String.
*on
Turns on the shortcut mechanism, making it ready for events / patterns to be played.
Also invokes prefixEventTypes.
*off
Turns the shortcut mechanism off.
*prefixEventTypes
Puts the remapping function before all event type functions. Therefore a newly defined event type won't work
with shortcuts before this has been called (directly or via on).
*current
Returns the Symbol of the current shortcut dictionary.
*dictNames
Returns the Symbols of all shortcut dictionaries.
*state
Returns the current state (\on or \off).
Examples
(
s = Server.local;
Server.default = s;
s.boot;
)
// turn shortcuts on
EventShortcuts.on
// post all, right now only \default exists
EventShortcuts.postAll
// play an Event with midinote 70
(m: 70).play
// play a Pbind
(
Pbind(
\m, Pwhite(60, 90, 20) + [0, -7], // midinote
\p, Pwhite(-1.0, 1), // pan
\l, 3, // legato
\s, 0.1, // strum
\d, 0.5 // dur
).play
)
// define new dictionary based on \default with two different shortcuts
EventShortcuts.addOnBase(\default, \mine, (s: \scale, t: \ctranspose))
// it isn't current yet, make it
EventShortcuts.makeCurrent(\mine)
// play Pbind with new shortcuts, using key/value notation here
(
p = Pbind(*[
de: Prand([[0, 1, 26, 27], [-6, 4, 10], [0, 8, 14]], inf), // degree
t: Pwhite(0, 1) + Pwrand([0, -10, 10], [0.9, 0.05, 0.05], 200), // ctranspose
d: 0.2, // dur
s: Scale.chromatic24 // scale
]).play
)
// define a SynthDef
(
SynthDef(\test, { |out = 0, freq = 440, width = 0.5, amp = 0.05, gate = 1,
att = 0.05, rel = 1, pan = 0|
Out.ar(out, Pan2.ar(Pulse.ar(freq, width, amp), pan) *
EnvGen.ar(Env.asr(att, 1, rel), gate, doneAction:2)
)
}).add
)
// you can also define shortcuts for synthdef args
(
EventShortcuts.addOnBase(\mine, \mine, (w: \width, r: \rel), true);
EventShortcuts.makeCurrent(\mine);
)
(
Pbind(*[
i: \test, // instrument
n: Prand([0, 4, 7], inf), // note
o: Pwhite(5, 6), // octave
dt: Pwhite(0, 20), // detune (in cent)
l: 0.2, // legato
d: 0.2, // dur
w: Pseq((5, 10..40)/100, 4), // width (synth arg)
r: Pseq([0.1, 0.5], inf), // rel (synth arg)
]).play
)
// works also with other event patterns: Pmono, PmonoArtic, Pbindef
(
Pmono(\default, *[
d: 0.03, // dur
a: 0.3, // amp
dt: Pseq([0, 10], inf), // detune in Hz
p: Pseq((-100, -95..100)/100, 1) // pan
]).play
)
// further shortcuts for playing events and patterns are collected here: Other event and pattern shortcuts
// e.g. you can directly play a Pbind derived from an Array:
(
[
n: Pshuf((1..12)), // note
d: 0.5, // dur
l: 3, // legato
o: Pwhite(4, 7) // octave
].pp
)
// also possible with Pbindef, though you shouldn't change current shortcut
// if you still want to refer later on to a Pbindef defined before the change
(
Pbindef(\x, *[
d: Prand([1,1,2]/5, inf), // dur
m: Pwhite(50, 80), // midinote
ct: Prand([[0, 4], [0, 5]], inf) // ctranspose
]).play
)
Pbindef(\x, \d, Prand([1,1,1,2,3]/7, inf))
Pbindef(\x, \ct, [0, 5, 8, 13, 16])
Pbindef(\x).stop;
// turns off and ensures that default shortcuts are active when EventShortcuts is
// turned on next time in this session
(
EventShortcuts.off;
EventShortcuts.makeCurrent(\default);
)