modal_widget 1.0.2
modal_widget: ^1.0.2 copied to clipboard
A package that overlays an arbitrary widget over others, during the execution of long tasks, to improve interactity (e.g. showing a spinner).
Overlay Widget #
Showing interactivity is important for apps, even while executing blocking tasks like logging in, reading from the internet, etc. During these periods it is convenient to block access to the interface and show a notice (e.g. "Reading Data") or a fancy widget like Flutter Spinkit.
Although it is easy to show build and show the overlay depending on the state of a StatefulWidget, it is easier not to have to build it ;)
This package provides a mixin that eases the task of overlaying an arbitrary widget over another widget, to show activity during the execution of long tasks.
Features #
The basic features of this mixing, where used in a widget are:
- Show a widget for a limited time (e.g. 2 seconds)
- Show a widget during the execution of a function
- Show a widget and later hide it programmatically
The effect is the one in the images:
Getting started #
To start using this package, add it to your pubspec.yaml
file:
dependencies:
overlay_widget:
Then get the dependencies (e.g. flutter pub get
) and import them into your application:
import 'package:overlay_widget/overlay_widget.dart';
Usage #
You need to add the mixin to your StatefulWidget
, and then use the function buildWithOverlayWidget
in your build
override:
class _OverlayWidgetDemoState extends State<OverlayWidgetDemo> with OverlayWidget{
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: null,
body: buildWithOverlayWidget(child: Center(
child: ElevatedButton(
onPressed: () => showOverlayWidgetWhile(
() async => await Future.delayed(
const Duration(seconds: 3)
)
),
child: const Text("show overlay")
),
),
overlayWidget: const Center(child: Text("processing", style: TextStyle(fontSize: 50),))
),
);
}
}
Additional information #
There are different mechanisms and options to control how and when to show the overlay: showing the widget until it is programmatically hidden (i.e. showOverlayWidget
... hideOverlayWidget
), showing the widget while a function is being run, or showing the widget during a period.
The interface of the function to build the overlay is the next:
Widget buildWithOverlayWidget({
required Widget child,
Widget? overlayWidget,
bool blurContent = false,
double opacity = 0.8,
VoidCallback? onHide
})
The function somehow defines the default values for the process, but some of them may be overridden when showing the animation.
child
: the content to show under the overlay.overlayWidget
: the widget that is being overlayed to the content while waiting.blurContent
(defaults to false): If set totrue
, the child widget will be blurred (to give the feeling of being non-interactive).opacity
(defaults to 0.8): If set to a value different than 1, the child widget will be set to semi-transparent by this factor.onHide
: Callback to call whenever the animation is hidden (whether auto-closed or closed usinghideOverlayWidget
function)
Showing the overlay #
There are multiple functions to show the overlay:
Future<bool> showOverlayWidget({bool force = false, VoidCallback? onHide}) async {
This is the basic function that shows the overlayWidget
, and calls the function onHide
when the animation is hidden. If onHide
is not provided, it defaults to the value provided in the call to buildWithOverlayWidget
.
If the animation was already being shown, the state of the widget will not change, and onHide
will not be called. This happens unless the parameter force
is set to true
.
It is set as a Future<bool>
to enable chaining function execution (e.g. using then
). The result that receives the future refers to wether the animation has been shown or not (i.e. true
) or it was already being shown (i.e. false
).
void hideOverlayWidget([bool force = false]) {
This function hides the overlay and enables the usage of the child widget again. The function is intended to be called after showOverlayWidget
is called, but it is advisable to use the auto-close feature.
If the widget was already hidden, the state of the widget will not change, unless the parameter force
is set to true
.
Future<bool> showOverlayWidgetWhile(Function callback, {Duration? timeout, VoidCallback? onTimeout, VoidCallback? onHide})
This function shows the overlay widget during the execution of callback
. It is possible to set a timeout
for the execution. If the time for the execution exceeds that time, the execution of the callback
is aborted, and the function onTimeout
is called.
If onHide
is not provided, it defaults to the value provided in the call to buildWithOverlayWidget
.
The function returns a Future<bool>
that is resolved after the callback is executed (or aborted). So it is possible to chain it with other functions using await
or then
procedures. This procedure is independent from the onHide
callback, and so both onHide
may be called and the chain to then
may be executed.
The bool
result is set to true
if the widget has been shown and hidden. If the widget was already shown when calling showOverlayWidgetWhile
the result of the future will be set to false
.
Future<bool> showOverlayWidgetDuring(Duration period, {VoidCallback? onHide}) {
This function shows the widget during the period period
. If onHide
is not provided, it defaults to the value provided in the call to buildWithOverlayWidget
.
At the end, this is a shortcut for return showOverlayWidgetWhile(() async => await Future.delayed(period), onHide: onHide)
.