Services API Reference

Fluttron provides six built-in Host services with typed Dart clients in fluttron_ui.

Quick Start

import 'package:fluttron_ui/fluttron_ui.dart';

final client = FluttronClient();
final fileService = FileServiceClient(client);
final dialogService = DialogServiceClient(client);
final clipboardService = ClipboardServiceClient(client);
final systemService = SystemServiceClient(client);
final storageService = StorageServiceClient(client);
final windowService = WindowServiceClient(client);

Built-in Services

Service	Namespace	Client class	Status
FileService	file	FileServiceClient	✅ Stable
DialogService	dialog	DialogServiceClient	✅ Stable
ClipboardService	clipboard	ClipboardServiceClient	✅ Stable
SystemService	system	SystemServiceClient	✅ Stable
StorageService	storage	StorageServiceClient	✅ Stable
WindowService	window	WindowServiceClient	✅ Stable

FileService (file.*)

Methods:

• readFile(path)
• writeFile(path, content)
• listDirectory(path)
• stat(path)
• createFile(path, {content})
• delete(path)
• rename(oldPath, newPath)
• exists(path)

final content = await fileService.readFile('/Users/me/notes.md');
await fileService.writeFile('/Users/me/notes.md', '# Updated');
final entries = await fileService.listDirectory('/Users/me');

DialogService (dialog.*)

Methods:

• openFile(...)
• openFiles(...)
• openDirectory(...)
• saveFile(...)

final filePath = await dialogService.openFile(
  title: 'Select markdown file',
  allowedExtensions: ['md'],
);

final folderPath = await dialogService.openDirectory(
  title: 'Select workspace',
);

openFile/openDirectory/saveFile return null when user cancels.
openFiles returns an empty list when user cancels.

ClipboardService (clipboard.*)

Methods:

• getText()
• setText(text)
• hasText()

await clipboardService.setText('Hello from Fluttron');
final text = await clipboardService.getText();
final hasText = await clipboardService.hasText();

SystemService (system.*)

Methods:

• getPlatform()

final platform = await systemService.getPlatform();
print('Running on: $platform'); // macos/windows/linux/android/ios

StorageService (storage.*)

Methods:

• set(key, value)
• get(key)

await storageService.set('user.name', 'Alice');
final name = await storageService.get('user.name');

get returns null when key does not exist.

WindowService (window.*)

Control the native application window from UI code.

Methods:

• setTitle(title) — Set the window title bar text
• setSize(width, height) — Resize the window (logical pixels)
• getSize() — Get the current window dimensions
• minimize() — Minimize the window to the dock/taskbar
• maximize() — Toggle maximize / restore the window
• setFullScreen(enabled) — Enter or exit fullscreen mode
• isFullScreen() — Check whether the window is currently fullscreen
• center() — Center the window on the screen
• setMinSize(width, height) — Set the minimum allowed window size

final windowService = WindowServiceClient(client);

// Set the window title dynamically
await windowService.setTitle('My App — Untitled.md');

// Resize the window
await windowService.setSize(1280, 800);

// Read current size
final size = await windowService.getSize();
print('${size['width']}x${size['height']}');

// Center on screen
await windowService.center();

// Toggle fullscreen
final isFullScreen = await windowService.isFullScreen();
await windowService.setFullScreen(!isFullScreen);

// Set minimum window size
await windowService.setMinSize(800, 600);

WindowService is registered by default — no extra setup needed.

Backward Compatibility

FluttronClient.invoke() remains the core transport and is not deprecated.

FluttronClient.getPlatform(), FluttronClient.kvSet(), and FluttronClient.kvGet() are still available but deprecated. Prefer SystemServiceClient and StorageServiceClient.

Custom Services

You can create custom Host services for app-specific needs. See the Custom Services Tutorial for a complete guide.

Quick example:

final client = FluttronClient();
final result = await client.invoke('greeting.greet', {'name': 'Alice'});
print(result['message']); // "Hello, Alice!"

Creating a Custom Service

1. Define the service (Host side):

   class GreetingService extends FluttronService {
     @override
     String get namespace => 'greeting';
     
     @override
     Future<dynamic> handle(String method, Map<String, dynamic> params) async {
       // Handle methods...
     }
   }

2. Register the service:

   void main() {
     final registry = ServiceRegistry()
       ..register(SystemService())
       ..register(StorageService())
       ..register(GreetingService()); // Your custom service
     
     runFluttronHost(registry: registry);
   }

3. Call from UI:

   final result = await client.invoke('greeting.greet', {'name': 'Alice'});

Using Service Packages

For reusable services, use the CLI to create a service package:

fluttron create ./my_service --type host_service --name my_service

This generates both Host implementation and UI client stub packages.

See the Custom Services Tutorial for details.

Generic invoke()

For any service (built-in or custom), you can always call:

final client = FluttronClient();
final result = await client.invoke('namespace.method', {
  'param1': 'value1',
  'param2': 42,
});

Next Steps

• Custom Services Tutorial — Create your own Host services
• Code Generation — Generate type-safe Host/Client code from contracts
• Annotations Reference — Service contract and model annotations
• Host Layer — Deep dive into the Host layer
• Renderer Layer — UI architecture
• Web Views API — Embed Web content