screenveil 0.0.1

A premium, highly customizable Flutter package to protect sensitive content with blur, images, or custom widgets when the app is in the background or app switcher.

ScreenVeil

A premium, lightweight, and highly customizable Flutter package designed to protect sensitive content when users switch apps or put your application into the background (app switcher preview).

ScreenVeil lets you easily mask or cover your active application screen with a Gaussian Blur, a Custom Image, or a Completely Custom Widget (like passcode screens or brand splash locks).

---

Features

• Gaussian Blur Effect: Real-time adjustable blur (sigmaX & sigmaY) with customizable overlay colors.
• Image Backdrop: Cover your app switcher preview with beautiful assets or brand wallpapers.
• Custom Widgets: Render any custom Flutter widget (e.g., dynamic biometric scan prompt, PIN lock keypad).
• Zero Native Bloat: Written in pure Dart & Flutter, making it highly secure and compatible with all cross-platform channels.
• Auto Lifecycle Detection: Integrates with WidgetsBindingObserver to shield previews instantly.
• Manual Programmatic Lock: Use the forceShow parameter to trigger the veil screen during transaction processing or biometric checkpoints.
• Premium Micro-Animations: Smooth fade-in/fade-out animations with adjustable durations.

---

Architecture Flow

graph TD
    App[Flutter Application] -->|Wrapped by| SV[ScreenVeil Widget]
    SV -->|Monitors App Lifecycle| Lifecycle[AppLifecycleState]
    
    Lifecycle -->|inactive / paused| ShowVeil[Immediately Overlay Veil]
    Lifecycle -->|resumed| HideVeil[Smoothly Dismiss Veil]
    
    ShowVeil --> Blur[VeilType.blur]
    ShowVeil --> Image[VeilType.image]
    ShowVeil --> Custom[VeilType.custom]

---

Getting Started

1. Add dependency

Add screenveil to your pubspec.yaml file:

dependencies:
  screenveil:
    path: ./path/to/screenveil

2. Wrap your Application

Wrap the root widget of your application (or just the sensitive screen) with the ScreenVeil widget. Typically, wrapping your MaterialApp's nested Navigator or home page builder works best:

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

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: ScreenVeil(
        type: VeilType.blur,
        blurOptions: BlurVeilOptions(
          sigmaX: 15.0,
          sigmaY: 15.0,
          color: Colors.black.withOpacity(0.5),
          centerWidget: const Icon(Icons.lock, color: Colors.white, size: 50),
        ),
        child: const MyDashboard(),
      ),
    );
  }
}

---

Veil Types & Examples

1. Blur Style (VeilType.blur)

Fades in a soft glass-morphic Gaussian blur over your application content, keeping the general aesthetic while fully obfuscating text and numbers.

ScreenVeil(
  type: VeilType.blur,
  blurOptions: BlurVeilOptions(
    sigmaX: 12.0,
    sigmaY: 12.0,
    color: Color(0x990A0E17), // 0.6 opacity dark slate
    centerWidget: Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        Icon(Icons.shield_rounded, color: Colors.cyan, size: 48),
        SizedBox(height: 12),
        Text('Secure Session Active', style: TextStyle(color: Colors.white)),
      ],
    ),
  ),
  child: Dashboard(),
)

2. Image Cover Style (VeilType.image)

Replaces your background preview with a solid logo, branded graphic, or wallpaper.

ScreenVeil(
  type: VeilType.image,
  imageOptions: ImageVeilOptions(
    image: AssetImage('assets/images/secured_preview_wallpaper.png'),
    fit: BoxFit.cover,
    tintColor: Colors.black.withOpacity(0.4), // optional wash overlay
  ),
  child: Dashboard(),
)

3. Custom Widget Builder (VeilType.custom)

Provides the ultimate control. Render passcode inputs, biometric lock controls, or marketing banners when the screen goes background.

ScreenVeil(
  type: VeilType.custom,
  customOptions: CustomVeilOptions(
    child: Scaffold(
      backgroundColor: Colors.black,
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            CircularProgressIndicator(),
            SizedBox(height: 16),
            Text('Encrypting memory data...'),
          ],
        ),
      ),
    ),
  ),
  child: Dashboard(),
)

---

API Parameters

Parameter	Type	Default Value	Description
child	Widget	Required	The underlying widget subtree to protect.
isEnabled	bool	true	Quickly toggle the automatic lifecycle protection on or off.
forceShow	bool	false	When true, programmatically forces the protection veil to display immediately (e.g. for custom app lock mechanisms).
type	VeilType	VeilType.blur	Choose between blur, image, or custom.
blurOptions	BlurVeilOptions	const BlurVeilOptions()	Configuration options for blur veils.
imageOptions	ImageVeilOptions?	null	Configuration options for image cover veils (required if type is image).
customOptions	CustomVeilOptions?	null	Configuration options for custom widget veils (required if type is custom).
transitionDuration	Duration	Duration(milliseconds: 200)	The duration of the fade overlay animations.
useFadeAnimation	bool	true	If set to false, the veil overlays instantly (perfect for maximum preview security).
triggerStates	List<AppLifecycleState>	[AppLifecycleState.inactive, AppLifecycleState.paused]	Customise exactly which application state changes trigger screen obscuring.
onVeilShow	VoidCallback?	null	Event callback fired when the veil overlay starts showing.
onVeilHide	VoidCallback?	null	Event callback fired when the veil overlay is completely hidden.

---

Best Practices for Complete Security

While rendering a Flutter-level overlay works beautifully for protecting your app's screenshot preview in the native app switcher, it depends on the operating system capturing the frame after the inactive event is fully handled.

For absolute system-level protection (e.g., completely blocking screenshots and making the preview black or blank natively):

• Android: Combine ScreenVeil with the native FLAG_SECURE configuration:

  import 'package:flutter_windowmanager/flutter_windowmanager.dart';
  // ...
  await FlutterWindowManager.addFlags(FlutterWindowManager.FLAG_SECURE);
  

• iOS: Combine with native window cover adjustments or secure text field tricks if you want to block video recording and manual user screenshots altogether.