Home / Specs / Settings System
Settings v1.0.0

Settings System

User preferences and keyboard configuration

Settings System Specification

Feature Overview

Feature Name: Settings & Preferences System

Priority: P1 (High)

Status: Maintenance & Enhancement

Target Version: v1.0.0

Summary

The settings system manages user preferences, storage permissions, configuration persistence, and settings UI. It provides a modern Material 3 interface for configuring keyboard behavior.

Motivation

Users need a comprehensive, intuitive settings system to customize keyboard behavior. The system must handle Android 11+ storage changes, persist preferences reliably, and expose all configurable options.

📋 Feature Parity Status (2025-11-16)

For complete analysis of missing settings compared to original Unexpected-Keyboard, see:

SETTINGS_COMPARISON_MISSING_ITEMS.md

Current Status Summary:

Priority Breakdown:

CleverKeys Exclusive Features (Not in Original):

⚠️ KNOWN ISSUES (From Historical Review)

CRITICAL Issues (Fixed)

#### ✅ Issue #5: Termux Mode Setting Missing from UI

File: res/xml/settings.xml

Status: ⚠️ NEEDS VERIFICATION

Original Problem: termux_mode_enabled checkbox not present in neural settings screen

Impact: Users cannot enable Termux-compatible prediction insertion

Current State: Variable exists in Config.kt but may not be exposed in settings XML

Action Required:

HIGH PRIORITY Issues (Fixed)

#### ✅ Issue #9: External Storage Permissions (Android 11+) - VERIFIED FIXED

File: AndroidManifest.xml:11-15

Status: ✅ VERIFIED (2025-10-21)

Original Problem: READ/WRITE_EXTERNAL_STORAGE deprecated on Android 11+ (API 30+)

Impact: Would cause file access failures on modern Android versions

Verification Result: PROPERLY CONFIGURED ✅

Action Required (Testing):

MEDIUM PRIORITY Issues (Fixed)

#### ✅ Issue #15: Theme Propagation Incomplete

File: src/main/kotlin/tribixbite/keyboard2/CleverKeysService.kt:654

Status: ⚠️ NEEDS VERIFICATION

Original Problem: // TODO: Propagate theme changes to active UI components

Impact: Theme changes may not apply until restart

Action Required:

#### ✅ Issue #17: Emoji Preferences Not Loaded

File: src/main/kotlin/tribixbite/keyboard2/Emoji.kt:102

Status: ⚠️ NEEDS VERIFICATION

Original Problem: // TODO: Load from preferences

Impact: Emoji preferences don't persist (recent/favorite emoji)

Action Required:

#### ✅ Issue #18: ConfigurationManager Theme Application

File: src/main/kotlin/tribixbite/keyboard2/ConfigurationManager.kt:306

Status: ⚠️ NEEDS VERIFICATION

Original Problem: // TODO: Fix Theme.initialize(context).applyThemeToView(view, theme)

Impact: Theme not fully applied to all UI components

Action Required:

LOW PRIORITY Issues

#### Issue #23: Deprecated API Suppressions

Files:

Status: FUTURE WORK

Problem: Using deprecated Android APIs with @Suppress annotations

Action Required (Future):

#### Issue #24: Hardcoded Strings

File: src/main/kotlin/tribixbite/keyboard2/CustomLayoutEditDialog.kt:46,54

Status: FUTURE WORK

Problem: Hardcoded "Custom layout" and "Remove layout" strings

Action Required (Future):

Requirements

Functional Requirements

Non-Functional Requirements

Technical Design

Architecture

SettingsActivity (Material 3 Compose)

    ├── PreferenceScreen


    │   ├── Neural Prediction Settings


    │   ├── Layout Settings


    │   ├── Theme Settings


    │   └── Advanced Settings


    ├── Config (reads SharedPreferences)


    └── ConfigurationManager (applies settings)



Defaults Architecture (added 2025-12-10):


    └── Defaults object (Config.kt)


        ├── Single source of truth for all ~100 default values


        ├── Referenced by Config.kt refresh()


        ├── Referenced by SettingsActivity.kt loadCurrentSettings()


        └── Referenced by onSharedPreferenceChanged()



Storage Strategy:


    ├── SharedPreferences (settings data)


    ├── DirectBootAwarePreferences (device-protected storage)


    ├── App-specific storage (getExternalFilesDir)


    └── Scoped storage (Android 11+)

Defaults Object (Config.kt)

Added: 2025-12-10 (commit f85a2a33)

The Defaults object centralizes all app default values to prevent mismatches between different code paths:

object Defaults {

    // Appearance


    const val THEME = "cleverkeysdark"


    const val KEYBOARD_HEIGHT_PORTRAIT = 28


    const val KEYBOARD_HEIGHT_LANDSCAPE = 50


    // ... ~100 constants organized by category



    // Neural prediction


    const val NEURAL_BEAM_WIDTH = 6


    const val NEURAL_MAX_LENGTH = 20


    // ...


}

Why this matters: Previously, Config.kt and SettingsActivity.kt had separate hardcoded defaults. If they disagreed, new users would see one value in the settings UI but the keyboard would use a different value. Now both files reference Defaults.X.

Categories:

Component Breakdown

TODO: Verification & Implementation Tasks

Phase 1: Critical Settings Issues (P0)

Duration: 2-3 hours

Tasks:

Phase 2: Medium Priority Settings (P1)

Duration: 3-4 hours

Tasks:

Phase 3: Low Priority Polish (P2)

Duration: 1-2 hours

Tasks:

Testing Strategy

Unit Tests

Integration Tests

Manual Tests

Dependencies

Internal Dependencies

External Dependencies

Success Metrics

Created: 2025-10-21

Last Updated: 2025-12-10

Owner: CleverKeys Development Team

Status: Defaults object added to centralize default values (f85a2a33)