Finish describing Playtime user interface elements

doc/playtime/modules/ROOT/nav.adoc

@@ -2,18 +2,23 @@
 * xref:installation.adoc[]
 * xref:key-concepts.adoc[]
 * xref:user-interface.adoc[]
+** xref:user-interface/general.adoc[]
 ** xref:user-interface/title-bar.adoc[]
 ** xref:user-interface/navigation-bar.adoc[]
 ** xref:user-interface/toolbar.adoc[]
 ** xref:user-interface/matrix-area.adoc[]
 ** xref:user-interface/track-area.adoc[]
 ** xref:user-interface/inspector.adoc[]
 *** xref:user-interface/inspector/matrix.adoc[]
+*** xref:user-interface/inspector/matrix/playback.adoc[]
+*** xref:user-interface/inspector/matrix/recording.adoc[]
 *** xref:user-interface/inspector/column.adoc[]
+*** xref:user-interface/inspector/column/playback.adoc[]
+*** xref:user-interface/inspector/column/recording.adoc[]
+*** xref:user-interface/inspector/track.adoc[]
 *** xref:user-interface/inspector/row.adoc[]
 *** xref:user-interface/inspector/slot.adoc[]
 *** xref:user-interface/inspector/clip.adoc[]
-*** xref:user-interface/inspector/track.adoc[]
 ** xref:user-interface/info-panel.adoc[]
 ** xref:user-interface/purchase-and-activate-dialog.adoc[]
 ** xref:user-interface/settings-dialog.adoc[]

doc/playtime/modules/ROOT/pages/user-interface/arrangement-writing-mode-dialog.adoc

@@ -1,5 +1,7 @@
 = Arrangement writing mode dialog
 
+This dialog opens when pressing the xref:user-interface/toolbar.adoc#toolbar-write-to-arrangement[image:generated/screenshots/elements/toolbar/write-to-arrangement.png[]] button in the title bar and the current arrangement is dirty. It gives you multiple options how to deal with the fact that there are already items in the arrangement.
+
 image::generated/screenshots/main/arrangement-writing-mode.png[]
 
 include::partial$generated/elements/arrangement-writing-mode/replace.adoc[]

doc/playtime/modules/ROOT/pages/user-interface/general.adoc

@@ -0,0 +1,58 @@
+= General usage
+
+This page describes the basic usage of common user interface elements in Playtime.
+
+== Drag fields
+
+image::generated/screenshots/elements/toolbar/tempo.png[]
+
+A drag field allows you to adjust numeric values in various ways.
+
+include::partial$user-interface/interactions/mouse-dragging.adoc[]
+include::partial$user-interface/interactions/mouse-wheel-scrolling.adoc[]
+include::partial$user-interface/interactions/touchpad-panning.adoc[]
+include::partial$user-interface/interactions/text-entry.adoc[]
+include::partial$user-interface/interactions/reset-to-default.adoc[]
+include::partial$user-interface/interactions/fine-adjustment.adoc[]
+
+== Knobs
+
+image::generated/screenshots/elements/toolbar/play-rate.png[]
+
+A knob allows you to adjust numeric values in various ways.
+
+include::partial$user-interface/interactions/mouse-dragging.adoc[]
+include::partial$user-interface/interactions/mouse-wheel-scrolling.adoc[]
+include::partial$user-interface/interactions/touchpad-panning.adoc[]
+include::partial$user-interface/interactions/text-entry.adoc[]
+include::partial$user-interface/interactions/reset-to-default.adoc[]
+include::partial$user-interface/interactions/fine-adjustment.adoc[]
+
+== Sliders
+
+image::generated/screenshots/elements/track-panel/volume.png[]
+
+A slider allows you to adjust numeric values in various ways.
+
+include::partial$user-interface/interactions/mouse-dragging.adoc[]
+include::partial$user-interface/interactions/mouse-wheel-scrolling.adoc[]
+include::partial$user-interface/interactions/touchpad-panning.adoc[]
+include::partial$user-interface/interactions/reset-to-default.adoc[]
+
+== Search lists
+
+image::generated/screenshots/main/sequences.png[]
+
+Search lists allow you to pick an item from a potentially large list.
+
+icon:search[] Search::
+Simply enter text to drill the list down to items matching your search text.
+
+icon:keyboard-o[] Navigate::
+Press kbd:[↑] or kbd:[↓] to navigate within the list of items.
+
+↕ Scroll::
+Scroll within the list using the scrollbar on the right or using the mousewheel.
+
+icon:mouse-pointer[] Select::
+Click the item or press kbd:[Enter] to select it.

