chaoperty_floating_loader #

Global transparent overlay loader for Flutter — works from anywhere via a global navigatorKey.
Supports once, ping‑pong, and loop‑wrap motions, with optional dim background and card.
ไทยอยู่ด้านล่าง ⬇️

✨ Features #

• Global overlay loader (no BuildContext needed)
• Motions: once, ping‑pong, loop‑wrap
• Start/end positions, ranges, edge bounce
• Optional dim backdrop and card
• Bundle‑friendly GIF (or your own assets)
• Horizontal, vertical, and diagonal patterns (via v* params)

📦 Installation #

dependencies:
  chaoperty_floating_loader: ^0.1.0

If you want to use the bundled GIF that ships with the package, you don’t need to add anything to your app’s assets.
For your own GIFs, declare them under your app’s flutter/assets and pass asset: 'images/your.gif' to show(...).

⚙️ Setup (required) #

Register the global navigatorKey:

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

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: ChaoAppLoader.navigatorKey, // ✅ required
      home: const MyHome(),
    );
  }
}

🚀 Quick Usage #

ElevatedButton(
  onPressed: () {
    ChaoAppLoader.show(
      asset: 'assets/images/my_duck.png', // หรือ .gif ก็ได้
      assetFromPackage: false, // สำคัญ! บอกว่าไม่ใช่ของแพ็กเกจ
      packAsset: ChaoPackAsset.duckFrontWalkGif,
      message: 'กำลังโหลด...',         // text under the GIF
      slideAcross: true,               // enable horizontal motion
      motion: Motion.pingPong,         // once | pingPong | loopWrap
      rangeMinAt: 0.2,                 // 0.0..1.0
      rangeMaxAt: 0.8,                 // 0.0..1.0
      slideMs: 2000,                   // bigger = slower
      verticalFactor: 0.7,             // 0.0(top) → 1.0(bottom)
      // asset: 'images/my_loader.gif', // use your own asset
    );
    Future.delayed(const Duration(seconds: 2), ChaoAppLoader.hide);
  },
  child: const Text('Show Loader'),
);

Hide anytime:

ChaoAppLoader.hide();

🧭 Motion Examples #

1) Once (custom start → end) #

ChaoAppLoader.show(
  message: 'Once: 0.20 → 0.85',
  slideAcross: true,
  motion: Motion.once,
  fromAt: 0.20,
  toAt: 0.85,
  bounceAtEdges: true, // small bounce on edge
  slideMs: 5200,
  verticalFactor: 0.70,
);

2) Ping‑Pong (within a range) #

ChaoAppLoader.show(
  message: 'Ping-Pong: 0.30 ↔ 0.80',
  slideAcross: true,
  motion: Motion.pingPong,
  rangeMinAt: 0.30,
  rangeMaxAt: 0.80,
  bounceAtEdges: true,
  slideMs: 1400,
  verticalFactor: 0.66,
);

3) Loop‑Wrap (Left → Right) #

ChaoAppLoader.show(
  message: 'Loop wrap (L→R)',
  slideAcross: true,
  motion: Motion.loopWrap,
  slideToRight: true,
  startAt: 0.15, // or Random().nextDouble()
  slideMs: 2400,
  verticalFactor: 0.72,
);

4) Vertical only (Top → Bottom) #

ChaoAppLoader.show(
  message: 'Vertical once: 0.10 → 0.85',
  vSlideAcross: true,
  vMotion: Motion.once,
  vFromAt: 0.10,
  vToAt: 0.85,
  slideMs: 2600,
);

5) Diagonal (loop X + ping‑pong Y) #

ChaoAppLoader.show(
  message: 'Diagonal: loop X + ping-pong Y',
  slideAcross: true,
  motion: Motion.loopWrap,
  slideToRight: true,
  startAt: 0.2,
  vSlideAcross: true,
  vMotion: Motion.pingPong,
  vRangeMinAt: 0.65,
  vRangeMaxAt: 0.80,
  slideMs: 2400, // controls both axes
);

⚙️ API #

Tips

• Make it slower/faster → change slideMs (bigger = slower).
• Start anywhere → use startAt: Random().nextDouble() or fromAt/toAt.
• Use packaged GIF → the default bundled GIF just works; pass asset: to override.

🧪 Local page-only overlay #

class LoadingOverlay extends StatelessWidget {
  final bool loading;
  final Widget child;

  const LoadingOverlay({super.key, required this.loading, required this.child});

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        child,
        if (loading)
          const Positioned.fill(
            child: DuckLoading(message: 'Loading...'),
          ),
      ],
    );
  }
}

🇹🇭 ภาษาไทย (Thai) #

chaoperty_floating_loader คือ ตัวโหลดแบบโอเวอร์เลย์โปร่งใส ที่เรียกได้จากทุกที่ (ไม่ต้องมี BuildContext) ผ่าน navigatorKey ระดับแอป
รองรับการเคลื่อนไหว ครั้งเดียว (once), ไป–กลับ (ping‑pong) และ วนรอบ (loop‑wrap)
ปรับ จุดเริ่ม/สิ้นสุด, ช่วงการวิ่ง, เด้งตอนชนขอบ, ใส่ ฉากหลังมืด และ การ์ด ได้

วิธีตั้งค่า (จำเป็น) #

ใส่ navigatorKey: ChaoAppLoader.navigatorKey ใน MaterialApp

ตัวอย่างใช้งานเร็ว #

ดูตัวอย่างด้านบนในส่วน Quick Usage ได้เลย

ทิป #

• ให้ช้าลง/เร็วขึ้น: แก้ slideMs
• เริ่มตรงไหนก็ได้: startAt หรือ fromAt/toAt
• ใช้ GIF จากแพ็กเกจ: ค่าเริ่มต้นทำงานได้เลย หรือส่ง asset: เป็นของคุณเอง

📄 License #

MIT © Chaoperty