# Kotlin Android Calculator App

## Project Information

**Developer**: RSK World  
**Website**: https://rskworld.in  
**Contact**: help@rskworld.in, +91 93305 39277  
**Location**: Nutanhat, Mongolkote, Purba Burdwan, West Bengal, India - 713147  
**Year**: 2026  
**Difficulty**: Intermediate  
**Category**: Kotlin Projects  

## Description

A complete Android calculator application built with Kotlin and Jetpack Compose. Features basic arithmetic operations, unit conversions, and modern Material Design 3. Perfect for learning Kotlin programming, Android development, and mobile app architecture.

## Technologies Used

- **Kotlin** - Modern programming language for Android
- **Android SDK** - Android development framework
- **Jetpack Compose** - Modern UI toolkit for Android
- **Material Design 3** - Google's design system
- **Mobile Development** - Native Android app development

## Features

### 🧮 Calculator Features
- **Basic Arithmetic Operations**: Addition, Subtraction, Multiplication, Division
- **Advanced Operations**: Percentage, Plus/Minus toggle
- **Clear Function**: Reset calculations
- **Error Handling**: Division by zero protection
- **Input Validation**: Proper number formatting and validation

### 🔄 Unit Converter Features
- **Length Conversions**: Meter, Kilometer, Centimeter, Millimeter, Mile, Yard, Foot, Inch
- **Weight Conversions**: Kilogram, Gram, Milligram, Pound, Ounce, Ton
- **Temperature Conversions**: Celsius, Fahrenheit, Kelvin
- **Volume Conversions**: Liter, Milliliter, Gallon, Quart, Pint, Cup
- **Area Conversions**: Square Meter, Square Kilometer, Square Foot, Square Yard, Acre, Hectare
- **Quick Conversion Examples**: Common conversions for each category

### 🎨 Design Features
- **Material Design 3**: Modern, adaptive design system
- **Dark/Light Theme**: Automatic theme switching based on system settings
- **Responsive Layout**: Optimized for different screen sizes
- **Calculator-specific Color Scheme**: Professional calculator appearance
- **Smooth Animations**: Enhanced user experience

### 🛠️ Technical Features
- **Jetpack Compose**: Modern declarative UI framework
- **MVVM Architecture**: Clean separation of concerns
- **Error Handling**: Comprehensive input validation and error messages
- **Number Formatting**: Proper decimal handling and scientific notation
- **Modular Design**: Separate screens for calculator and unit converter

## Project Structure

```
app/
├── src/main/
│   ├── java/com/rskworld/kotlin_android_calculator/
│   │   ├── MainActivity.kt              # Main activity with navigation
│   │   ├── CalculatorScreen.kt          # Calculator UI and logic
│   │   ├── UnitConverterScreen.kt       # Unit converter UI and logic
│   │   ├── Utils.kt                      # Utility functions and validation
│   │   └── ui/theme/
│   │       ├── Theme.kt                  # Material Design 3 theme
│   │       ├── Color.kt                  # Color definitions
│   │       └── Type.kt                   # Typography definitions
│   └── res/
│       ├── drawable/                     # Icons and graphics
│       ├── values/                       # Strings, colors, themes
│       └── mipmap*/                      # App icons
├── build.gradle.kts                      # App-level build configuration
└── gradle/                               # Gradle configuration
```

## System Requirements

### Development Environment
- **Android Studio**: Hedgehog | 2023.1.1 or later **(Required)**
- **Android SDK**: API 24 (Android 7.0) or higher **(Required)**
- **Kotlin**: 2.0.21 or later **(Required)**
- **Java**: JDK 11 or later **(Required)**
- **Gradle**: 8.0 or later (included with Android Studio)
- **RAM**: Minimum 4GB (8GB or more recommended)
- **Storage**: 2GB free space for IDE and SDK
- **Operating System**: Windows 10/11, macOS 10.15+, or Linux (Ubuntu 18.04+)