doc/playtime/modules/ROOT/pages/user-interface/info-panel.adoc

@@ -12,6 +12,8 @@ This tab displays information about the current state of the Playtime engine.
 
 include::partial$generated/elements/info-panel/stats/tempo-buffer-size.adoc[]
 
+See xref:user-interface/settings-dialog.adoc#settings-tempo-latency[].
+
 include::partial$generated/elements/info-panel/stats/pre-buffered-blocks-playing-min.adoc[]
 
 include::partial$generated/elements/info-panel/stats/pre-buffered-blocks-playing-avg.adoc[]
@@ -23,5 +25,3 @@ include::partial$generated/elements/info-panel/stats/pre-buffer-fallback-count.a
 include::partial$generated/elements/info-panel/stats/pre-buffer-miss-count.adoc[]
 
 include::partial$generated/elements/info-panel/warnings.adoc[]
-
-In certain situations, you might see a warning button, that upon clicking will show you further details about the warnings.

doc/playtime/modules/ROOT/pages/user-interface/inspector/clip.adoc

@@ -1,23 +1,152 @@
 = Clip inspector
 
 include::partial$generated/elements/inspector/clip/overdub.adoc[]
+
 include::partial$generated/elements/inspector/clip/quantize.adoc[]
+
+See xref:user-interface/inspector/matrix/playback.adoc#inspector-matrix-midi-quantization-grid[].
+
+[NOTE]
+====
+Playtime uses its own quantization algorithm, but it remembers the original event positions in a way that is compatible with REAPER.
+
+If you open a MIDI clip quantized by Playtime in REAPER's MIDI editor, you will see that the MIDI events are quantized there as well, and you have the possibility to unquantize directly in the MIDI editor.
+
+Vice versa, Playtime detects correctly if a clip has been quantized in REAPER's MIDI editor.
+That means you can use both quantization methods interchangeably!
+====
+
 include::partial$generated/elements/inspector/clip/name.adoc[]
+
+TIP: Another way to change the sanem is to press kbd:[F2] when the slot is selected.
+
 include::partial$generated/elements/inspector/clip/looped.adoc[]
+
+See xref:key-concepts.adoc#loop[] and xref:key-concepts.adoc#one-shot[].
+
 include::partial$generated/elements/inspector/clip/volume.adoc[]
+
 include::partial$generated/elements/inspector/clip/pitch.adoc[]
+
+For audio, pitch shifting is done using REAPER's pitch-shifting/time-stretching engine with the clip's xref:user-interface/inspector/clip.adoc#inspector-clip-time-stretch-mode[].
+
+include::partial$clip-prop-applied-quantized.adoc[]
+
 include::partial$generated/elements/inspector/clip/velocity-sensitivity.adoc[]
+
 include::partial$generated/elements/inspector/clip/source-info.adoc[]
+
+See xref:key-concepts.adoc#source[].
+
 include::partial$generated/elements/inspector/clip/color.adoc[]
+
 include::partial$generated/elements/inspector/clip/start-timing.adoc[]
