# Control Object

{% embed url="<https://www.youtube.com/watch?v=7P4AI-RaK-o>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=7P4AI-RaK-o>

The **Control Object** action allows you to programmatically control various built-in controllers and objects within your app. This enables dynamic interaction with UI components like scrollable lists, text fields, page views, timers, and more.

> **Note:** The controller must be initialized and assigned to the target widget before this action can control it.

***

#### ✅ Common Use Cases

* Programmatically scrolling to a specific position in a list
* Setting or clearing text in form fields
* Navigating between pages in a PageView
* Controlling timer operations (start, pause, reset)
* Adding data to streams for reactive UI updates
* Managing file operations and API cancellations

***

#### ⚙️ Default Behavior

By default:

| Behavior                 | Description                                                      |
| ------------------------ | ---------------------------------------------------------------- |
| **Controller Required**  | Action fails if the specified controller is not found in context |
| **Method Validation**    | Action fails if the method doesn't exist for the controller type |
| **Parameter Evaluation** | All `args` expressions are evaluated before method execution     |
| **Error Handling**       | Throws exception if controller or method is invalid              |

***

#### 🛠️ How to Use

1. Create a controller variable (e.g., Scroll Controller, Page Controller)
2. Assign the controller to the target widget
3. Add the **Control Object** action to an event
4. Set `dataType` to reference your controller variable
5. Choose the desired `method` from the available options
6. Provide required `args` for the selected method

***

#### 📦 Properties

| Property   | Type       | Required | Description                                     |
| ---------- | ---------- | -------- | ----------------------------------------------- |
| `dataType` | Expression | ✅        | Reference to the controller variable to control |
| `method`   | String     | ✅        | The method name to call on the controller       |
| `args`     | Object     | ❌        | Named arguments to pass to the method           |

***

#### 🎛️ Supported Controller Types & Methods

**Scroll Controller**

Controls scrolling behavior in scrollable widgets (ListView, GridView, etc.).

| Method      | Parameters                                                  | Description                                  |
| ----------- | ----------------------------------------------------------- | -------------------------------------------- |
| `jumpTo`    | `offset: number`                                            | Instantly jump to a specific scroll position |
| `animateTo` | `offset: number`, `durationInMs?: number`, `curve?: string` | Smoothly animate to a scroll position        |

**Page Controller**

Controls page navigation in PageView widgets.

| Method          | Parameters                                                | Description                       |
| --------------- | --------------------------------------------------------- | --------------------------------- |
| `jumpToPage`    | `page: number`                                            | Instantly jump to a specific page |
| `animateToPage` | `page: number`, `durationInMs?: number`, `curve?: string` | Smoothly animate to a page        |
| `nextPage`      | `durationInMs?: number`, `curve?: string`                 | Navigate to the next page         |
| `previousPage`  | `durationInMs?: number`, `curve?: string`                 | Navigate to the previous page     |

**Text Field Controller**

Controls text input in TextFormField widgets.

| Method     | Parameters     | Description                       |
| ---------- | -------------- | --------------------------------- |
| `setValue` | `text: string` | Set the text content of the field |
| `clear`    | -              | Clear all text from the field     |

**Timer Controller**

Controls timer operations in Timer widgets.

| Method   | Parameters | Description                  |
| -------- | ---------- | ---------------------------- |
| `start`  | -          | Start the timer              |
| `resume` | -          | Resume a paused timer        |
| `pause`  | -          | Pause the timer              |
| `reset`  | -          | Reset timer to initial state |

**Stream Controller**

Controls data flow in StreamBuilder widgets.

| Method  | Parameters  | Description            |
| ------- | ----------- | ---------------------- |
| `add`   | `data: any` | Add data to the stream |
| `close` | -           | Close the stream       |

**Async Controller**

Controls async operations in FutureBuilder widgets.

| Method       | Parameters | Description                                |
| ------------ | ---------- | ------------------------------------------ |
| `invalidate` | -          | Invalidate cached data and trigger refresh |

**API Cancel Token**

Controls cancellable API requests.

| Method   | Parameters         | Description                    |
| -------- | ------------------ | ------------------------------ |
| `cancel` | `message?: string` | Cancel the ongoing API request |

**File Controller**

Controls file operations.

| Method   | Parameters | Description     |
| -------- | ---------- | --------------- |
| `delete` | -          | Delete the file |

**Story Controller**

Controls story/carousel navigation.

| Method     | Parameters | Description                 |
| ---------- | ---------- | --------------------------- |
| `next`     | -          | Move to next story item     |
| `previous` | -          | Move to previous story item |

***

#### 💡 Examples

**Scroll to Top of List:**

```json
{
  "type": "controlObject",
  "dataType": "myScrollController",
  "method": "jumpTo",
  "args": {
    "offset": 0
  }
}
```

**Animate to Page:**

```json
{
  "type": "controlObject",
  "dataType": "myPageController",
  "method": "animateToPage",
  "args": {
    "page": 2,
    "durationInMs": 500,
    "curve": "easeOut"
  }
}
```

**Set Text Field Value:**

```json
{
  "type": "controlObject",
  "dataType": "myTextController",
  "method": "setValue",
  "args": {
    "text": "appState.userName"
  }
}
```

**Dynamic Page Navigation:**

```json
{
  "type": "controlObject",
  "dataType": "myPageController",
  "method": "jumpToPage",
  "args": {
    "page": "appState.selectedTab"
  }
}
```

**Timer Control:**

```json
{
  "type": "controlObject",
  "dataType": "myTimerController",
  "method": "start",
  "args": {}
}
```

**Stream Data Update:**

```json
{
  "type": "controlObject",
  "dataType": "myStreamController",
  "method": "add",
  "args": {
    "data": {
      "message": "New data arrived!"
    }
  }
}
```

{% embed url="<https://digiaacademy.portal.trainn.co/share/control-object-examples>" %}

***

#### 🔗 Related Documentation

* [Variables - Controller Types](https://docs.digia.tech/logic-and-interaction/actions/broken-reference) - Learn about creating controller variables
* [Set App State](https://docs.digia.tech/logic-and-interaction/actions/set-app-state) - Update app state variables
* [Set State](https://docs.digia.tech/logic-and-interaction/actions/set-state) - Update page state variables
* [Building UI - Event Handlers](https://docs.digia.tech/logic-and-interaction/event-handlers) - Connect actions to UI events