hq_picker 0.0.4

A stateful widget that allows users to pick media files (images, videos, audio, files) from their device.

HQPicker

A high-performance, fully customizable, multi-mode media picker for Flutter — powered by the BLoC pattern. HQPicker delivers 60fps scrolling, zero setState sluggishness, and elegant memory management even with thousands of media files.

---

✨ Features

• BLoC Architecture — Zero setState inside the picker core. Optimized for fast rebuilds and scalability.
• Two Beautiful Picker Styles — Instagram full-screen preview + Telegram draggable bottom sheet.
• Unified HQPicker API — One entry-point for all shapes: instagram, telegram, document, directory.
• Conditional Camera Buttons — In the Instagram picker the camera / video-camera buttons are shown only when the requestType supports them.
• Pagination Built-in — Lazy-loads media in chunks of 60 to prevent memory leaks and freezing.
• Full Text-Style Theming — Every Text widget in the picker (badge, album name, video duration, dialog, snack-bar…) is individually styleable via HQPickerTheme.
• Cropping & Compression — Built-in image editing with adjustable quality, shown behind a configurable loading overlay.
• Localization — All visible strings (including permissionRequired, permissionDenied, openSettings, etc.) are configurable via HQPickerLocalizations.
• Custom SnackBar / Toast — Provide onSnackBar to replace the built-in SnackBar with any toast/overlay you prefer.
• File System Support — Native document and directory pickers via file_selector.

---

🚀 Getting Started

flutter pub add hq_picker

Or add it manually to your pubspec.yaml:

dependencies:
  hq_picker: ^0.0.4

Import in your Dart code:

import 'package:hq_picker/hq_picker.dart';

---

📱 Usage

1. Unified HQPicker.pick(...) — recommended

// Instagram style (full-screen)
final results = await HQPicker.pick(
  context: context,
  shape: HQPickerShape.instagram,
  maxCount: 5,
  requestType: HQPickerRequestType.image,
);

// Telegram style (sliding sheet)
final results = await HQPicker.pick(
  context: context,
  shape: HQPickerShape.telegram,
  maxCount: 5,
);

// Native document picker
final docs = await HQPicker.pick(
  context: context,
  shape: HQPickerShape.document,
  allowedExtensions: ['pdf', 'docx'],
);

// Native directory picker
final dir = await HQPicker.pickDirectory();

2. Convenience shortcuts

// Images only — Instagram style
final images = await HQPicker.pickImage(
  context: context,
  shape: HQPickerShape.instagram,
  maxCount: 5,
);

// Videos only — Telegram style
final videos = await HQPicker.pickVideo(
  context: context,
  shape: HQPickerShape.telegram,
  maxCount: 3,
);

// Documents
final docs = await HQPicker.pickDocument(
  allowedExtensions: ['pdf'],
);

3. Inline Telegram sheet

final GlobalKey<HQPickerTelegramMediaPickersState> _key = GlobalKey();

// In your widget tree:
HQPickerTelegramMediaPickers(
  key: _key,
  requestType: HQPickerRequestType.all,
  maxCountPickMedia: 5,
  maxCountPickFiles: 5,
  config: const HQPickerConfig(),
  onMediaPicked: (assets, files) {
    debugPrint('Picked ${assets?.length} assets, ${files?.length} files');
  },
);

// Open / close:
ElevatedButton(
  onPressed: () => _key.currentState?.toggleSheet(context),
  child: const Text('Open Telegram Sheet'),
);

---

🎨 Theming — Full Text-Style Control

Every visible text in the picker can be styled independently via HQPickerTheme:

config: HQPickerConfig(
  theme: HQPickerTheme(
    // Colors
    backgroundColor: Color(0xFF1E1E2E),
    appbarColor: Color(0xFF1E1E2E),
    confirmButtonColor: Colors.deepPurple,
    badgeBackgroundColor: Colors.deepPurple,

    // Text styles
    albumNameTextStyle: TextStyle(
      fontFamily: 'Cairo',
      fontSize: 20,
      fontWeight: FontWeight.bold,
      color: Colors.white,
    ),
    confirmButtonTextStyle: TextStyle(
      color: Colors.white,
      fontWeight: FontWeight.w600,
    ),
    badgeTextStyle: TextStyle(color: Colors.white),
    videoDurationTextStyle: TextStyle(fontSize: 9, color: Colors.yellow),
    emptyListTextStyle: TextStyle(color: Colors.white54, fontSize: 16),
    dialogTitleTextStyle: TextStyle(color: Colors.white),
    dialogContentTextStyle: TextStyle(color: Colors.white70),
    snackBarTextStyle: TextStyle(color: Colors.white),
  ),
),

---

🌐 Localization

All strings default to English. Override any or use the built-in Arabic preset:

// Arabic preset
config: HQPickerConfig(
  localizations: HQPickerLocalizations.ar(),
),

// Or override individual strings
config: HQPickerConfig(
  localizations: HQPickerLocalizations(
    confirm: 'Done',
    gallery: 'My Gallery',
    permissionRequired: 'Access Required',
    permissionDenied: 'Please allow media access in Settings.',
    openSettings: 'Open Settings',
    emptyList: 'No media found',
  ),
),

---

🔔 Custom SnackBar / Toast

Replace the default built-in SnackBar with your own notification:

config: HQPickerConfig(
  showSnackBar: false, // disable built-in snackbar
  onSnackBar: (context, message) {
    // Use any toast library or widget
    Fluttertoast.showToast(msg: message);
  },
),

---

⚙️ Advanced Config

config: HQPickerConfig(
  // Image processing
  enableCropping: true,
  compressImage: true,
  compressQuality: 80,

  // Custom loading overlay during processing
  loadingWidget: Center(
    child: CircularProgressIndicator(color: Colors.deepPurple),
  ),

  // Custom icons
  icons: HQPickerIcons(
    camera: Icon(Icons.camera_alt_outlined),
    cameraVideo: Icon(Icons.video_call_outlined), // video camera in Instagram toolbar
    dropdown: Icon(Icons.expand_more),
  ),
),

---

📦 Return Type

All pickers return List<HQPickerResult>:

final results = await HQPicker.pick(...);

for (final result in results) {
  final File? file = result.file;     // File representation
  final AssetEntity? asset = result.asset; // Original gallery asset
}

---

📋 HQPickerConfig Reference

Property	Type	Default	Description
theme	HQPickerTheme	default dark	All colors & text styles
localizations	HQPickerLocalizations	English	All UI strings
icons	HQPickerIcons	Material icons	All picker icons
enableCropping	bool	false	Enable image crop after pick
compressImage	bool	true	Compress images before returning
compressQuality	int	80	JPEG compression quality (0–100)
showSnackBar	bool	true	Show built-in SnackBar on empty selection
onSnackBar	Function?	null	Custom SnackBar / toast callback
loadingWidget	Widget?	CircularProgressIndicator	Overlay shown during processing