+
+See xref:key-concepts.adoc#clip-start-timing[].
+
+include::partial$generated/elements/inspector/clip/start-timing/immediately.adoc[]
+
+include::partial$generated/elements/inspector/clip/start-timing/custom.adoc[]
+
+TIP: In most cases, picking one of the pre-defined quantizations (e.g. **1 bar**) should be sufficient.
+
 include::partial$generated/elements/inspector/clip/stop-timing.adoc[]
+include::partial$generated/elements/inspector/clip/stop-timing/like-start-timing.adoc[]
+include::partial$generated/elements/inspector/clip/stop-timing/until-end-of-clip.adoc[]
+
+CAUTION: This can easily lead to unintentional concurrent playback of clips when using xref:user-interface/inspector/column/playback.adoc#inspector-column-exclusive-mode[].
+
+include::partial$generated/elements/inspector/clip/stop-timing/immediately.adoc[]
+include::partial$generated/elements/inspector/clip/stop-timing/custom.adoc[]
+
+
 include::partial$generated/elements/inspector/clip/sync-to-project-tempo.adoc[]
+
+TIP: This alone doesn't guarantee yet that your clip will be played in time.
+It's just one of multiple ingredients for in-sync playback.
+See xref:key-concepts.adoc#in-sync[].
+
+NOTE: This is comparable to REAPER's item time base setting.
+In fact, this will be translated to different item time base settings when xref:user-interface/toolbar.adoc#toolbar-write-to-arrangement[writing to the arrangement].
+
 include::partial$generated/elements/inspector/clip/tempo.adoc[]
+
+TIP: This is available for audio clips only.
+MIDI clips are by its very nature tempo-agnostic.
+
+include::partial$clip-prop-applied-quantized.adoc[]
+
 include::partial$generated/elements/inspector/clip/time-signature.adoc[]
+
 include::partial$generated/elements/inspector/clip/downbeat.adoc[]
+
+TIP: This can be used to realize an link:https://en.wikipedia.org/wiki/Anacrusis[Anacrusis] (or pick-up beat).
+See xref:user-interface/inspector/matrix/recording.adoc#inspector-matrix-recording-detect-downbeat[].
+
 include::partial$generated/elements/inspector/clip/start-position.adoc[]
+
+TIP: This setting works for both audio and MIDI clips.
+When using it on MIDI clips, be aware that the REAPER MIDI editor doesn't indicate the start position in any way, which can be confusing.
+If you want to permanently change the start position permanently, it's usually better to adjust the underlying MIDI data.
+
+include::partial$user-interface/clip-prop-adjust-in-beats.adoc[]
+
+include::partial$clip-prop-applied-quantized.adoc[]
+
 include::partial$generated/elements/inspector/clip/length.adoc[]
-include::partial$generated/elements/inspector/clip/reset-behavior.adoc[]
+
+The value **Original** means that the source will end at the original end of the source material.
+
+Use the ÷2 and ×2 buttons to halve or double the current length.
+
+TIP: This setting works for both audio and MIDI clips.
+When using it on MIDI clips, be aware that the REAPER MIDI editor doesn't indicate the length in any way, which can be confusing.
+If you want to permanently change the start position permanently, it's usually better to adjust the underlying MIDI data.
+
+include::partial$user-interface/clip-prop-adjust-in-beats.adoc[]
+
+include::partial$clip-prop-applied-quantized.adoc[]
+
+include::partial$generated/elements/inspector/clip/midi-reset-behavior.adoc[]
+
+include::partial$generated/elements/inspector/clip/midi-reset-behavior/none.adoc[]
+include::partial$generated/elements/inspector/clip/midi-reset-behavior/light-left.adoc[]
+include::partial$generated/elements/inspector/clip/midi-reset-behavior/extreme-left.adoc[]
+include::partial$generated/elements/inspector/clip/midi-reset-behavior/light-right.adoc[]
+include::partial$generated/elements/inspector/clip/midi-reset-behavior/extreme-right.adoc[]
+
 include::partial$generated/elements/inspector/clip/midi-channel.adoc[]
