Skip to content

KIVYMD_2.0_UPGRADE.md

Latest commit

 

History

History
209 lines (165 loc) · 7 KB

KIVYMD_2.0_UPGRADE.md

File metadata and controls

209 lines (165 loc) · 7 KB

KivyMD 2.0 Upgrade Summary

Overview

Successfully upgraded CalorieApp Testnet from KivyMD 1.2.0 to KivyMD 2.0.1.dev0 (master branch) with zero deprecation warnings.

Upgrade Date

November 16, 2025

Version Changes

  • KivyMD: 1.2.0 → 2.0.1.dev0 (git-d668d8b, master branch)
  • Kivy: 2.3.0 (stable, unchanged)
  • Python: 3.12.0 (unchanged)

Breaking Changes Addressed

1. Button Classes Removed

KivyMD 2.0 removed several legacy button classes. Created compatibility layer in src/core/legacy_buttons.py:

Removed Classes → New Wrappers:

  • MDRaisedButton → MDButton(style="elevated")
  • MDFlatButton → MDButton(style="text")
  • MDFillRoundFlatButton → MDButton(style="filled", radius=[18])
  • MDFillRoundFlatIconButton → MDButton(style="filled", radius=[18])

All classes registered with Factory for KV file compatibility.

2. List Item Classes Restructured

Removed Classes → New Wrappers:

  • OneLineIconListItem → MDListItem
  • OneLineAvatarIconListItem → MDListItem
  • IconLeftWidget → MDListItemLeadingIcon
  • IconRightWidget → MDListItemTrailingIcon

3. Typography System Overhaul

Material Design 3 typography replaced old H1-H6 system:

Old Style → New Style:

  • H5 → Title
  • H6 → Title
  • Body1 → Body
  • Body2 → Body
  • Subtitle1 → Label
  • Subtitle2 → Label
  • Caption → Label
  • Button → Label
  • Overline → Label

Files Updated: 18 KV files across entire codebase

4. TextField Mode Property

Breaking Change:

  • Old: mode: "fill"
  • New: mode: "filled"

Files Updated: 20+ occurrences across all KV files

5. Top/Bottom AppBar Deprecated

Removed in Previous Session:

  • MDBottomAppBar → Simple MDBoxLayout bottom bars
  • MDTopAppBar → Simple MDBoxLayout top bars

Files Updated:

  • login_screen.kv
  • wallet_setup_screen.kv
  • account_naming_screen.kv

6. Unicode Console Encoding Fix

Issue: Windows console (cp1252) cannot display Unicode emojis Solution: Replaced emoji checkmarks with text markers

  • ✅ → [SUCCESS]
  • ❌ → [ERROR]

File: src/core/app.py line 76

Files Modified

Core Compatibility Layer

  • src/core/legacy_buttons.py (NEW)
    • 8 legacy button/list classes
    • Factory registration for KV access
    • ~65 lines

Python Import Updates (11 files)

  • src/core/app.py
  • src/utils/dialogs.py
  • src/screens/WalletScreen.py
  • src/screens/SettingsScreen.py
  • src/screens/CreateExtraWalletScreen.py
  • src/screens/CreateWalletScreen.py
  • src/screens/MnemonicImportScreen.py
  • src/screens/MnemonicDisplayScreen.py
  • src/screens/KeypairImportScreen.py
  • src/screens/ImportChoiceScreen.py
  • src/screens/AccountChoiceScreen.py

KV File Updates (24 files - entire kv/ directory)

Typography: All KV files updated with new font_style values TextField: All KV files updated with mode: "filled" Bottom Bars: 3 screen files replaced deprecated AppBar components

Dependency Manifests

  • requirements.txt
  • config/requirements.txt
  • buildozer.spec

All updated to pull KivyMD from master branch:

  • pip: kivymd @ git+https://github.com/kivymd/KivyMD.git@master
  • buildozer: kivymd@https://github.com/kivymd/KivyMD/archive/master.zip

File Cleanup

  • Renamed: src/core/calorieapptestnet.kv → calorieapptestnet.kv.old
    • Prevented automatic loading of obsolete monolithic file
    • Contained 4442 lines of outdated code with H5 typography and deprecated components

Verification Results

✅ Success Criteria

  1. Zero Deprecation Warnings - Verified in app startup log
  2. Clean Startup - All KV files load successfully
  3. XRPL Connectivity - Client manager connects to testnet servers
  4. Factory Registration - All 195+ symbols loaded without duplicates
  5. Modular KV Architecture - 24 screen files load in correct order

Console Output

[INFO   ] [KivyMD      ] 2.0.1.dev0, git-d668d8b, 2025-11-16
[INFO   ] [Factory     ] 195 symbols loaded
[INFO   ] [SUCCESS] Connected to XRPL server: https://testnet.xrpl-labs.com
[INFO   ] [Loaded KV file] base.kv
[INFO   ] [Loaded KV file] account_choice_screen.kv
[INFO   ] [Loaded KV file] account_naming_screen.kv
...

No errors, exceptions, or deprecation warnings in startup sequence.

Migration Strategy

Compatibility Layer Approach

Rather than refactoring all button usage across 24 screens and 11 Python files, we created a thin compatibility layer that:

  1. Wraps new KivyMD 2.0 classes with legacy names
  2. Provides sensible defaults (e.g., style="elevated" for MDRaisedButton)
  3. Maintains Factory registration for KV file access
  4. Requires minimal code changes (import path updates only)

Benefits

  • ✅ Minimal code churn (11 import statements vs 100+ button replacements)
  • ✅ Maintains existing KV file syntax
  • ✅ Easy to revert if needed
  • ✅ Clear upgrade path for future Material Design 3 migration
  • ✅ Centralized compatibility logic

Future Considerations

Gradual MD3 Migration

The compatibility layer is a stopgap. Consider migrating to native MD3 components:

  1. Replace MDRaisedButton → MDButton(style="elevated") in KV files
  2. Update button styling to match MD3 design tokens
  3. Remove legacy_buttons.py once migration complete

Typography Fine-Tuning

Current mapping uses conservative choices:

  • All subtitles/captions → "Label" (may be too uniform)
  • Consider using MD3 size variants: "Title" (large/medium/small), "Body" (large/medium/small), "Label" (large/medium/small)

TextField Mode Standardization

Verify UI consistency after mode: "filled" changes:

  • Check field appearance on different screens
  • Ensure proper theming with MD3 color scheme
  • Consider switching to mode: "outlined" if filled style doesn't match design

Testing Recommendations

Functional Testing

  • Create new wallet flow (mnemonic generation)
  • Import existing wallet (mnemonic/keypair)
  • Account switching dialog
  • Settings screen list items
  • Transaction sending with text fields
  • NFT minting with input validation

Visual Regression Testing

  • Compare button styling (elevated vs old raised)
  • Verify text field appearance (filled mode)
  • Check typography hierarchy (Title vs H5)
  • Test bottom bar layout on all screens

Performance Baseline

  • App startup time
  • KV file loading duration
  • Screen transition smoothness

References

Conclusion

The KivyMD 2.0 upgrade was completed successfully with:

  • 0 deprecation warnings
  • 0 runtime errors
  • 11 Python files updated
  • 24 KV files modernized
  • 1 compatibility layer created
  • Full backward compatibility maintained

The app now runs on the latest KivyMD development branch with Material Design 3 components and is ready for Android APK builds without deprecation noise.