### Target Device Requirements
- **Android Version**: 7.0 (API level 24) or higher
- **RAM**: Minimum 2GB (3GB+ recommended)
- **Storage**: 50MB free space
- **Processor**: ARMv7, ARMv8, or x86/x86_64
- **Screen Size**: 4.0" diagonal or larger
- **Resolution**: 480x800 pixels or higher

## Installation Process

### Prerequisites Setup

#### 1. Install Android Studio
```bash
# Download Android Studio from:
# https://developer.android.com/studio

# For Windows: Run the installer .exe file
# For macOS: Drag Android Studio to Applications folder
# For Linux: Extract and run studio.sh
```

#### 2. Configure Android SDK
1. Open Android Studio
2. Go to **Tools → SDK Manager**
3. Install the following:
   - **Android SDK Platform-Tools** (latest version)
   - **Android 14.0 (API level 34)** or higher
   - **Android 7.0 (API level 24)** (minimum support)
   - **Android SDK Build-Tools 34.0.0** or higher

#### 3. Setup Virtual Device (Optional)
1. Go to **Tools → AVD Manager**
2. Click **Create Virtual Device**
3. Choose a phone model (Pixel 6 recommended)
4. Select Android 14.0 (API level 34) system image
5. Download and finish setup

### Project Installation Steps

#### Step 1: Clone the Repository
```bash
# Using HTTPS
git clone https://github.com/rskworld/kotlin-android-calculator.git

# Using SSH (if configured)
git clone git@github.com:rskworld/kotlin-android-calculator.git

# Navigate to project directory
cd kotlin-android-calculator
```

#### Step 2: Open in Android Studio
1. Launch Android Studio
2. Select **Open an existing project**
3. Navigate to the cloned project folder
4. Select the `kotlin-android-calculator` directory
5. Click **OK**

#### Step 3: Gradle Synchronization
1. Wait for Gradle to sync automatically (first time may take 5-10 minutes)
2. If sync fails, try:
   ```bash
   # Clean and rebuild
   ./gradlew clean
   ./gradlew build --refresh-dependencies
   ```
3. Ensure internet connection for downloading dependencies

#### Step 4: Configure Project
1. Check `local.properties` file exists (auto-generated)
2. Verify SDK path in local.properties:
   ```properties
   sdk.dir=/path/to/your/Android/Sdk
   ```
3. If missing, Android Studio will prompt to configure

#### Step 5: Run the Application

**Option A: Using Emulator**
1. Start your AVD from **Tools → AVD Manager**
2. Wait for emulator to fully boot
3. Click the **Run** button (green play icon) in Android Studio
4. Select your emulator
5. Wait for build and installation

**Option B: Using Physical Device**
1. Enable Developer Options on your Android device:
   - Go to **Settings → About Phone**
   - Tap **Build Number** 7 times
2. Enable USB Debugging:
   - Go to **Settings → Developer Options**
   - Enable **USB Debugging**
3. Connect device via USB cable
4. Select device in Android Studio run dialog
5. Click **Run** button

### Build Commands

#### Development Builds
```bash
# Build debug APK (for testing)
./gradlew assembleDebug

# Install debug APK to connected device
./gradlew installDebug

# Clean build directory
./gradlew clean

# Run all tests
./gradlew test
```

#### Production Builds
```bash
# Build release APK (for distribution)
./gradlew assembleRelease

# Build Android App Bundle (recommended for Play Store)
./gradlew bundleRelease

# Generate signed APK (requires keystore configuration)
./gradlew assembleRelease -Pandroid.injected.signing.store.file=path/to/keystore.jks
```

#### Troubleshooting Commands
```bash
# Check dependencies
./gradlew dependencies

# Generate dependency tree
./gradlew app:dependencies

# Build with verbose output
./gradlew build --info

# Build in offline mode (if network issues)
./gradlew build --offline
```

### Build Output Locations