+
+include::partial$generated/elements/inspector/clip/source-fades.adoc[]
+
+include::partial$generated/elements/inspector/clip/time-stretch-mode.adoc[]
+
+Playtime uses this algorithm whenever it needs to adjust beat-based audio clips to the current tempo while keeping the original pitch, but also when xref:user-interface/inspector/clip.adoc#inspector-clip-pitch[adjusting the pitch] of audio clips.
+
+include::partial$clip-prop-applied-quantized.adoc[]
+
+include::partial$generated/elements/inspector/clip/time-stretch-mode/vari-speed.adoc[]
+include::partial$generated/elements/inspector/clip/time-stretch-mode/keeping-pitch.adoc[]
+
+When selecting this option, you can choose between all pitch shifting modes and corresponding sub modes that are supported by REAPER.
+
+include::partial$generated/elements/inspector/clip/resample-mode.adoc[]
+
+Playtime uses resampling in the following cases:
+
+. Vari-speed time stretching
+. Adjusting to play rate changes
+. Adjusting clips that have a sample rate other than the project/hardware sample rate
+
+You can choose between all resample modes that are supported by REAPER.
+
+include::partial$clip-prop-applied-quantized.adoc[]
+
 include::partial$generated/elements/inspector/clip/source-cut-start.adoc[]
-include::partial$generated/elements/inspector/clip/source-cut-length.adoc[]
+
+include::partial$clip-prop-applied-quantized.adoc[]
+
+
+include::partial$generated/elements/inspector/clip/source-cut-length.adoc[]
+
+include::partial$clip-prop-applied-quantized.adoc[]

doc/playtime/modules/ROOT/pages/user-interface/inspector/column.adoc

@@ -2,13 +2,10 @@
 
 You will see this when selecting a xref:user-interface/matrix-area.adoc#column-cell[].
 
-include::partial$generated/elements/inspector/column/playback-track.adoc[]
-include::partial$generated/elements/inspector/column/custom-name.adoc[]
-include::partial$generated/elements/inspector/column/exclusive-mode.adoc[]
-include::partial$generated/elements/inspector/column/follow-scenes.adoc[]
-include::partial$generated/elements/inspector/column/start-timing.adoc[]
-include::partial$generated/elements/inspector/column/stop-timing.adoc[]
-include::partial$generated/elements/inspector/column/trigger-mode.adoc[]
-include::partial$generated/elements/inspector/column/velocity-sensitivity.adoc[]
-include::partial$generated/elements/inspector/column/time-stretch-mode.adoc[]
-include::partial$generated/elements/inspector/column/resample-mode.adoc[]
+This inspector is divided into two areas:
+
+xref:user-interface/inspector/column/playback.adoc[]::
+Settings that are mainly about playing clips
+
+xref:user-interface/inspector/column/recording.adoc[]::
+Settings that are mainly about recording clips

doc/playtime/modules/ROOT/pages/user-interface/inspector/column/playback.adoc

@@ -0,0 +1,37 @@
+= Column playback settings
+
+include::partial$generated/elements/inspector/column/playback-track.adoc[]
+
+See xref:key-concepts.adoc#column-track[].
+
+include::partial$generated/elements/inspector/column/custom-name.adoc[]
+
+include::partial$generated/elements/inspector/column/exclusive-mode.adoc[]
+
+include::partial$generated/elements/inspector/column/follow-scenes.adoc[]
+
+include::partial$generated/elements/inspector/column/start-timing.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-start-timing[].
+
+include::partial$generated/elements/inspector/column/stop-timing.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-stop-timing[].
+
+include::partial$generated/elements/inspector/column/trigger-mode.adoc[]
+include::partial$generated/elements/inspector/column/trigger-mode/toggle.adoc[]
+include::partial$generated/elements/inspector/column/trigger-mode/momentary.adoc[]
+include::partial$generated/elements/inspector/column/trigger-mode/retrigger.adoc[]
+
+
+include::partial$generated/elements/inspector/column/velocity-sensitivity.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-velocity-sensitivity[].
+
+include::partial$generated/elements/inspector/column/time-stretch-mode.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-time-stretch-mode[].
+
+include::partial$generated/elements/inspector/column/resample-mode.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-resample-mode[].

