Support custom ToastGravity to Position Mapping (#533)

* ✨ add custom position mapping for toasts

* 🐛 feat(example): add custom position mapping for toast messages

Author: wilinz

example/lib/toast_context.dart

@@ -36,6 +36,32 @@ class _ToastContextState extends State<ToastContext> {
     );
   }
 
+  _showCustomPositionMappingToast() {
+    final customPositionMapping = (child, gravity) {
+      switch (gravity) {
+        case ToastGravity.TOP:
+          return Positioned(top: 150.0, left: 24.0, right: 24.0, child: child);
+        case ToastGravity.BOTTOM:
+          return Positioned(
+              bottom: 200, left: 24.0, right: 24.0, child: child);
+        default:
+          return null;
+      }
+    };
+    fToast.showToast(
+      child: Text("This is the custom ToastGravity.BOTTOM"),
+        gravity: ToastGravity.BOTTOM,
+        toastDuration: Duration(seconds: 2),
+        customPositionMapping: customPositionMapping,
+    );
+
+    fToast.showToast(
+      child: Text("This is the default ToastGravity.BOTTOM"),
+      gravity: ToastGravity.BOTTOM,
+      toastDuration: Duration(seconds: 2),
+    );
+  }
+
   _showBuilderToast() {
     fToast.showToast(
         child: toast,
@@ -149,6 +175,9 @@ class _ToastContextState extends State<ToastContext> {
                 _showToast();
               },
             ),
+            SizedBox(
+              height: 24.0,
+            ),
             ElevatedButton(
               child: Text("Show Custom Toast via PositionedToastBuilder"),
               onPressed: () {
@@ -158,6 +187,15 @@ class _ToastContextState extends State<ToastContext> {
             SizedBox(
               height: 24.0,
             ),
+            ElevatedButton(
+              child: Text("Show Custom Toast via CustomPositionMapping"),
+              onPressed: () {
+                _showCustomPositionMappingToast();
+              },
+            ),
+            SizedBox(
+              height: 24.0,
+            ),
             ElevatedButton(
               child: Text("Custom Toast With Close Button"),
               onPressed: () {

lib/fluttertoast.dart

@@ -3,6 +3,14 @@ import 'dart:async';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 
+/// Signature for a function that defines custom position mapping for a toast
+///
+/// [child] is the toast widget to be positioned.
+/// [gravity] is the gravity option for the toast which can be used to determine the position.
+/// The function should return a [Widget] that defines the position of the toast.
+/// If the position is not handled by the custom logic, return `null` to fall back to default logic.
+typedef ToastPositionMapping = Widget? Function(Widget child, ToastGravity? gravity);
+
 /// Toast Length
 /// Only for Android Platform
 enum Toast {
@@ -233,6 +241,7 @@ class FToast {
     Duration fadeDuration = const Duration(milliseconds: 350),
     bool ignorePointer = false,
     bool isDismissable = false,
+    ToastPositionMapping? customPositionMapping,
   }) {
     if (context == null)
       throw ("Error: Context is null, Please call init(context) before showing toast.");
@@ -258,6 +267,15 @@ class FToast {
     OverlayEntry newEntry = OverlayEntry(builder: (context) {
       if (positionedToastBuilder != null)
         return positionedToastBuilder(context, newChild);
+      // Use custom mapping logic to fall back to the default mapping if it is not defined or returns null
+      if (customPositionMapping != null) {
+        Widget? customPosition = customPositionMapping(newChild, gravity);
+        if (customPosition != null) {
+          return customPosition;
+        }
+      }
+
+      // Use the default mapping logic
       return _getPostionWidgetBasedOnGravity(newChild, gravity);
     });
     _overlayQueue.add(_ToastEntry(