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.