fdevs_pops

A powerful and flexible Flutter package for managing overlays such as dialogs, snackbars, and custom overlays with unique identifiers. It simplifies overlay management by allowing multiple overlays to coexist, providing easy show/dismiss functionality, and supporting auto-hide capabilities.

Features

• Unique Overlay Management: Assign unique IDs to each overlay for precise control over showing, dismissing, and checking their status.
• Multiple Overlay Support: Handle multiple overlays simultaneously without conflicts.
• Dialog Support: Built-in extensions for displaying modal dialogs with customizable barriers and auto-hide options.
• Snackbar Support: Convenient methods for showing snackbars at the bottom of the screen with auto-hide functionality.
• Custom Overlays: Create fully customizable overlays with alignment, barriers, and positioning options.
• Async Results: Overlays can return results asynchronously, making it easy to handle user interactions.
• Auto-Hide: Optional auto-hide durations for overlays to disappear automatically.
• Queue Management: Internal queue system to manage overlay order and lifecycle.
• Easy Initialization: Simple setup with a navigator key for seamless integration into Flutter apps.

Getting started

Prerequisites

• Flutter SDK: ^1.17.0
• Dart SDK: ^3.9.2

Installation

Add fdevs_pops to your pubspec.yaml:

dependencies:
  fdevs_pops: ^0.0.1

Then run:

flutter pub get

Setup

Initialize the FPops manager in your app's root widget by wrapping your MaterialApp with FPops.init() and providing a GlobalKey<NavigatorState>:

import 'package:flutter/material.dart';
import 'package:fdevs_pops/fdevs_pops.dart';

void main() {
  runApp(const MyApp());
}

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

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final GlobalKey<NavigatorState> _navigatorKey = GlobalKey<NavigatorState>();

  @override
  Widget build(BuildContext context) {
    return FPops.init(
      rootNavigatorKey: _navigatorKey,
      child: MaterialApp(
        navigatorKey: _navigatorKey,
        home: const HomePage(),
      ),
    );
  }
}

Usage

Showing a Dialog

final result = await FPops.I.showDialog<String>(
  id: 'my_dialog',
  builder: (_) => AlertDialog(
    title: Text('Confirm Action'),
    content: Text('Are you sure you want to proceed?'),
    actions: [
      TextButton(
        onPressed: () => FPops.I.dismiss('my_dialog', 'cancelled'),
        child: Text('Cancel'),
      ),
      ElevatedButton(
        onPressed: () => FPops.I.dismiss('my_dialog', 'confirmed'),
        child: Text('Confirm'),
      ),
    ],
  ),
  barrierDismissible: true,
  autoHideDuration: null, // No auto-hide for dialogs
);

if (result == 'confirmed') {
  // Handle confirmation
}

Showing a Snackbar

await FPops.I.showSnackBar(
  id: 'my_snackbar',
  builder: (_) => Container(
    padding: EdgeInsets.all(16),
    color: Colors.green,
    child: Text('Operation completed successfully!'),
  ),
  autoHideDuration: Duration(seconds: 3),
);

Showing a Custom Overlay

await FPops.I.showCustom(
  id: 'my_custom_overlay',
  builder: (_) => Container(
    width: 200,
    height: 200,
    color: Colors.blue,
    child: Center(child: Text('Custom Overlay')),
  ),
  alignment: Alignment.topRight,
  barrierDismissible: true,
  barrierColor: Colors.black.withOpacity(0.5),
  autoHideDuration: Duration(seconds: 5),
);

Checking Overlay Status

bool isOpen = FPops.I.isOverlayOpen('my_dialog');

Dismissing an Overlay Manually

FPops.I.dismiss('my_dialog');

Clearing All Overlays

FPops.I.clearAll();

For more detailed examples, see the /example folder.

API Reference

FPops Class

The main class for managing overlays.

Methods

• static Widget init({required GlobalKey<NavigatorState> rootNavigatorKey, required Widget child}): Initializes the FPops manager.
• void show(String id, OverlayConfig config, {Completer<Object?>? completer}): Shows an overlay with the given ID and configuration.
• void dismiss<T>(String id, [T? result]): Dismisses the overlay with the given ID and optional result.
• bool isOverlayOpen(String id): Checks if an overlay with the given ID is currently active.
• void clearAll(): Clears all active overlays.

Extensions

FPopsDialogExtension

• Future<T?> showDialog<T>({required String id, required WidgetBuilder builder, bool barrierDismissible = true, Color? barrierColor = Colors.black54, Duration? autoHideDuration}): Shows a dialog overlay.

FPopsSnackBarExtension

• Future<T?> showSnackBar<T>({required String id, required WidgetBuilder builder, Duration? autoHideDuration = Durations.medium4}): Shows a snackbar overlay.

FPopsCustomExtension

• Future<T?> showCustom<T>({required String id, required WidgetBuilder builder, Alignment alignment = Alignment.center, bool barrierDismissible = false, Color? barrierColor, Duration? autoHideDuration}): Shows a custom overlay.

OverlayType Enum

• dialog: For dialog overlays.
• snackbar: For snackbar overlays.
• custom: For custom overlays.

OverlayConfig Class

• OverlayConfig({required WidgetBuilder builder, required OverlayType type}): Configuration for an overlay.

Additional information

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an Issue on GitHub.

Issues

If you encounter any issues or have feature requests, please file them on the GitHub Issues page.

License

This package is licensed under the LICENSE file.

Changelog

See CHANGELOG.md for version history and updates.

Resources

• Flutter Documentation
• Dart Package Publishing Guide
• Writing Package Pages