Control Object

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:

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

Animate to Page:

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

Set Text Field Value:

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

Dynamic Page Navigation:

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

Timer Control:

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

Stream Data Update:

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

https://digiaacademy.portal.trainn.co/share/control-object-examplesdigiaacademy.portal.trainn.co

---

🔗 Related Documentation

• Variables - Controller Types - Learn about creating controller variables

• Set App State - Update app state variables

• Set State - Update page state variables

• Building UI - Event Handlers - Connect actions to UI events