Zones - malcolmgroves/reaper_csi GitHub Wiki

Zones are where we do two things:

  • where we map the widgets defined in our mst files to the actions we want to perform when they are invoked (pressed, rotated, etc)
  • where we group multiple action/widget mappings together into related groups.

A Simple Example

The widget/action mapping part is easy. Let's say we have a widget called PlayButton, and we want it to perform the Play action when pressed, we would simply use the following syntax in our zon file.

PlayButton Play

There's obviously more options than just play. Have a look at the Action Reference page for more examples.

However, we can't just have this sitting by itself. We need to put it inside a zone definition, usually along with other widgets performing related functions (say, the Stop, Record, FF, Rewind buttons, etc). At a minimum, we’d need something like this:

Zone Home
        PlayButton Play
ZoneEnd

Provided our CSI.INI and Widget definitions are setup correctly, this should allow us to control the Play button from our Surface.

Naming Zones

If your Zone name has a space in it, you'll need to wrap all references to it in quotes. Probably a good idea to wrap them all in quotes, spaces or not, just so you don't have to think about it.

A Slightly More Useful Example

As great as it is to get that first action happening when you press a Surface button, let’s look at a slightly more interesting example. I might group a bunch of widgets together into a zone called MasterButtons, because the actions I am assigning to them are conceptually related:

Zone "MasterButtons|"
	Track ToggleMapSelectedTrackFXMenu
	Send ToggleMapSelectedTrackSends
	Pan ToggleMapSelectedTrackFX
	Shift+Pan GoZone Home
	Plugin ToggleScrollLink
        ChannelLeft TrackBank "-1"
	ChannelRight TrackBank "1"
	BankLeft TrackBank "-20"
	BankRight TrackBank "20"
	Rewind Rewind
	FastForward FastForward
	Stop Stop
	Play Play
	Record Record
	F1 NextPage
ZoneEnd

As another example, I might define a zone called Channels which collects all my track faders and related widgets into a single group, again because for me they are all related to controlling my tracks.

Zone "Channel|"
	TrackNavigator
	DisplayUpper|  TrackNameDisplay
	TrackTouch+DisplayUpper|  TrackVolumeDisplay
	RotaryPush| GoZone PanWidth|
	Rotary| TrackPan "0"
	RecordArm|  TrackRecordArm
	Solo|  TrackSolo
	Mute| TrackMute
	Select|  TrackUniqueSelect
	Shift+Select|  TrackRangeSelect
	Control+Select|  TrackSelect
	Shift+Control+Select| TogglePin
	Fader|  TrackVolume
	FaderTouch|  TrackTouch
ZoneEnd

Note the | character after the name of the zone. This indicates that it is a Template zone, meaning it will be instantiated as a child of another zone.

For example, here I'm defining some widget/action mappings in my Home zone, while also pulling in the MasterButtons and Channel zones from earlier:

Zone "Home"
	OnTrackSelection MapSelectedTrackSendsToWidgets
	OnTrackSelection MapSelectedTrackFXToMenu
	IncludedZones
		"MasterButtons|" 
		"Channel|1-8"
	IncludedZonesEnd
ZoneEnd

Zones vs Template Zones

Notice with Template Zones, at the point we include them into the parent zone, we can decide how many instances we want. In the case of MasterButtons, we just want the one. However, for Channel, the control surface probably has a number of faders, so we really want one of these Channel zones instantiated for each one. Instead of defining Channel1, Channel2, etc, we can specify the number we want when we inlcude the zone.

In this case we'll end up with Channel1 through Channel8 instantiated, and everywhere in the Channel Zone definition that you see the | character, it will get substituted the relevant value (1 through 8).

So conceptually, we'll end up with something like this:

  • Home
    • MasterButtons
    • Channel1
    • Channel2
    • Channel3
    • Channel4
    • Channel5
    • Channel6
    • Channel7
    • Channel8

That's great for Template Zones, but we can also do this with stand-alone zones (ie, zones not instantiated as a child of another zone). We still use the | character, but for these we need to specify how many we want when we define them:

Zone "Send|1-8" 
   ...
ZoneEnd

Changing Zones

We can also change which zones are active at the moment. Notice in my Channel zone definition above, the RotaryPush widgets are mapped to an Action called GoZone:

RotaryPush| GoZone PanWidth|

That is telling CSI to "overlay" that zone over the currently active zones. Any widgets used in the new PanWidth zone that were previously mapped in the currently active zones will now trigger the actions defined in the PanWidth zone. Any that aren't used in the PanWidth zone will keep performing the actions they were before we triggered GoZone.

Zone "PanWidth|1-8"
	TrackNavigator
	ParentZone Channel|
	Rotary| TrackPanWidth 1
	RotaryPush| GoZone Pan|
ZoneEnd

This zone could of course jump to another zone, as you can see with the call to GoZone Pan on the second last line.

This results in a very flexible system where can temporarily change certain control's behaviour in response to whatever widgets and/or Virtual Widgets we like.

Adding Comments to Zones

When triggering custom actions or using actions whose meanings may otherwise not be obvious, it's a good idea to add comments to your in your .zon files. CSI allows for two types of comments:

  1. / Lines that begin with a forward slash are completely ignored by CSI and are good for commenting sections of code. Hint: these also work in .mst files.
  2. // Trailing comments are preceeded by two forward slashes and can be used after an action in a .zon file

Here is an example from a .zon file that uses both types of comments. First, the entire section is preceded by a comment using a single forward slash. Then, each of the automation modes is followed by a trailing comment identifying which mode is which.

/To make MCU Std mode work like MCU Cubase mode, I'm using F1-F5 on the X-Touch One for the automation modes.

Zone "SelChannelButtons|"
	SelectedTrackNavigator
	F1 				TrackAutoMode 1 	//Read
	F2 				TrackAutoMode 3 	//Write
	F3 				TrackAutoMode 0 	//Trim
	F4 				TrackAutoMode 2 	//touch
	F5				TrackAutoMode 4 	//Latch

ZoneEnd