Flutter Widget & Utility Library #

A comprehensive Flutter library offering customizable widgets and utility classes to simplify and enhance app development. This library includes rich UI components leveraging packages like syncfusion_flutter, cached_network_image, and flutter_map, alongside utilities for HTTP requests, file handling, navigation, and more. Designed for flexibility, it supports extensive customization for styling, behavior, and platform-specific features.

Table of Contents #

• Overview
• Dependencies
• Widgets
  • UI Components
  • Interactive Widgets
  • Media Widgets
  • Data Display Widgets
• Utilities
  • App Management
  • System Utilities
  • Network Utilities
• Installation
• Contributing
• License
• Contact

Overview #

This library provides a collection of reusable Flutter widgets and utilities designed to streamline development and enhance user experiences. Widgets include advanced UI components like calendars, charts, and maps, while utilities offer tools for tasks such as HTTP requests, file operations, and navigation. Each component is highly customizable, supporting both Material and Cupertino designs, with platform-specific optimizations.

Dependencies #

The library relies on the following packages (ensure these are included in your pubspec.yaml):

Add these dependencies to your pubspec.yaml and run flutter pub get.

Widgets #

UI Components #

UBarcode

Description: Generates barcodes and QR codes using syncfusion_flutter_barcodes. Supports various barcode types with customizable appearance.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UBarcode(
  value: 'https://example.com',
  type: UBarcodeType.qrCode,
  barColor: Colors.black,
  showValue: true,
  errorCorrectionLevel: UErrorCorrectionLevel.high,
)

UCachedImage

Description: Loads and displays images from URLs with caching using cached_network_image for optimized performance.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UCachedImage(
  imageUrl: 'https://example.com/image.jpg',
  placeholder: CircularProgressIndicator(),
  errorWidget: Icon(Icons.broken_image),
  width: 200,
  height: 200,
  fit: BoxFit.cover,
)

UContainer

Description: A customizable container widget (UContainer) with advanced styling and layout options, including padding, margin, and decoration.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UContainer(
  padding: EdgeInsets.all(16),
  margin: EdgeInsets.all(8),
  decoration: BoxDecoration(
    color: Colors.blue[50],
    borderRadius: BorderRadius.circular(12),
  ),
  child: Text('Content'),
)

Interactive Widgets #

UChipChoice

Description: A customizable chip selection widget for single or multiple choice options, supporting scrollable or wrapped layouts.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UChipChoice<String>(
  options: ['Apple', 'Banana', 'Orange'],
  selected: 'Apple',
  onChanged: (index, isSelected, item) => print('Selected: $item'),
)

UForm

Description: A collection of form widgets (UTextField, UTextFieldPersianDatePicker, UElevatedButton, UOutlinedButton, UTextButton, USearchableDropdown, UTextFieldPhoneNumber) for customizable inputs and buttons.

Parameters (UTextField):

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

USpacedColumn(
  spacing: 16,
  children: [
    UTextField(
      labelText: 'Name',
      hintText: 'Enter your name',
      onChanged: (value) => print('Name: $value'),
      validator: (value) => value!.isEmpty ? 'Required' : null,
    ),
    UElevatedButton(
      title: 'Submit',
      onTap: () => print('Submitted'),
      backgroundColor: Colors.blue,
    ),
  ],
)

UOtpField

Description: A widget for entering OTP codes with individual text fields for each digit, supporting auto-focus and validation.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UOtpField(
  controller: TextEditingController(),
  length: 4,
  cursorColor: Colors.blue,
  fillColor: Colors.grey[200]!,
  activeColor: Colors.blue,
  borderColor: Colors.grey,
  borderRadius: 12,
  fieldWidth: 50,
  fieldHeight: 50,
  autoFocus: true,
  onCompleted: (value) => print('OTP: $value'),
)

Media Widgets #

UImage

Description: Displays images from various sources (network, file, memory, assets) with support for SVG, Lottie, and caching.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UImage(
  source: 'https://example.com/image.jpg',
  width: 100,
  height: 100,
  fit: BoxFit.cover,
  placeholder: 'assets/placeholder.png',
  borderRadius: 8,
)

UImageSlider

Description: A carousel widget for displaying images with automatic scrolling and customizable indicators.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UImageSlider(
  images: [
    'https://example.com/image1.jpg',
    'https://example.com/image2.jpg',
  ],
  height: 200,
  imageFit: BoxFit.cover,
  radius: 8,
  autoPlayDuration: 5,
  activeIndicatorColor: Colors.blue,
)

UVideoPlayer

Description: Plays videos from network, file, or asset sources with customizable playback controls.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UVideoPlayer(
  source: 'https://example.com/video.mp4',
  autoplay: true,
  showControls: true,
)

UPdfViewer

Description: Displays PDF files with support for zooming, scrolling, and page navigation.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UPdfViewer(
  source: 'https://example.com/sample.pdf',
  initialPage: 1,
  zoomLevel: 1.0,
  onPageChanged: (page) => print('Page: $page'),
)

UWebView

Description: Displays web content with support for navigation and JavaScript execution.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UWebView(
  url: 'https://example.com',
  javascriptMode: JavascriptMode.unrestricted,
  onPageFinished: (url) => print('Page loaded: $url'),
)

Data Display Widgets #

UCalendar

