Start with ReaLearn Playtime target descriptions

doc/playtime/modules/ROOT/nav.adoc

@@ -44,6 +44,7 @@
 ** xref:user-interface/keyboard-shortcuts.adoc[]
 * xref:further-concepts.adoc[]
 ** xref:further-concepts/general.adoc[]
+** xref:further-concepts/matrix.adoc[]
 * xref:advanced-usage-scenarios.adoc[]
 ** xref:advanced-usage-scenarios/record-performance-as-audio.adoc[]
 ** xref:advanced-usage-scenarios/control-with-items.adoc[]

doc/playtime/modules/ROOT/pages/further-concepts/matrix.adoc

@@ -0,0 +1,92 @@
+= Matrix concepts
+
+[[cell]]
+== Cell
+
+A _cell_ is a broad term that can refer to a xref:key-concepts.adoc#slot[], a xref:key-concepts.adoc#column[], a xref:key-concepts.adoc#row[], or the entire xref:key-concepts.adoc#matrix[].
+
+While it may seem like a concept exclusive to Playtime's xref:user-interface.adoc[], it is not limited to that context.
+
+[[active-cell]]
+== Active cell
+
+In a xref:key-concepts.adoc#matrix[], there's always exactly one <<cell>> that is considered the currently _active_ one. It is then possible to carry out certain actions on this cell, for example using the xref:realearn-targets.adoc[].
+
+One way to _activate_ a cell is to select it in the xref:user-interface.adoc[]. Vice versa, the selection in the user interface usually follows the currently active cell.
+
+By default, a _slot cell_ is also _activated_ just by <<trigger-slot,triggering>> it. This can be changed by setting the matrix property xref:user-interface/inspector/matrix/playback.adoc#inspector-matrix-activate-slot-on-trigger[].
+
+[[trigger-slot]]
+== Trigger a slot
+
+_Triggering a slot_ is an action carried out on a xref:key-concepts.adoc#slot[] that can have one of the following results, depending on the current slot contents and play state:
+
+* Start slot playback
+* Stop slot playback
+* Start slot recording
+* Stop slot recording
+
+Triggering a slot can be achieved either by using the xref:user-interface/keyboard-shortcuts.adoc#enter[] shortcut in the xref:user-interface.adoc[] or by using the ReaLearn xref:realearn::targets/playtime/slot-transport-action.adoc[].
+
+Triggering also takes the xref:user-interface/inspector/column/playback.adoc#inspector-column-trigger-mode[] and xref:user-interface/inspector/clip.adoc#inspector-clip-velocity-sensitivity[] into account.
+
+[[control-unit]]
+== Control unit
+
+A _control unit_ represents a xref:realearn::key-concepts.adoc#controller[] connected to a certain xref:key-concepts.adoc#matrix[Playtime matrix]. The concept is most important for xref:key-concepts.adoc#grid-controller[grid controllers] because they have special features within Playtime, most importantly <<control-unit-scrolling,scrolling>> through the matrix and displaying a corresponding <<control-unit-frame>> in the xref:user-interface.adoc[].
+
+One control unit always corresponds to a one xref:realearn::key-concepts.adoc#unit[ReaLearn unit] within the same xref:helgobox::key-concepts.adoc#instance[] as the xref:key-concepts.adoc#matrix[Playtime matrix].
+
+A control unit has the following properties:
+
+Name::
+Usually corresponds to the name of the connected xref:realearn::key-concepts.adoc#managed-controller[], e.g. "Launchpad". The name is currently not visible in Playtime, but might be displayed as part of the <<control-unit-frame>> in the future.
+
+Color::
+The color of the control unit is derived from the color of the xref:realearn::key-concepts.adoc#managed-controller[]. You can see the color "in action" by looking at the <<control-unit-frame>>.
+
+Size::
+The number of columns and rows available on the controller. For example, in case of Launchpads, it's usually 8 columns and 8 rows.
++
+The size of the control unit is provided by xref:realearn::further-concepts/compartment.adoc#custom-data[] of the xref:realearn::key-concepts.adoc#main-compartment[] within the xref:realearn::key-concepts.adoc#unit[ReaLearn unit] representing this control unit:
++
+[cols="m,1,1"]
+|===
+| Variable | Type | Description
+
+| playtime.control_unit.column_count
+| Integer
+| Number of available columns
+
+| playtime.control_unit.row_count
+| Integer
+| Number of available rows
+|===
++
+[source,lua]
+.Example in Lua
+----
+custom_data = {
+    playtime = {
+        control_unit = {
+            column_count = 8,
+            row_count = 8,
+        },
+    },
+},
+----
+
+[[control-unit-scroll-position]] Current scroll position::
+The address of the top-left visible slot. See <<control-unit-scrolling>>.
+
+[[control-unit-scrolling]]
+== Control unit scrolling
+
+When connecting a xref:key-concepts.adoc#grid-controller[] to Playtime, it reflects the contents of the xref:key-concepts.adoc#matrix[]. It often happens that the matrix is larger than the size of the controller grid. In that case, it's important to be able to scroll.
+
+[[control-unit-frame]]
+== Control unit frame
+
+The _control unit frame_ is a rectangle in the xref:user-interface/matrix-area.adoc[] that shows which portion of the matrix is currently shown on a certain grid controller, according to the current <<control-unit-scrolling,scroll position>>.
+
+The display of control unit frames can be switched off using xref:user-interface/settings-dialog.adoc#settings-show-control-unit-frames[].

