Summary
This module serves as the backbone of the application, providing essential infrastructure for system interactions and data processing. It handles complex tasks like requesting sensitive Android permissions (Accessibility, Usage Stats), calculating physical scroll distances based on screen density, managing tactile feedback (haptics), and standardizing time formatting. It ensures the app behaves consistently across different devices and provides a polished user experience.How It Works
The General Utilities module acts as a translation layer between the raw Android system and the app’s user interface.Physical Feedback (Haptics)
When a user interacts with the app (e.g., tapping a button, scrolling a wheel, or reaching a limit), the UI component calls the
HapticsManager. This manager checks if vibrations are enabled in both system and app settings. If allowed, it plays a specific vibration pattern (like a crisp “click” or a heavy “thud”) using the Android Vibrator API, ensuring the user “feels” the interaction.Real-World Measurement (Physics)
As the user scrolls through their social media feeds, the app tracks the raw number of pixels moved.
ScrollPhysics takes these pixels and uses the device’s screen density (DPI) to calculate the actual physical distance scrolled in meters or kilometers. This allows the app to report “You scrolled 50 meters” rather than “You scrolled 20,000 pixels.”System Access (Permissions)
To track usage and block apps, the app needs special permissions like Accessibility and Usage Stats. The
PermissionManager checks the current status of these permissions. If a permission is missing, it guides the user directly to the specific Android Settings page where they can grant it, simplifying the complex setup process.Key Components
HapticsManager
Centralizes all vibration effects, defining specific patterns for success, errors, ticks, and warnings to create a tactile language for the app.
PermissionManager
Manages the checking and requesting of sensitive system permissions (Accessibility, Usage Stats, Overlays) required for core functionality.
ScrollPhysics
Converts raw screen pixels into physical units (meters/kilometers) based on the specific hardware display metrics of the user’s phone.
DateUtil
Handles all date and time logic, ensuring correct timezone handling and consistent text formatting (e.g., “1h 30m”) across screens.
Constants & Configuration
TheAppConstants file defines critical thresholds that determine how the app interprets user behavior:
| Constant | Value | Description |
|---|---|---|
MINIMUM_SIGNIFICANT_SESSION_DURATION_MS | 1 second | Sessions shorter than this are ignored (filters accidental opens). |
COMPULSIVE_UNLOCK_THRESHOLD_MS | 20 seconds | Unlocking, checking one app, and locking within this time is flagged as “Compulsive”. |
SESSION_MERGE_GAP_MS | 30 seconds | Two scroll events within this window are merged into a single continuous session. |
NOTIFICATION_UNLOCK_WINDOW_MS | 30 seconds | An unlock immediately following a notification is attributed to that notification. |
Utility Features
Intent Extras
IntentExtras provides a centralized registry of all keys used for passing data between screens (e.g., package_name, group_id). This prevents bugs caused by typos in string keys and makes navigation logic type-safe.
UI Text Wrapper
UiText is a helper class that allows ViewModels to emit text that is either a raw String or a String Resource ID. This decouples the business logic from the Android Context, making the code testable while still supporting localization.
Changelog System
The module includes aChangelogScreen that renders a timeline of app updates. It parses a structured list of features and versions, displaying them in an interactive timeline with expandable details, helping users stay informed about new features like “Smart Limits” or “Focus Tools”.