imad_flutter library
MushafImad Flutter Library
A Quran reader library for Flutter providing Mushaf page display with audio recitation support, bookmarks, search, and more.
Getting Started
Initialize the library before use:
await MushafLibrary.initialize(
databaseService: myDatabaseService,
bookmarkDao: myBookmarkDao,
readingHistoryDao: myReadingHistoryDao,
searchHistoryDao: mySearchHistoryDao,
);
Then access repositories:
final chapters = await MushafLibrary.getChapterRepository().getAllChapters();
Classes
- AlKetabApiService
- AlKetabResult
- AlKetabSearchResponse
- AudioPlaybackSource
- Common interface for any class that performs audio-data fetching and verse-timing queries for a specific backend source.
- AudioPlayerState
- Audio player state containing playback information.
- AudioRecitationProvider
- Base interface for fetching recitations from a specific backend source.
- AudioRepository
- Repository for Quran audio playback and recitation management. Public API - exposed to library consumers.
- AyahTiming
- Bookmark
- User bookmark for a specific verse or page. Public API - exposed to library consumers.
- BookmarkDao
- Data Access Object interface for bookmarks. Abstraction layer to keep DB implementation swappable.
- BookmarkData
- BookmarkListWidget
- A reusable bookmark list widget.
- BookmarkRepository
- Repository for managing user bookmarks. Public API - exposed to library consumers.
- BookmarksViewModel
- ViewModel for bookmarks management.
- BottomSheetOption
- A generic option item for use inside MushafModalBottomSheet body.
- CacheStats
- Statistics about the current cache state. Public API - exposed to library consumers.
- Chapter
- Domain model for Quran Chapter (Surah). Public API - exposed to library consumers.
- ChapterData
- Quran metadata — static data for all 114 chapters and 604 page mappings.
- ChapterIndexDrawer
- Drawer showing all 114 surahs for quick navigation.
- ChapterInfo
- Summary of a chapter suitable for displaying in headers and lists. Public API - exposed to library consumers.
- ChapterRepository
- Repository for Chapter-related operations. Public API - exposed to library consumers.
- ChaptersByHizb
- Chapters grouped by Hizb. Public API - exposed to library consumers.
- ChaptersByPart
- Chapters grouped by Juz (Part). Public API - exposed to library consumers.
- ChaptersByQuarter
- Chapters grouped by Quarter (Rub al-Hizb). Public API - exposed to library consumers.
- ChaptersByType
- Chapters grouped by type (Meccan/Medinan). Public API - exposed to library consumers.
- ChapterTiming
- CompositeAudioRepository
- An AudioRepository that aggregates one or more audio source backends simultaneously.
- DatabaseService
- Facade around the database that powers Quran metadata. Internal API - not exposed to library consumers.
- DataExportRepository
- Repository for exporting and importing user data. Public API - exposed to library consumers.
- DefaultMushafLogger
- Default logger implementation using Dart's print.
- Error
- Error state with exception and optional message.
- FlutterAudioPlayer
- App-specific AudioHandler that connects just_audio to audio_service
- HiveBookmarkDao
- Hive-backed implementation of BookmarkDao.
- HiveDatabaseService
- Hive/in-memory implementation of DatabaseService using static Quran metadata.
- HiveReadingHistoryDao
- Hive-backed implementation of ReadingHistoryDao.
- HiveSearchHistoryDao
- Hive-backed implementation of SearchHistoryDao.
- ImportResult
- Result of data import operation. Public API - exposed to library consumers.
- ItqanAudioConfig
- Configuration for the CMS audio metadata fetching.
- ItqanPlaybackSource
- AudioPlaybackSource implementation for the Itqan CMS API.
- ItqanRecitationProvider
-
AudioRecitationProvider implementation that fetches recitations from the
Itqan CMS
/recitations/endpoint. - LastReadPosition
- Last read position for resuming reading. Public API - exposed to library consumers.
- LastReadPositionData
- Loading
- Loading state.
- Mp3QuranPlaybackSource
- AudioPlaybackSource implementation for the mp3quran.net static files.
- Mp3QuranRecitationProvider
- Provider for mp3quran.net static assets.
- MushafAnalytics
- Interface for library analytics.
- MushafColors
- Color presets for reading themes.
- MushafLibrary
- Main entry point for MushafImad Flutter library.
- MushafLogger
- Interface for library logging.
- MushafModalBottomSheet
- generic component for all use cases of bottom sheet in the mushaf.
- MushafPageView
- MushafPageView — the main Mushaf reader screen.
- MushafPageViewState
- MushafThemeNotifier
- A ChangeNotifier that holds the current ReadingTheme for the Mushaf.
- MushafThemeScope
- An InheritedNotifier that provides a MushafThemeNotifier to the widget tree, so all Mushaf widgets can share and react to theme changes.
- MushafViewModel
- ViewModel for the main Mushaf reading view.
- NoOpMushafAnalytics
- No-op analytics implementation.
- Page
- Domain model for Quran Page. Public API - exposed to library consumers.
- PageData
- Page metadata.
- PageHeaderInfo
- Lightweight structure describing the contextual header for a Mushaf page. Public API - exposed to library consumers.
- PageRepository
- Repository for Page-related operations. Public API - exposed to library consumers.
- PageVerseData
- Per-verse data for rendering on a Mushaf page.
- Part
- Domain model for Quran Part (Juz). Represents one of the 30 parts of the Quran. Public API - exposed to library consumers.
- PreferencesData
- PreferencesRepository
- Repository for all user preferences and settings. Public API - exposed to library consumers.
- Quarter
- Domain model for Quran Quarter (Hizb fraction). Represents one-quarter of a Hizb. Public API - exposed to library consumers.
- QuranComAudioSourceConfig
- Caller-facing configuration for the Quran.com (Quran.Foundation) audio source.
- QuranComPlaybackSource
- AudioPlaybackSource implementation for the Quran.com (Quran.Foundation) streaming API.
- QuranComRecitationProvider
- Provides high-level recitation management for the Quran.com audio source.
- QuranDataProvider
- Provides Quran page data — chapters, juz, and page metadata.
- QuranLineImage
- Displays a single Quran line image loaded from assets.
- QuranPageWidget
- Renders a single Quran page — 15 line images with a page header.
- QuranPlayerViewModel
- ViewModel for the Quran audio player.
- QuranRepository
- Repository for general Quran data operations. Public API - exposed to library consumers.
- ReadingHistory
- Reading history entry for analytics. Public API - exposed to library consumers.
- ReadingHistoryDao
- Data Access Object interface for reading history. Abstraction layer to keep DB implementation swappable.
- ReadingHistoryRepository
- Repository for managing reading history and progress. Public API - exposed to library consumers.
- ReadingHistoryViewModel
- ViewModel for reading history.
- ReadingStats
- Reading statistics aggregated from history. Public API - exposed to library consumers.
- ReadingThemeData
- Color scheme data for a reading theme.
- Recitation
- A recitation -- the selectable unit in the audio picker.
- RecitationDataProvider
- Provider for all available Quran recitations from mp3quran.net. Data matches iOS/Android implementation for compatibility. Internal implementation - not exposed in public API.
- Reciter
- A Quran reciter (person).
- ReciterTiming
- Timing data for a reciter. Used for audio-verse synchronization. Public API - exposed to library consumers.
-
Result<
T> - A generic wrapper for handling success and error states. Public API - exposed to library consumers.
- Riwayah
- A riwayah (transmission chain, e.g. "Hafs an Asim").
- SearchHistoryDao
- Data Access Object interface for search history. Abstraction layer to keep DB implementation swappable.
- SearchHistoryData
- SearchHistoryEntry
- Search history entry. Public API - exposed to library consumers.
- SearchHistoryRepository
- Repository for managing search history and suggestions. Public API - exposed to library consumers.
- SearchPage
- Full search page with unified verse/chapter/bookmark search.
- SearchSuggestion
- Search suggestion based on history. Public API - exposed to library consumers.
- SearchViewModel
- SettingsPage
- Unified settings page combining theme, preferences, and data management.
- SettingsViewModel
- ViewModel for the unified settings page.
-
Success<
T> - Success state with data.
- ThemeConfig
- Theme configuration. Public API - exposed to library consumers.
- ThemePickerWidget
- A visual theme picker widget for selecting Mushaf reading themes.
- ThemeViewModel
- ViewModel for theme management.
- UserDataBackup
- Complete backup of user data. Public API - exposed to library consumers.
- Verse
- Domain model for Quran Verse (Ayah). Public API - exposed to library consumers.
- VerseDataProvider
- Loads and caches verse data from the bundled JSON asset.
- VerseFasel
- VerseFasel — renders a verse number marker (circle with Arabic numeral).
- VerseHighlight
- Domain model for Verse highlight rectangle. Contains normalized coordinates (0-1) for selection highlighting.
- VerseHighlightData
- Lightweight model for verse highlight region (single line).
- VerseMarker
- Domain model for Verse number marker position. Contains normalized coordinates (0-1) for verse number placement.
- VerseMarkerData
- Lightweight model for verse marker position on a page line.
- VerseRepository
- Repository for Verse-related operations. Public API - exposed to library consumers.
Enums
- HizbQuarterProgress
- Enum representing Hizb quarter progress.
- LogCategory
- LogLevel
- MushafAudioSource
- Identifies an audio source backend the library can use for recitation playback.
- MushafColorScheme
- Color scheme options. Public API - exposed to library consumers.
- MushafThemeMode
- Theme mode for the application. Public API - exposed to library consumers.
- MushafType
- Supported Mushaf layouts that alter how verses map to pages. Public API - exposed to library consumers.
- PlaybackState
- Playback states for audio player.
- QuranComEnvironment
- Which Quran.com environment the client should talk to.
- ReadingTheme
- Reading theme for Mushaf pages. Controls background color, text color, and other visual settings.
- SearchType
- Search query types. Public API - exposed to library consumers.
Extensions
Constants
-
allChapters
→ const List<
ChapterData> - All 114 chapters with their metadata.
-
juzStartPages
→ const List<
int> - Juz (Part) start pages — standard Hafs Mushaf.
Properties
- mushafGetIt → GetIt
-
Service locator instance for the library.
final
Functions
-
setupMushafDependencies(
{required DatabaseService databaseService, required BookmarkDao bookmarkDao, required ReadingHistoryDao readingHistoryDao, required SearchHistoryDao searchHistoryDao, required MushafLogger logger, Set< MushafAudioSource> audioSources = const {MushafAudioSource.mp3quran}, QuranComAudioSourceConfig? quranComConfig, ItqanAudioConfig? itqanAudioConfig, FlutterAudioPlayer? audioPlayer}) → Future<void> - Register all core dependencies for the Mushaf library.