doc/playtime/modules/ROOT/pages/user-interface/inspector/column/recording.adoc

@@ -0,0 +1,3 @@
+= Column recording settings
+
+NOTE: There are no column-specific recording settings yet. This section is reserved for the future,

doc/playtime/modules/ROOT/pages/user-interface/inspector/matrix.adoc

@@ -2,21 +2,10 @@
 
 You will see this when selecting the xref:user-interface/matrix-area.adoc#matrix-cell[].
 
-include::partial$generated/elements/inspector/matrix/start-timing.adoc[]
-include::partial$generated/elements/inspector/matrix/stop-timing.adoc[]
-include::partial$generated/elements/inspector/matrix/trigger-mode.adoc[]
-include::partial$generated/elements/inspector/matrix/velocity-sensitivity.adoc[]
-include::partial$generated/elements/inspector/matrix/activate-slot-on-trigger.adoc[]
-include::partial$generated/elements/inspector/matrix/transport-sync.adoc[]
-include::partial$generated/elements/inspector/matrix/midi-quantization-grid.adoc[]
-include::partial$generated/elements/inspector/matrix/time-stretch-mode.adoc[]
-include::partial$generated/elements/inspector/matrix/resample-mode.adoc[]
+This inspector is divided into two areas:
 
-include::partial$generated/elements/inspector/matrix/recording-looped.adoc[]
-include::partial$generated/elements/inspector/matrix/limit-recording-length.adoc[]
-include::partial$generated/elements/inspector/matrix/recording-length.adoc[]
-include::partial$generated/elements/inspector/matrix/recording-detect-downbeat.adoc[]
-include::partial$generated/elements/inspector/matrix/recording-auto-quantize.adoc[]
-include::partial$generated/elements/inspector/matrix/recording-sync-to-project-tempo.adoc[]
-include::partial$generated/elements/inspector/matrix/recording-midi-reset-behavior.adoc[]
-include::partial$generated/elements/inspector/matrix/tempo-detection-range.adoc[]
+xref:user-interface/inspector/matrix/playback.adoc[]::
+Settings that are mainly about playing clips
+
+xref:user-interface/inspector/matrix/recording.adoc[]::
+Settings that are mainly about recording clips

doc/playtime/modules/ROOT/pages/user-interface/inspector/matrix/playback.adoc

@@ -0,0 +1,35 @@
+= Matrix playback settings
+
+include::partial$generated/elements/inspector/matrix/start-timing.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-start-timing[].
+
+include::partial$generated/elements/inspector/matrix/stop-timing.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-stop-timing[].
+
+include::partial$generated/elements/inspector/matrix/trigger-mode.adoc[]
+
+See xref:user-interface/inspector/column/playback.adoc#inspector-column-trigger-mode[].
+
+include::partial$generated/elements/inspector/matrix/velocity-sensitivity.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-velocity-sensitivity[].
+
+include::partial$generated/elements/inspector/matrix/activate-slot-on-trigger.adoc[]
+
+include::partial$generated/elements/inspector/matrix/transport-sync.adoc[]
+
+include::partial$generated/elements/inspector/matrix/midi-quantization-grid.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-quantize[].
+
+TIP: If you want more advanced quantization options, do quantization in REAPER's MIDI editor instead.
+
+include::partial$generated/elements/inspector/matrix/time-stretch-mode.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-time-stretch-mode[].
+
+include::partial$generated/elements/inspector/matrix/resample-mode.adoc[]
+
+See xref:user-interface/inspector/clip.adoc#inspector-clip-resample-mode[].