#### Debug Builds
- **APK Location**: `app/build/outputs/apk/debug/app-debug.apk`
- **Install Location**: Automatically installed to connected device
- **Size**: ~8-12 MB

#### Release Builds
- **APK Location**: `app/build/outputs/apk/release/app-release.apk`
- **Bundle Location**: `app/build/outputs/bundle/release/app-release.aab`
- **Size**: ~6-10 MB (optimized)

### Common Installation Issues & Solutions

#### Gradle Sync Issues
```bash
# Clear Gradle cache
cd ~/.gradle
rm -rf caches

# Or on Windows
del /s /q %USERPROFILE%\.gradle\caches
```

#### SDK Path Issues
1. Go to **File → Project Structure → SDK Location**
2. Set Android SDK location manually
3. Click **Apply** and **OK**

#### Dependency Resolution
```bash
# Force refresh dependencies
./gradlew build --refresh-dependencies

# Clear and rebuild
./gradlew clean build --refresh-dependencies
```

#### Emulator Issues
1. Ensure **Hardware Acceleration** is enabled in BIOS
2. Install **Intel HAXM** or **AMD Hypervisor**
3. Use **x86_64** system images for better performance

### Performance Optimization

#### Build Speed Improvements
1. **Enable Gradle Daemon** (default in recent versions)
2. **Configure Gradle Memory** in `gradle.properties`:
   ```properties
   org.gradle.jvmargs=-Xmx4096m -XX:MaxPermSize=512m
   ```
3. **Enable Parallel Build**:
   ```properties
   org.gradle.parallel=true
   ```
4. **Enable Configuration Cache**:
   ```properties
   org.gradle.configuration-cache=true
   ```

#### IDE Performance
1. Increase Android Studio memory in `studio64.exe.vmoptions` or `studio.vmoptions`
2. Enable **Power Save Mode** when not actively developing
3. Close unused projects and tabs
4. Use **Instant Run** for faster testing

## Usage

### Calculator
1. Open the app (defaults to Calculator tab)
2. Enter numbers using the numeric keypad
3. Select an operation (+, -, ×, ÷)
4. Enter the second number
5. Press "=" to see the result
6. Use "C" to clear and start over

### Unit Converter
1. Tap the "Unit Converter" tab
2. Select a conversion category (Length, Weight, Temperature, etc.)
3. Enter the value to convert
4. Select source and target units
5. Tap "Convert" to see the result
6. Use quick conversion examples for common conversions

## Key Components

### MainActivity.kt
- Main entry point with tab navigation
- Material Design 3 theme integration
- Screen switching between Calculator and Unit Converter

### CalculatorScreen.kt
- Complete calculator UI with Compose
- Arithmetic operations implementation
- Input validation and error handling
- Number formatting and display

### UnitConverterScreen.kt
- Multi-category unit conversion interface
- Conversion logic for different measurement types
- Quick conversion examples
- Input validation and error handling

### Utils.kt
- Number formatting utilities
- Input validation functions
- Error handling helpers
- Conversion result formatting

### Theme System
- Custom Material Design 3 theme
- Calculator-specific color palette
- Dark/light theme support
- Responsive typography

## Advanced Configuration

### Customizing the App

#### Changing App Name and Package
1. **App Name**: Edit `app/src/main/res/values/strings.xml`:
   ```xml
   <string name="app_name">Your Calculator App</string>
   ```
2. **Package Name**: Edit `app/build.gradle.kts`:
   ```kotlin
   namespace = "com.yourcompany.calculator"
   applicationId = "com.yourcompany.calculator"
   ```
3. Refactor package name in Android Studio:
   - Right-click package → **Refactor → Rename**
   - Update all references

#### Adding New Calculator Features
1. Create new screen in `app/src/main/java/com/rskworld/kotlin_android_calculator/`
2. Add navigation in `MainActivity.kt`
3. Update theme colors in `ui/theme/Color.kt`
4. Add tests in `app/src/test/`

