# Data Types

In Digia, **Variables** are containers for data. Every variable has a specific **Type**, which determines what kind of data it can hold and what operations you can perform on it.

We categorize types into two main groups: **Scalar Types** (Primitive values) and **Controller Types** (Objects that control UI).

## Scalar Types

These are the fundamental building blocks of your data.

> \[!TIP] **Data Manipulation**: Data is rarely static. You often need to capitalize a name, calculate a total price, or filter a list. Digia provides built-in **Operations** for each type to handle this. Check the "Operations" column below to see what's possible.

| Type        | Description                                                      | Examples & Use Cases                                                                                                                  | Operations                                                                      |
| ----------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **String**  | Textual data. Can contain letters, numbers, symbols, and emojis. | <p><strong>Ex:</strong> <code>"Hello"</code>, <code>"user\_123"</code><br><strong>Uses:</strong> Usernames, Titles, URLs.</p>         | [String Operations](/logic-and-interaction/adding-logic/string-operations.md)   |
| **Number**  | Numeric values (integers or decimals).                           | <p><strong>Ex:</strong> <code>42</code>, <code>3.14</code>, <code>-10</code><br><strong>Uses:</strong> Prices, Quantity, Ratings.</p> | [Math Operators](/logic-and-interaction/adding-logic/math-operators.md)         |
| **Boolean** | True/False values. Logic gates.                                  | <p><strong>Ex:</strong> <code>true</code>, <code>false</code><br><strong>Uses:</strong> Toggles, Visibility, Conditions.</p>          | [Logical Operators](/logic-and-interaction/adding-logic/logical-operators.md)   |
| **JSON**    | Structured key-value pairs. Standard for API responses.          | <p><strong>Ex:</strong> <code>{"id": 1, "name": "Digia"}</code><br><strong>Uses:</strong> API Data, Config.</p>                       | [JSON Operators](/logic-and-interaction/adding-logic/json-operators.md)         |
| **List**    | Ordered collection of items.                                     | <p><strong>Ex:</strong> <code>\["Apple", "Banana"]</code><br><strong>Uses:</strong> Feeds, Galleries, Menus.</p>                      | [Iterable Operators](/logic-and-interaction/adding-logic/iterable-operators.md) |

***

## Controllers

Controllers are special objects that bind to a Widget to control its behavior programmatically.

> \[!NOTE] **Are Controllers Mandatory?** No. Most widgets work perfectly fine without a controller. You only need to create one if:
>
> * You need to **manipulate the widget from outside** (e.g., a "Reset" button that clears a TextField).
> * You need the widget's **state to persist** (e.g., keeping the scroll position when navigating between tabs).

Below is the list of available methods for each controller.

### ScrollController

Manages the scroll position of a scrollable widget. **Attached to**: `ScrollView`, `ListView`, `GridView`.

| Method        | Arguments                                                                                                | Description                                       |
| ------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| **jumpTo**    | `offset` (Number)                                                                                        | Instantly jumps to the specified scroll position. |
| **animateTo** | <p><code>offset</code> (Number)<br><code>durationInMs</code> (Number)<br><code>curve</code> (String)</p> | Smoothly scrolls to the position over time.       |

### PageController

Controls which page is currently visible in a PageView or Carousel. **Attached to**: `PageView`, `Carousel`.

| Method            | Arguments                                                                                              | Description                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| **nextPage**      | <p><code>durationInMs</code> (Number)<br><code>curve</code> (String)</p>                               | Animates to the next page.                     |
| **previousPage**  | <p><code>durationInMs</code> (Number)<br><code>curve</code> (String)</p>                               | Animates to the previous page.                 |
| **jumpToPage**    | `page` (Number)                                                                                        | Instantly jumps to the specified page index.   |
| **animateToPage** | <p><code>page</code> (Number)<br><code>durationInMs</code> (Number)<br><code>curve</code> (String)</p> | Smoothly animates to the specified page index. |

### TextEditingController

Manages the text content and selection of a text input field. **Attached to**: `TextField`, `TextFormField`.

| Method       | Arguments       | Description                         |
| ------------ | --------------- | ----------------------------------- |
| **setValue** | `text` (String) | Sets the text content of the field. |
| **clear**    | -               | Clears the text field.              |

### StreamController

Manages a stream of data events. Useful for broadcasting updates to a StreamBuilder. **Attached to**: `StreamBuilder`.

| Method    | Arguments     | Description                                                |
| --------- | ------------- | ---------------------------------------------------------- |
| **add**   | `value` (Any) | Pushes a new value to the stream, triggering a UI rebuild. |
| **close** | -             | Closes the stream.                                         |

### TimerController

Controls a countdown or stopwatch timer. **Attached to**: `Timer` widget.

| Method     | Arguments | Description                               |
| ---------- | --------- | ----------------------------------------- |
| **start**  | -         | Starts the timer.                         |
| **pause**  | -         | Pauses the timer.                         |
| **resume** | -         | Resumes the timer from where it left off. |
| **reset**  | -         | Resets the timer to its initial state.    |

### AsyncController

Manages the state of an asynchronous operation (Future). **Attached to**: `AsyncBuilder` (FutureBuilder).

| Method         | Arguments | Description                                     |
| -------------- | --------- | ----------------------------------------------- |
| **invalidate** | -         | Forces the Future to re-run (refresh the data). |

### StoryController

Controls the playback and navigation of a Story widget. **Attached to**: `Story` widget.

| Method       | Arguments        | Description                           |
| ------------ | ---------------- | ------------------------------------- |
| **play**     | -                | Plays the story.                      |
| **pause**    | -                | Pauses the story.                     |
| **next**     | -                | Skips to the next story item.         |
| **previous** | -                | Goes back to the previous story item. |
| **jumpTo**   | `index` (Number) | Jumps to a specific story index.      |
| **mute**     | -                | Mutes the story audio.                |
| **unMute**   | -                | Unmutes the story audio.              |

## How to use a Controller?

1. **Define it**: specific the controller type in your Page State or App State.
2. **Attach it**: Select the widget (e.g., ListView) and bind its `controller` property to your variable.
3. **Call it**: In an Action (like "On Tap"), choose **Control Object** and select your controller variable to trigger a method (like `animateTo`).


---

# 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/data-and-state/data-types.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.