coocaa_flutter_focus 0.1.0

A Flutter focus management library for TV and remote-control directional navigation.

coocaa_flutter_focus

coocaa_flutter_focus is a standalone Flutter library extracted from a2ui_renderer for TV-style focus management and remote-control directional navigation.

It provides:

• Global arrow-key focus traversal through FocusController.
• Focusable child registration through FocusableWidget.
• Direction-limited and history-aware focus areas through FocusableGroup.
• Automatic Scrollable visibility handling when focus changes.
• Back-key interception with optional Navigator pop fallback.

Installation

Add the package to another Flutter project:

dependencies:
  coocaa_flutter_focus: ^0.1.0

Then import the public library entry:

import 'package:coocaa_flutter_focus/coocaa_flutter_focus.dart';

Quick Start

Initialize the controller once near app startup. If you want the built-in back handling to pop routes, use the controller's navigatorKey.

import 'package:coocaa_flutter_focus/coocaa_flutter_focus.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

void main() {
  FocusController.instance.init();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: FocusController.instance.navigatorKey,
      home: const FocusDemoPage(),
    );
  }
}

class FocusDemoPage extends StatelessWidget {
  const FocusDemoPage({super.key});

  @override
  Widget build(BuildContext context) {
    return FocusableGroup(
      child: Row(
        children: List<Widget>.generate(3, (int index) {
          return Padding(
            padding: const EdgeInsets.all(8),
            child: FocusableWidget(
              autofocus: index == 0,
              onKeyEvent: (FocusNode node, KeyEvent event) {
                return KeyEventResult.ignored;
              },
              onEdge: (FocusNode node, LogicalKeyboardKey direction) {
                debugPrint('Reached focus edge: $direction');
              },
              child: Builder(
                builder: (BuildContext context) {
                  final bool focused = Focus.of(context).hasFocus;
                  return DecoratedBox(
                    decoration: BoxDecoration(
                      color: focused ? Colors.blue : Colors.grey,
                    ),
                    child: SizedBox(
                      width: 120,
                      height: 80,
                      child: Center(child: Text('Item $index')),
                    ),
                  );
                },
              ),
            ),
          );
        }),
      ),
    );
  }
}

Public API

FocusController

FocusController.instance is the global focus coordinator.

• init() registers keyboard and focus listeners.
• dispose() removes listeners and clears controller state.
• requestFocus(node, scrollable: true) requests focus and optionally scrolls the focused widget into view.
• setAlignment(value) sets the default scroll alignment.
• setScrollEdgeOffset(value) keeps focused content at least the configured distance from the viewport edge.
• setScrollDuration(value) and setScrollCurve(value) configure focus-scroll animation.
• addReturnIntercept(callback) intercepts back-key behavior.
• addFocusScrollListener(listener) observes focus-driven scroll state.

FocusableWidget

Wrap every focusable item with FocusableWidget.

• autofocus requests initial focus.
• canRequestFocus enables or disables focus for the item.
• onKeyEvent can handle custom key events before default traversal.
• onDirection can override the next node for a direction.
• onEdge is called when traversal reaches an edge.
• onInitNode exposes the internally owned FocusNode.

FocusableGroup

Use FocusableGroup to describe a logical focus area.

• limitDirections keeps focus inside the group for selected arrow directions.
• memory restores the last focused child when entering the group.
• onGroupFocusChange reports when focus enters or leaves the group.

Development

Run static analysis:

flutter analyze

Run tests:

flutter test