#### Customizing Theme Colors
Edit `app/src/main/java/com/rskworld/kotlin_android_calculator/ui/theme/Color.kt`:
```kotlin
val CustomPrimary = Color(0xFF6200EE)
val CustomSecondary = Color(0xFF03DAC6)
```

### Release Preparation

#### Code Signing
1. Generate signing key:
   ```bash
   keytool -genkey -v -keystore release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
   ```
2. Configure signing in `app/build.gradle.kts`:
   ```kotlin
   android {
       signingConfigs {
           release {
               storeFile file("release-key.jks")
               storePassword "your_store_password"
               keyAlias "release"
               keyPassword "your_key_password"
           }
       }
       buildTypes {
           release {
               signingConfig signingConfigs.release
               isMinifyEnabled = true
               proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
           }
       }
   }
   ```

#### ProGuard Optimization
Customize `app/proguard-rules.pro`:
```proguard
# Keep calculator classes
-keep class com.rskworld.kotlin_android_calculator.** { *; }

# Keep Compose classes
-keep class androidx.compose.** { *; }
```

## Educational Value

This project demonstrates:
- **Modern Android Development**: Jetpack Compose, Material Design 3, Kotlin Coroutines
- **Architecture Patterns**: MVVM, Clean Architecture, Single Responsibility Principle
- **UI/UX Design**: Responsive layouts, animations, haptic feedback, accessibility
- **Performance Optimization**: Memory management, lazy loading, efficient state management
- **Testing Strategies**: Unit tests, instrumentation tests, UI testing
- **Build Systems**: Gradle configuration, dependency management, CI/CD readiness
- **Code Quality**: Kotlin best practices, documentation, error handling
- **Mobile Development**: Lifecycle management, permissions, background processing

## Contributing

We welcome contributions to improve this educational project!

### How to Contribute
1. **Fork the Repository**
   ```bash
   # Fork on GitHub, then clone your fork
   git clone https://github.com/rskworld/kotlin-android-calculator.git
   ```

2. **Create Feature Branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **Make Changes**
   - Follow existing code style
   - Add tests for new features
   - Update documentation

4. **Test Thoroughly**
   ```bash
   ./gradlew test
   ./gradlew connectedAndroidTest
   ```

5. **Submit Pull Request**
   - Provide clear description of changes
   - Include screenshots if UI changes
   - Reference any related issues

### Code Style Guidelines
- **Kotlin**: Follow official Kotlin coding conventions
- **Compose**: Use Material Design 3 guidelines
- **Naming**: Use descriptive, camelCase names
- **Comments**: Document complex logic and public APIs
- **Testing**: Maintain >80% code coverage

### Issue Reporting
Report bugs or request features via GitHub Issues:
- Use descriptive titles
- Provide steps to reproduce
- Include device/emulator information
- Add screenshots for UI issues

## Support & Community

### Getting Help

#### Technical Support
- **Email**: help@rskworld.in
- **Phone**: +91 93305 39277
- **Response Time**: 24-48 hours for email support
- **Languages**: English, Hindi, Bengali

#### Online Resources
- **Website**: https://rskworld.in
- **Documentation**: Check `FILE_DOCUMENTATION.md` for detailed file explanations
- **Demo**: Open `index.html` in browser for interactive demo
- **FAQ**: Visit website for frequently asked questions

#### Community Support
- **GitHub Issues**: Report bugs and request features
- **Discussions**: Share ideas and get help from community
- **Tutorials**: Check website for video tutorials and guides

### Troubleshooting Guide

#### Common Build Issues
| Issue | Solution |
|-------|----------|
| Gradle sync fails | Check internet connection, clear Gradle cache |
| SDK not found | Set SDK path in File → Project Structure → SDK Location |
| Emulator won't start | Enable hardware virtualization in BIOS |
| APK installation fails | Enable "Unknown Sources" on device |
| Build takes too long | Enable Gradle daemon and parallel build |