doc/playtime/modules/ROOT/pages/key-concepts.adoc

@@ -272,4 +272,11 @@ That is, it starts and stop playback according to the bar/beat division and temp
 [[playtime-timeline]]
 === Playtime timeline
 
-When the REAPER project is stopped, Playtime uses its own timeline as reference, which however, shares a common tempo with the <<reaper-project-timeline>>.
+When the REAPER project is stopped, Playtime uses its own timeline as reference, which however, shares a common tempo with the <<reaper-project-timeline>>.
+
+[[grid-controller]]
+== Grid controller
+
+A _grid controller_ is a unique class of hardware controller designed specifically for clip launching. A well-known example is the Novation Launchpad. A grid controller feature a grid of pads with LEDs arranged in rows and columns — exactly like Playtime's xref:key-concepts.adoc#matrix[]!
+
+Playtime includes out-of-the-box support for many popular grid controllers. link:https://github.com/helgoboss/helgobox/wiki/Playtime-Controllers[Here] you can find the current list of supported devices.

doc/playtime/modules/ROOT/pages/usage/grid-controllers.adoc

@@ -1,17 +1,9 @@
 = Use grid controllers
 
-== Introduction
-
-_Grid controllers_ are a unique class of hardware controller designed specifically for clip launching. A well-known example is the Novation Launchpad. These controllers feature a grid of pads with LEDs arranged in rows and columns — exactly like Playtime's xref:key-concepts.adoc#matrix[]!
-
 .Grid controllers are optional!
-TIP: You don't need a grid controller to use Playtime! However, using one adds a tactile dimension to the clip-launching experience, making Playtime feel more like a distinct musical instrument. It’s a fun way to enhance interaction and creativity.
-
-Playtime includes out-of-the-box support for many popular grid controllers. link:https://github.com/helgoboss/helgobox/wiki/Playtime-Controllers[Here] you can find the current list of supported devices.
-
-== Usage
+TIP: You don't need a xref:key-concepts.adoc#grid-controller[] to use Playtime! However, using one adds a tactile dimension to the clip-launching experience, making Playtime feel more like a distinct musical instrument. It’s a fun way to enhance interaction and creativity.
 
-If your controller is on the link:https://github.com/helgoboss/helgobox/wiki/Playtime-Controllers[list of supported devices], here's how you set it up:
+If your xref:key-concepts.adoc#grid-controller[] is on the link:https://github.com/helgoboss/helgobox/wiki/Playtime-Controllers[list of supported devices], here's how you set it up:
 
 . Ensure that Playtime is running and you see its xref:user-interface.adoc[].
 . If the device is already connected to the USB port, **disconnect it** and wait a few seconds!

doc/playtime/modules/ROOT/pages/user-interface/keyboard-shortcuts.adoc

@@ -2,6 +2,7 @@
 
 Playtime provides keyboard shortcuts in addition to the xref:helgobox::app/user-interface/keyboard-shortcuts.adoc[general ones].
 
+[cols = "1,1a"]
 |===
 |Shortcut |Purpose
 
@@ -26,6 +27,15 @@ Playtime provides keyboard shortcuts in addition to the xref:helgobox::app/user-
 |kbd:[Space]
 |Starts or stops playback.
 
+|[[enter]] kbd:[Enter]
+|
+Carries out an action depending on the current selection:
+
+* When the xref:user-interface/matrix-area.adoc#matrix-cell[] is selected, stops all clips in the xref:key-concepts.adoc#matrix[].
+* When a xref:user-interface/matrix-area.adoc#column-cell[] is selected, stops all clips in the xref:key-concepts.adoc#column[].
+* When a xref:user-interface/matrix-area.adoc#row-cell[] is selected, plays all clips in the xref:key-concepts.adoc#row[] whose column follows scenes.
+* When a xref:user-interface/matrix-area.adoc#slot-cell[] is selected, xref:further-concepts/matrix.adoc#trigger-slot[triggers] the xref:key-concepts.adoc#slot[].
+
 |kbd:[F2]
 |Renames the currently selected column, row, clip or track.
 

