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, PLx and live coding with Strings



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. 


NOTE: Some pattern classes (e.g. Ppar) don't work correctly with EventShortcuts, but this can be circumvented by applying shortcuts to source event patterns before, see method Pattern::eventShortcuts.



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);

)