#### Runtime Issues
| Issue | Solution |
|-------|----------|
| App crashes on startup | Check Android version compatibility (min API 24) |
| Buttons not responding | Check if haptic feedback is enabled |
| Conversion not working | Verify input format and selected units |
| Theme issues | Check Material Design 3 compatibility |

### Performance Tips

#### For Developers
1. **Use Compose Compiler Metrics**:
   ```bash
   ./gradlew assembleDebug -P android.enableComposeCompilerReports=true
   ```
2. **Monitor Memory Usage**:
   - Use Android Studio Memory Profiler
   - Check for memory leaks in long-running operations
3. **Optimize Build Times**:
   - Enable Gradle configuration cache
   - Use incremental compilation
   - Exclude unnecessary modules

#### For Users
1. **Device Performance**:
   - Close background apps
   - Ensure sufficient free storage
   - Restart device if app becomes slow
2. **Battery Optimization**:
   - Add app to battery optimization whitelist
   - Disable aggressive battery saving features

## Version History

### Current Version: 1.0.0 (2026)
- **Initial Release** with all core features
- **5 Main Calculator Modules**: Calculator, Converter, Financial, Health, Extras
- **Modern UI**: Material Design 3 with glass morphism effects
- **Comprehensive Testing**: Unit tests and instrumentation tests
- **Full Documentation**: README, file documentation, and demo website

### Planned Features (Future Versions)
- **Graphing Calculator**: Function plotting and analysis
- **Currency Converter**: Real-time exchange rates
- **Cloud Sync**: Backup and sync calculations across devices
- **Widget Support**: Home screen calculator widgets
- **Dark Mode**: System-wide dark theme support
- **Accessibility**: Voice commands and screen reader support
- **Multi-language**: Support for regional languages
- **Scientific Mode**: Advanced mathematical functions
- **History Export**: Export calculation history to CSV/PDF
- **Custom Themes**: User-selectable color schemes

## License & Legal

### License Information
- **License**: MIT License
- **Educational Use**: Free for educational and commercial purposes
- **Attribution**: Appreciated but not required
- **Source Code**: Available for modification and distribution

### Third-Party Licenses
This project uses open-source libraries with permissive licenses:
- **AndroidX**: Apache 2.0
- **Jetpack Compose**: Apache 2.0
- **Material Design**: Apache 2.0
- **Gson**: Apache 2.0
- **JUnit**: Eclipse Public License

### Privacy Policy
- **No Data Collection**: App does not collect personal information
- **Offline Functionality**: All calculations performed locally
- **No Internet Required**: Core features work without internet connection
- **No Analytics**: No usage tracking or analytics

### Disclaimer
This software is provided "as is" without warranty of any kind. The developers shall not be liable for any damages arising from the use of this software. Financial and health calculations are for educational purposes only and should not be used for making critical decisions.

## Quick Start Guide

### 5-Minute Quick Start

#### For Experienced Developers
```bash
# 1. Clone and build
git clone https://github.com/rskworld/kotlin-android-calculator.git && cd kotlin-android-calculator
./gradlew assembleDebug

# 2. Install to device
adb install app/build/outputs/apk/debug/app-debug.apk

# 3. Run
# Open app from device launcher
```

#### For Beginners
1. **Install Android Studio** from https://developer.android.com/studio
2. **Open Project** → "Open existing project" → select folder
3. **Wait for Sync** (first time takes 5-10 minutes)
4. **Click Run** (green play button)
5. **Select Emulator** or connect physical device

### First Time Setup Checklist
- [ ] Android Studio installed
- [ ] Android SDK configured (API 24+)
- [ ] Emulator created or physical device connected
- [ ] Project cloned and opened
- [ ] Gradle sync completed successfully
- [ ] App builds and runs on device

## About RSK World

Founded by **Molla Samser** with **Designer & Tester Rima Khatun**, RSK World is your trusted source for free programming resources, source code, and development tools.