Description: Displays a customizable calendar with event support and optional Jalali calendar integration using syncfusion_flutter_calendar.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UCalendar(
  dataSource: UCalendarDataSource(
    appointments: [
      Appointment(
        startTime: DateTime.now(),
        endTime: DateTime.now().add(Duration(hours: 1)),
        subject: 'Meeting',
        color: Colors.blue,
      ),
    ],
  ),
  view: CalendarView.month,
  showNavigationArrow: true,
  onTap: (details) => print('Tapped: ${details.date}'),
)

UChart

Description: A collection of chart widgets (e.g., UColumnChart, UDoughnutChart) for data visualization using syncfusion_flutter_charts.

Parameters (Common):

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UColumnChart(
  data: [
    ChartData(xValue: 'Jan', yValue: 10, color: Colors.blue),
    ChartData(xValue: 'Feb', yValue: 15, color: Colors.red),
  ],
  legendPosition: ChartLegendPosition.top,
  showLegend: true,
  enableTooltip: true,
)

UGauge

Description: Displays a radial gauge using syncfusion_flutter_gauges with customizable ranges and annotations.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UGauge(
  value: 75,
  min: 0,
  max: 100,
  size: 200,
  ranges: [
    UGaugeRange(start: 0, end: 50, color: Colors.red),
    UGaugeRange(start: 50, end: 100, color: Colors.green),
  ],
  annotations: [
    UGaugeAnnotation(widget: Text('75%'), angle: 90, position: 0.5),
  ],
)

UMap

Description: An interactive map widget using flutter_map with support for multiple tile providers and markers.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';
import 'package:flutter_map/flutter_map.dart';

UMap(
  controller: MapController(),
  center: LatLng(51.509364, -0.128928),
  zoom: 12,
  tileProvider: UMapTileProvider.openStreetMap,
  markers: [
    Marker(
      point: LatLng(51.509364, -0.128928),
      width: 40,
      height: 40,
      child: Icon(Icons.location_pin, color: Colors.red, size: 40),
    ),
  ],
)

UNumberPagination

Description: A pagination control with numbered buttons, previous/next navigation, and ellipsis for large page counts.

Parameters:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UNumberPagination(
  currentPage: 5,
  totalPages: 10,
  onPageChanged: (page) => print('Page: $page'),
  threshold: 2,
  selectedColor: Colors.blue,
)

Utilities #

App Management #

UApp

Description: Provides access to app-wide configuration, device information, platform checks, and theme-related properties.

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

// Access app metadata
String appName = UApp.name;

// Check platform
bool isWeb = UApp.isWeb;

// Update locale
UApp.updateLocale(Locale('fa'));

// Toggle theme
UApp.switchTheme();

System Utilities #

UClipboard

Description: Manages system clipboard operations for copying and pasting text.

Methods:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

await UClipboard.set('Hello, Flutter!');
String? text = await UClipboard.getText();

UFile

Description: Handles file operations like picking images/files and cropping images using image_picker, file_picker, and image_cropper.

Methods:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

List<FileData> images = await UFile.showImagePicker(
  source: ImageSource.gallery,
  allowMultiple: true,
);

ULocalAuth

Description: Manages biometric and local authentication using local_auth.

Methods:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

bool canAuth = await ULocalAuth.canAuthenticate();
bool authenticated = await ULocalAuth.authenticate(
  localizedReason: 'Please authenticate',
);

ULocalStorage

Description: Manages persistent key-value storage using shared_preferences.

Methods:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

await ULocalStorage.init();
ULocalStorage.set('key', 'value');
String? value = ULocalStorage.getString('key');

ULocation

Description: Retrieves user location using geolocator.

Methods:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

Position? position = await ULocation.getUserLocation(
  onUserLocationFound: (pos) => print('Location: ${pos.latitude}'),
);

UNavigator

Description: Manages navigation, dialogs, and notifications with custom transitions.

Methods:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

await UNavigator.push(Text('New Page'), transition: RouteTransitions.fade);
UNavigator.snackbar(message: 'Action completed');

UUUID

Description: Generates UUIDs using the uuid package.

Methods:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

String uuid = UUUID.uuidV4();

UValidators

Description: Provides form validation methods for various input types.

Methods:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

FormFieldValidator<String> validator = UValidators.combineValidators([
  UValidators.required(message: 'Required'),
  UValidators.email(requiredMessage: 'Email required', invalidMessage: 'Invalid email'),
]);

Network Utilities #

UHttpClient

Description: Manages HTTP requests, file uploads, and downloads with customizable headers and timeouts.

Methods:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

UHttpClient client = UHttpClient(baseUrl: 'https://api.example.com');
await client.get(
  '/users',
  onSuccess: (response) => print(response.body),
);
client.close();

UNetwork

Description: Checks network connectivity using connectivity_plus and internet_connection_checker.

Methods:

Usage:

import 'package:flutter_widget_utility/flutter_widget_utility.dart';

bool hasWifi = await UNetwork.hasWifi();

Installation #

Add the library to your pubspec.yaml:

dependencies:
  flutter_widget_utility: ^1.0.0

Run flutter pub get to install the package. Import and use the widgets and utilities as shown in the examples above.

Contributing #

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/new-feature).
3. Commit your changes (git commit -am 'Add new feature').
4. Push to the branch (git push origin feature/new-feature).
5. Create a pull request.

Please ensure your code follows the project's coding standards and includes tests.

License #

This library is licensed under the MIT License. See the LICENSE file for details.

Contact #

For more information, visit SinaMN75.com or check out the GitHub repository.