= Projection

This section is about the _ReaLearn Companion_ app, which is a separate software that powers ReaLearn's xref:further-concepts/unit.adoc#projection[] feature.

At the moment, it comes as https://play.google.com/store/apps/details?id=org.helgoboss.realearn_companion[Android app]
and https://realearn.helgoboss.org/[web app].
The iOS app has not been published yet.
The source code is available https://github.com/helgoboss/realearn-companion[here at GitHub].

NOTE: The new xref:helgobox::app.adoc[] will gradually replace the companion app.

== Connecting to ReaLearn

The start screen lets you connect to a specific ReaLearn instance by scanning the QR code that pops up when pressing ReaLearn's <<header-panel,Projection button>>.
It's also possible to enter the connection data manually, in case your device doesn't have a camera or in case you are using the web app (in which QR code scanning often doesn't work so well).
If you are experiencing issues, follow the instructions given by the app and the setup guide which is displayed when pressing the <<Projection>> button!

Please note, if all you want is to open the web app on the computer that also runs REAPER/ReaLearn, you don't need to bother with QR codes or connection data at all.
Just follow the link that is displayed in the setup guide.

ReaLearn allows many Companion apps to connect to it simultaneously, there's no artificial limit.

== Viewing the controller projection

As soon as you have connected, you should be able to see the controller projection, which consists of both the controller layout and the current mapping of its control elements.
If not, the app will give you a hint what's missing.
The control element labels will reflect the labels of your main mappings.

You can tap the screen to make the app bar disappear or reappear.
There's a menu on the right side of the app bar which let's you change various aspects of the appearance.
Just give it a try!
Dark mode combined with high-contrast is especially nice on devices with OLED displays!
All of these settings will be saved on your device, not in ReaLearn's controller preset.

Another thing you can do here is applying two-finger gestures in order to zoom/pinch.

== Editing the controller layout

Pressing the pencil button in the app bar let's you enter edit mode.
As soon as you do that, the control element labels will reflect the labels of your controller mappings and a palette will appear on the side of the screen.

=== Editing basics

You can drag the controls freely from the palette onto the scene and back.
Pressing a control element opens a panel which lets you change its appearance.
The two labels mentioned there are used in the following way:

. If the control element is a composite control element (see below, e.g. push encoder), the first label represents the mapping of the first inner control element (e.g. the encoder) and the second label represents the mapping of the second inner control element (e.g. the button).
See the _Midi Fighter Twister_ <<tested-controllers,controller preset>> for a real-world usage of this feature.
. If the control element is just a normal control element, the second label is usually empty.
Except this control element has more than one main mapping assigned: In that case the second label shows the second main mapping.

Whenever you press the save button (floppy disk) in the app bar, the layout is saved - not on your specific device but as part of ReaLearn's controller preset!
So this same layout will automatically be available to all other connected Companion apps.

You can leave the edit mode by pressing the pencil button again.
This gives you a preview of your current changes.

*Attention:* If you leave the controller projection view (e.g. by pressing the upper left arrow) or if you change your controller preset from within ReaLearn, all non-saved controller layout changes will be lost!
So it's a good idea to save often.
Once saved, there's no undo though.
You can back up temporary states by copying the corresponding controller preset files (on the computer running ReaLearn) to a temporary backup location (see _Save as…_ button documentation in the <<header-panel,Header panel>> section).

=== Composite control elements

If you want one visual control element to contain 2 logical control elements (e.g. a push encoder = encoder + button), just move one control element onto another one - and they will merge into a composite control element.
If you want to undo this merging, move the merged control element back on the palette - they will split up and you can drag them onto the scene again.

=== Batch-editing control elements

Sometimes it's a bit tedious to edit each control element separately.
As soon as you long-press one control element, the Companion app will enter multi-edit mode and you can start adding/removing other control elements to/from the selection by just tapping them.
When you move one element of the selection, all others will also be moved.
You can open the control element appearance panel by long-pressing an element.
All changes made in the panel will immediately be applied to all selected elements.

You can leave multi-edit mode either by unselecting all elements or by (temporarily) leaving the edit mode.

_Known issue:_ In the web app, multi-edit mode currently doesn't work, there's a graphical glitch.

=== Dealing with the grid

You can hide the grid using the app bar menu.
The grid will still have an effect though.

One way to get more fine-grained positioning is by decreasing the grid size.
However, it doesn't go below a certain minimum and changing the grid size after already having positioned lots of elements might not be the best idea.
Usually, the better way is to just expand the scene.
Don't worry, your layout will always fit on the screen, no matter how large the scene actually is in terms of grid squares!

You can enlarge the scene by slightly moving a control element out of the scene.
Do so in small steps and you will automatically have more space at your disposal.
The scene will always be as big as the imaginary rectangle from the top-left control element to the bottom-right control element!
