By kertikristof
2021-07-26

Overview

The button event can be found on all control elements, which have push functionality: both buttons and encoders. The button event by default is in momentary mode and in this article I will show you the basics such as setting a button to toggle, when it comes to this event in the Grid system.

Button value, mode and state

When you open up the default Local Variables action block under the button event, you will notice that the val variable is assigned to self:button_value(). This returns the value of the button. By default, this value is 127 when the button is pressed down and 0 when released, this is what's called momentary button mode.

default local variable value

The button mode can be changed with the self:button_resolution() function, so the self:button_value() function returns different button values on interaction. The self:button_resolution function() has a simple user interface: add a Button Settings action block as the first action in the actions panel.

add button settings action

You can use the simple drop down selection when clicking in the input area, or enter an integer, to set the specific button mode you need.

set button mode

There are a lot of functions available in programming Grid modules. Our goal is to make the programming aspect more accessible through action blocks. Such simplification is having Button Settings instead of calling self:button_resolution() with a parameter in a Code Block action.

The self:button_state() function will return the state of the control element. This is either "pressed down" 0 OR "released" 127. This is not effected by the Button Settings action, and the selected button mode.

Wrapping up

  1. The self:button_value() function's returned value is effected by the button mode set by the Button Settings action. Default Local Variables action will have this function assigned to a variable.
  2. To change from momentary to toggle, 2-step or other step range, use the Button Settings action, as the first action in the actions panel.
  3. The self:button_state() function returns if the button is pressed (0) or released (127). This is not effected by Button Settings.

set button to toggle

MIDI and button values

The most important concept to keep in mind when working with button states, that note on (command 144) and note off (command 128) MIDI messages won't work as expected with different button modes. Originally the note on and note off MIDI commands represent a keyboard key, where a key is whether pressed or released. Each software will try to do something about the "wrong" or "stuck" notes. Different DAW's will try to map MIDI note on and note off messages differently to user interface elements, and this can have unexpected results too.

To utilize the various step options of the Button Settings action, it's best to use **Control Change **messages when working with MIDI.

set button midi messages to control change

Split press and release

Before Grid Editor v1.2+ the button event was split into down (press) and up (release) events. From Grid Editor v1.2+ these events are merged, so for special use cases, you may need a set of Condition actions to send different MIDI or Macro messages to your connected host device.

add an if condition

You can set a condition to check on the state or value of the button to send different messages. The example below shows a simple check on the button state, and sends different MIDI control value under each case, whether the button state is pressed or released.

button state example

Using print for debug

As in most configuration scenarios, you can use the Code Block action with a print() function to see different button modes in action. Below when using the 3-step mode, see that the button value range is split in range of 0-42-84-126. In order to see changes, press the button being configured.

In the example below, the Code Block action is moved below the Button Settings and Local Variables action blocks. The value could be different in the print(val) function call if the order of actions is different!

set button to toggle