qibla_compass 1.0.1

A Flutter Qibla compass using GPS and compass sensor. Bilingual Arabic/English UI, smooth animations, and real-time alignment feedback.

qibla_compass 🕌

A beautifully designed, production-ready Flutter package for showing the Qibla (direction of the Kaaba in Mecca) using the device's GPS and compass sensor.

---

Features

Feature	Detail
🧭 Live compass	Streams real-time heading from flutter_compass
📍 GPS location	Uses geolocator with full permission handling
✨ Smooth animation	Animated needle with shortest-path interpolation (no 0/360 spin)
📳 Haptic feedback	Single pulse when the device aligns with the Qibla
🎨 Theming	Built-in defaultTheme and midnightTheme; fully customisable
🌍 Bilingual	Arabic + English labels throughout
📦 Embeddable	QiblaCompassWidget can be dropped into any screen
✅ Tested	Unit tests for all Qibla calculations

---

Getting Started

1. Add dependency

dependencies:
  qibla_compass:
    path: ../qibla_compass   # or your pub.dev version

2. Android permissions

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

3. iOS permissions

Add to ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to calculate Qibla direction</string>

---

Usage

Full-screen (recommended)

import 'package:qibla_compass/qibla_compass.dart';

Navigator.push(
  context,
  MaterialPageRoute(builder: (_) => const QiblaScreen()),
);

Custom theme

QiblaScreen(theme: QiblaTheme.midnightTheme)

Embedded compass widget

Use QiblaCompassWidget if you want to integrate the compass dial into your own screen:

StreamBuilder<CompassEvent>(
  stream: FlutterCompass.events,
  builder: (context, snapshot) {
    final heading = snapshot.data?.heading ?? 0;
    return QiblaCompassWidget(
      qiblaBearing: QiblaCalculator.calculateBearing(lat, lng),
      deviceHeading: heading,
      size: 240,
    );
  },
);

Pure calculation

// Bearing in degrees from true North (0–360)
final bearing = QiblaCalculator.calculateBearing(30.0444, 31.2357); // Cairo → ~135°

// Distance to Mecca in km
final km = QiblaCalculator.calculateDistanceKm(30.0444, 31.2357); // ~1290 km

// Are we aligned?
final aligned = QiblaCalculator.isAligned(bearing, deviceHeading); // default ±5°

---

Theming

// Use a built-in theme
const QiblaScreen(theme: QiblaTheme.midnightTheme)

// Or create your own
const myTheme = QiblaTheme(
  backgroundDark: Color(0xFF1A0A2E),
  backgroundMid:  Color(0xFF2E0F3E),
  gold:           Color(0xFFE8C96A),
  compassFaceStart: Color(0xFF3A1A6C),
  compassFaceEnd:   Color(0xFF1A0A2E),
);

QiblaScreen(theme: myTheme)

QiblaTheme properties

Property	Default	Description
backgroundDark	#0A2E24	Outermost background
backgroundMid	#0F3E33	Secondary background
gold	#CDA047	Primary accent (needle, bearing text, badges)
compassFaceStart	#1A5C4A	Compass centre gradient start
compassFaceEnd	#0A2E24	Compass centre gradient end
northIndicator	#FF4757	Colour of the "N" tick
accentCyan	#00D9FF	Info-strip icon colour

---

Running tests

flutter test

---

Accuracy notes

• Accuracy depends on the device's magnetometer hardware.
• Ask the user to perform a figure-8 calibration motion before use (the UI hints at this).
• alignmentThresholdDegrees (default 5°) can be tightened or loosened:

QiblaScreen(alignmentThresholdDegrees: 3.0)  // stricter

---

License

MIT © 2024