doc/playtime/modules/ROOT/pages/user-interface/settings-dialog.adoc

@@ -8,6 +8,8 @@ image::generated/screenshots/main/settings.png[]
 
 include::partial$generated/elements/settings/show-control-unit-frames.adoc[]
 
+See xref:further-concepts/matrix.adoc#control-unit-frame[].
+
 include::partial$generated/elements/settings/show-column-numbers.adoc[]
 
 Disabling this will give you more vertical space, but also hides the shortcut buttons such as xref:user-interface/matrix-area.adoc#column-cell-exclusive-mode[]. In that case, you can still change those things in the xref:user-interface/inspector/column.adoc[].

doc/realearn/modules/ROOT/pages/further-concepts/compartment.adoc

@@ -39,8 +39,7 @@ They are JSON files and very similar to what you get when you press
 _Export to clipboard_.
 * They can even be in a subdirectory.
 Please note that the subdirectory name becomes a part of the preset ID, so better don't move existing presets around if you want preset references of existing ReaLearn units to stay intact.
-* JSON files can also contain custom data sections.
-For example, the ReaLearn Companion app adds a custom data section to controller presets in order to memorize the positions and shapes of all control elements.
+* JSON files can also contain <<custom-data>>.
 
 [#writing-presets-with-luau]
 === Writing presets with Luau
@@ -406,6 +405,18 @@ For controls divided into rows and column, as for example found on the Novation
 Numbered (`numbered`)::
 Simply lets you pick among any number between 1 and 100.
 
+[[custom-data]]
+== Custom compartment data
+
+Each xref:key-concepts.adoc#compartment[] in ReaLearn can carry _custom data_. That is arbitrary structured (JSON-like) data which can be used in certain ways.
+
+I know that's a quite generic description. It's best to give some examples:
+
+* ReaLearn's xref:further-concepts/unit.adoc#projection[projection feature] uses custom compartment data within the xref:key-concepts.adoc#controller-compartment[] in order to memorize the positions and shapes of all control elements.
+* Playtime's xref:playtime::further-concepts/matrix.adoc#control-unit[] feature reads custom compartment data within the xref:key-concepts.adoc#main-compartment[] in order to know the size of the connected xref:playtime::key-concepts.adoc#grid-controller[].
+
+Such custom data can't directly be edited in ReaLearn's xref:user-interface.adoc[]. But you can read it when dealing with JSON or Lua chunks, e.g. when <<writing-presets-with-luau>>.
+
 == Order in which mappings are processed
 
 Since ReaLearn 2.10.0, mappings are processed from top to button, exactly in the order in which they are defined within the corresponding compartment.

doc/realearn/modules/ROOT/pages/key-concepts.adoc

@@ -13,12 +13,23 @@ In ReaLearn, the term _control_ typically refers to the process of triggering or
 
 In ReaLearn, the term _feedback_ refers to controlling LEDs, motorized faders, or displays on your device in response to events in REAPER, such as a track volume change.
 
-[[controller]]
 == Controller
 
-A _controller_ is the device you use to control REAPER.
+Most of the time, when talking about _controllers_ in the documentation, we are talking about controllers in the _general_ sense.
+
+[[controller,Controller]]
+=== Controller in the general sense
+
+A _controller_ in the general sense is the device you use to control REAPER.
 It is usually a hardware device, such as a MIDI keyboard or control surface, but it can also be software, like an OSC app.
 
+Controllers are normally not specifically managed within ReaLearn, because you just need to set an <<input-port>> and and <<output-port>>, and that's all ReaLearn needs to know. An exception are <<managed-controller,managed controllers>>.
+
+[[managed-controller]]
+=== Managed controller
+
+Only recently, ReaLearn introduced the concept of xref:further-concepts/instance.adoc#auto-units[], in which controllers can actually be managed in a xref:user-interface/settings-dialog.adoc#controllers[list]. ReaLearn then automatically creates <<unit,units>> depending on which of these controllers are connected. Such controllers are called _managed controllers_.
+
 [[control-element]]
 == Control element
 

doc/realearn/modules/ROOT/pages/targets/playtime.adoc

@@ -1,2 +1,53 @@
+= Playtime targets
 
-= Playtime targets
+The targets in this section are made for controlling xref:playtime::introduction.adoc[Playtime], the clip launcher contained in Helgobox.
+
+[[column-selector]]
+== Column selector
+
+Column-related targets use a _column selector_ to define what xref:playtime::key-concepts.adoc#column[] the target should be applied to.
+
+The following kinds of column selectors are available:
+
+Active::
+The xref:playtime::further-concepts/matrix.adoc#active-cell[currently active] column.
+
+At position::
+Here you can refer to a fixed column by entering the column number, e.g. 2.
+
+Dynamic::
+Allows you to dynamically refer to a certain column. See <<dynamic-selector-variables>>.
+
+[[slot-selector]]
+== Slot selector
+
+Slot-related targets use a _slot selector_ to define what xref:playtime::key-concepts.adoc#slot[] the target should be applied to.
+
+The following kinds of slot selectors are available:
+
+Active::
+The xref:playtime::further-concepts/matrix.adoc#active-cell[currently active] slot.
+
+At coordinates::
+Here you can refer to a fixed slot by entering the slot address, e.g. 2 and 4. The first number is the number of the xref:playtime::key-concepts.adoc#column[], the second one the number of the xref:playtime::key-concepts.adoc#row[].
+
+Dynamic::
+Allows you to dynamically refer to a certain slot. There are two expressions, the first one should evaluate to the column index and the second one to the row index. As always, expressions must evaluate to zero-based indexes! See TODO <<dynamic-selector-variables>>.
+
+[[dynamic-selector-variables]]
+== Dynamic selector variables
+
+In addition to the general variables described in xref:further-concepts/target.adoc#dynamic-selector[], the dynamic selectors mentioned above grants access to the following variables:
+
+[cols="m,1,3"]
+|===
+| Variable | Type | Description
+
+| control_unit_column_index
+| Integer >= 0
+| Column index of the current top-left scroll position within the xref:playtime::further-concepts/matrix.adoc#control-unit[Playtime control unit] represented by this xref:key-concepts.adoc#unit[ReaLearn unit].
+
+| control_unit_row_index
+| Integer >= 0
+| Row index of the current top-left scroll position within the xref:playtime::further-concepts/matrix.adoc#control-unit[Playtime control unit] represented by this xref:key-concepts.adoc#unit[ReaLearn unit].
+|===

doc/realearn/modules/ROOT/pages/targets/playtime/browse-cells.adoc

@@ -1,3 +1,9 @@
 = Target "Playtime: Browse cells"
 
-include::partial$under-construction.adoc[]
+Changes the currently xref:playtime::further-concepts/matrix.adoc#active-cell[].
+
+Best uses with xref:further-concepts/mapping.adoc#rotary-endless-encoder[encoders] or previous/next-style buttons.
+
+== Axis
+
+Sets the direction into which to browse.

doc/realearn/modules/ROOT/pages/targets/playtime/column-action.adoc

@@ -1,3 +1,10 @@
 = Target "Playtime: Column action"
 
-include::partial$under-construction.adoc[]
+Invokes a xref:playtime::key-concepts.adoc#column[]-related action.
+
+TODO
+
+== Action menu
+
+== Column menu
+

doc/realearn/modules/ROOT/pages/targets/playtime/control-unit-scroll.adoc

@@ -1,3 +1,7 @@
 = Target "Playtime: Control unit scroll"
 
-include::partial$under-construction.adoc[]
+Controls the current xref:playtime::further-concepts/matrix.adoc#control-unit-scroll-position[] of the xref:playtime::further-concepts/matrix.adoc#control-unit[] represented by this xref:key-concepts.adoc#unit[ReaLearn unit].
+
+== Axis
+
+Sets the direction into which to scroll.

doc/realearn/modules/ROOT/pages/targets/playtime/matrix-action.adoc

@@ -1,3 +1,37 @@
 = Target "Playtime: Matrix action"
 
-include::partial$under-construction.adoc[]
+Invokes a xref:playtime::key-concepts.adoc#matrix[]-related action.
+
+TODO
+
+== Action menu
+
+Stop::
+
+Undo::
+
+Redo::
+
+Build scene::
+
+Set record length mode::
+
+Set custom record length in bars::
+
+Enable/disable click::
+
+Enable/disable MIDI auto-quantize::
+
+Smart record::
+
+Play ignited or enable silence mode::
+
+Enable/disable silence mode::
+
+Panic::
+
+Enable/disable sequencer recording::
+
+Enable/disable sequencer playing::
+
+Tap tempo::