> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/controller/overview/controller-overview.md).

# Controller Overview

Use Controllers in Grid Studio to build physical and on-screen control surfaces that trigger workflows, hold values, and drive parameters.

<figure><img src="https://1089527861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1lzYXYTbE4lxMSWTSQTM%2Fuploads%2F4i4PZVLPLU393XJifzFT%2FController%20Overview%20Intro%20Img.png?alt=media&amp;token=50e532c0-ac0c-45ed-b645-3cc709ce0980" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Make sure to update the Grid original widgets from the library to have access to the new widgets for Controller Buttons
{% endhint %}

A running show, installation, or technical system usually needs someone to operate it: start a sequence, switch a scene on or off, raise a level, step through a list of options. A Controller gives the operator a surface for this, made of buttons, encoders, and touch strips.

Grid Studio provides two kinds of Controller:

* **Virtual Controller** – an on-screen control surface that needs no hardware. It is the general form of a Controller.
* **StreamDeck** – a more specific use of the Virtual Controller. It works in the same way and adds the ability to connect a physical StreamDeck.

Because a StreamDeck is a Virtual Controller with a physical device, everything learned about one applies to the other.

## What You Can Build

Typical examples include:

* Operator panels that trigger workflows, cue lists, and other actions
* On/off buttons that keep and display their state
* Increase and decrease buttons for levels, speeds, positions, or indices
* Encoders for smooth or fine adjustment of a value
* Buttons that cycle through a list of values or presets
* Several controls that all operate the same parameter
* The same control surface available on screen and on hardware

***

## The Controller Model

Every Controller follows the same structure:

```
Controller
├── Page 1
│   ├── Button
│   ├── Button
│   ├── Encoder
│   └── Touch Strip
├── Page 2
│   └── ...
└── Page 3
    └── ...
```

A **Page** holds a set of **Controller Buttons**. The Controller Button is the general building block. It has two specialised versions:

* **Encoders** – a rotary control that can be turned and pushed.
* **Touch Strips** – a touch-sensitive strip that shows a value and reacts to tap and swipe.&#x20;

{% hint style="info" %}
Because encoders and touch strips are versions of the Controller Button, they share its parts and most of its settings. Each specialised button only adds what is unique to it.\
Encoder and Touch Strips are available on the StreamDeck Plus and StreamDeck Plus XL.
{% endhint %}

### Behavior and Appearance

A Controller Button has two separate jobs:

* **Behavior** is what the button does when it is used. This is decided by programming the button: its type, its values, the parameter it targets, and the events and workflows linked to it.
* **Appearance** is how the button looks. This is decided by its widget.

A button will still function without a widget with basic customization options, but widgets provide more design options and greater range of feedback. There are pre-built widgets available, but just like other widgets these can be customized or user can create their own widgets as well.

### The Controller Editor

Both kinds of Controller are configured and operated in the **Controller Editor**. It is opened with the **Open Editor** button in the Inspector, or selecting the Controller view from the top menu and it follows the Controller that is selected in the Project Tree.

In edit mode the editor is used to build pages and buttons. In play mode it can be used to operate the Controller directly on screen, which makes it possible to test a control surface without touching the hardware.

### How This Section Is Organized

The section is organized from the general to the specific:

* [**Virtual Controller**](/grid/controller/overview/virtual-controller.md) explains the general concept. **StreamDeck** only covers what is added by the physical device.
* [**Controller Buttons**](/grid/controller/controller-buttons/controller-buttons.md) describes the button in detail. **Encoders** and **Touch Strips** only cover what makes them different.
* [**Programming a Button**](/grid/controller/controller-buttons/controller-buttons/programming-a-button.md) covers everything that decides what a button does. [**Widgets**](/grid/controller/controller-buttons/controller-buttons/widgets.md) covers how it looks.

### Where to Start

If you are building a control surface for the first time:

1. Create a **Virtual Controller**, or a **StreamDeck** if you are using a physical hardware.
2. Click **Open Editor** in the Inspector to open the **Controller Editor**.
3. Organize the surface into **Pages**.
4. Configure **Controller Buttons**.
5. Assign a **Widget** to design how each button looks if you like.
6. **Program** what each button does.

The **Reference** page lists every property of buttons, encoders, and touch strips.