# 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](broken://pages/a8ZkBLioPk7BWmXQpQnj#controller-types) - Learn about creating controller variables
* [Set App State](/logic-and-interaction/actions/set-app-state.md) - Update app state variables
* [Set State](/logic-and-interaction/actions/set-state.md) - Update page state variables
* [Building UI - Event Handlers](/logic-and-interaction/event-handlers.md) - Connect actions to UI events


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/logic-and-interaction/actions/control-object.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.