Next generation modular control surface
TouchOSC Manual

Editor · Document

A document is the top-level container for all controls and the root node of the control hierarchy tree.

A document has properties that define the display size and background color, global routing options for messages and optional notes by the creator.

A document can also have a script attached and define control callback functions, which will be called before any other script callbacks and allow to capture certain events globally before they are forwarded to the target controls. See Object Callback Functions for details.

Note that documents will be scaled proportionally to the available display size when rendered in control surface mode. For performance reasons, it is advised to choose the smallest possible size and aspect ratio to comfortably position and edit your layout's controls, and let the application handle the final scaling for presentation.


The width of the document.


The height of the document.


The background color of the document.



The global routing matrix determines which types of received messages or input will cause any other type of configured messages to be sent or suppressed.

The left column lists all possible types of inputs that can change a control's values. The bottom row lists all possible types of messages that can be sent in response to a control's value changing.

Any event changing a control's value will be tagged with the type of action that caused the value change. When a control's value changes, the application then compiles a list of all enabled messages that are being triggered by this value change. The application will then consult the routing options of the document to determine which of these messages will be sent depending on the type of event that caused the initial value change.

For example: If any control has an enabled MIDI message that will update the control's x value on reception, and an enabled OSC message that specifies the x value as a trigger, the incoming MIDI message will only cause the OSC message to be sent if the cross at the intersection between MIDI input in the left column and OSC output in the bottom row is checked.


Each document can optionally have creator's name and comments attached to it. The Comments button in the document properties panel will be highlighted if these are not empty.

At the bottom of the dialog, and also in the preferences, there is an option to automatically open the creator's comments after loading the document, if any.

We do encourage users to leave this option enabled, as there might be helpful tips, tricks and guidance attached to a document. Also, in our humble opinion, it's just nice to acknowledge the person sharing their work.

Document Tree

The document tree displays a hierarchical view of all controls in the document.

Controls can be selected and the current selection will be highlighted in the tree structure. For each control the visible and locked properties can be toggled with the eye and lock icons on the right respectively.

Controls that are containers and hence can contain child controls will be displayed as tree nodes that can be expanded and collapsed using the arrow icon to the left of the control name.

Cookie Policy

We use cookies to deliver website content. By continuing without changing your preferences, you agree to our use of cookies.