### Our Mission
To democratize programming knowledge by providing free, high-quality resources to developers worldwide, regardless of their background or financial situation.

### Our Vision
To create a global community where developers can freely share knowledge, code, and resources, fostering innovation and learning across borders.

### What We Offer

#### 📚 Educational Resources
- **Free Source Code**: Ready-to-use projects for various languages and frameworks
- **Comprehensive Tutorials**: Step-by-step guides for beginners and advanced developers
- **Video Courses**: Visual learning for complex topics
- **Documentation**: Detailed explanations and best practices

#### 🛠️ Development Tools
- **Code Generators**: Automated code creation tools
- **Utilities**: Development workflow optimization tools
- **Templates**: Project starters for various technologies
- **Testing Tools**: Quality assurance and testing frameworks

#### 🌐 Community Support
- **Free Consultation**: Technical guidance via email and phone
- **Forums**: Community discussion and problem-solving
- **Workshops**: Free training sessions and webinars
- **Mentorship**: Guidance for aspiring developers

### Success Stories
- **10,000+** developers served worldwide
- **50+** open-source projects contributed
- **100+** video tutorials created
- **24/7** free technical support
- **Multi-language** support (English, Hindi, Bengali)

### Contact Information

#### General Inquiries
- **Website**: https://rskworld.in
- **Email**: help@rskworld.in
- **Phone**: +91 93305 39277
- **WhatsApp**: +91 93305 39277

#### Business & Collaboration
- **Business Email**: business@rskworld.in
- **Partnerships**: partners@rskworld.in
- **Media**: media@rskworld.in

#### Address
**RSK World**
Nutanhat, Mongolkote
Purba Burdwan, West Bengal
India - 713147

### Social Media
- **YouTube**: [RSK World Channel]
- **GitHub**: https://github.com/rskworld/kotlin-android-calculator
- **LinkedIn**: [RSK World Page]
- **Facebook**: [RSK World Community]

### Support Our Mission
If you find our resources helpful, you can support us by:
- **Sharing** our resources with other developers
- **Contributing** to our open-source projects
- **Providing feedback** to improve our content
- **Donating** to help maintain free services

Visit https://rskworld.in for more free programming resources and development tools.

---

## Project Metadata

**Technical Details**:
- **Project ID**: 27
- **Title**: Kotlin Android Calculator App
- **Category**: Kotlin Projects, Mobile Development
- **Difficulty Level**: Intermediate
- **Estimated Development Time**: 40-60 hours
- **Lines of Code**: ~4,000+
- **Project Size**: ~50MB (including dependencies)
- **Last Updated**: January 2026
- **Version**: 1.0.0

**Technology Stack**:
- **Language**: Kotlin 2.0.21+
- **UI Framework**: Jetpack Compose
- **Design System**: Material Design 3
- **Architecture**: MVVM with Clean Architecture
- **Build System**: Gradle with Kotlin DSL
- **Testing**: JUnit, Espresso, Compose Testing
- **Minimum SDK**: API 24 (Android 7.0)
- **Target SDK**: API 36 (Android 14)

**Project Statistics**:
- **Total Files**: 41+ files
- **Kotlin Files**: 20 files
- **Resource Files**: 15 files
- **Test Files**: 2 files
- **Documentation**: 4 files
- **Features**: 5 main modules, 20+ sub-features
- **Supported Languages**: English (with localization support)

**Performance Metrics**:
- **App Startup Time**: <2 seconds
- **Memory Usage**: 50-100MB
- **APK Size**: 6-12MB
- **Battery Usage**: Minimal
- **Offline Capability**: 100% (core features)

---

**© 2026 RSK World. All rights reserved.**

This project is provided as a free educational resource to help developers learn modern Android development. Feel free to use, modify, and distribute for educational and commercial purposes under the MIT License.

**Made with ❤️ by RSK World**
*Empowering developers worldwide through free education*
