134 lines
4.3 KiB
Markdown
134 lines
4.3 KiB
Markdown
|
# Android Widget Setup
|
||
|
|
|
||
|
|
The Android home screen widget is automatically included in the app build. This document describes the implementation details.
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
The widget uses **Material 3 / Material You** design with dynamic colors on Android 12+ (API 31+).
|
||
|
|
|
||
|
|
## Widget Design (Native Android)
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────┐
|
||
|
|
│ ✨ Ask Conduit │ ← Primary color (dynamic)
|
||
|
|
│ │
|
||
|
|
├───────────┬───────────┬─────────────┤
|
||
|
|
│ 📷 │ 🖼️ │ 📋 │
|
||
|
|
│ Camera │ Photos │ Clipboard │ ← Secondary container
|
||
|
|
└───────────┴───────────┴─────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
### Material You (Android 12+)
|
||
|
|
|
||
|
|
- **Primary button**: System accent color (`system_accent1_600`)
|
||
|
|
- **Secondary buttons**: Secondary container color (`system_accent2_100`)
|
||
|
|
- **Background**: Neutral surface color (`system_neutral1_10`)
|
||
|
|
- **Icons**: Tinted with `system_accent1_700`
|
||
|
|
|
||
|
|
### Fallback (Android 11 and below)
|
||
|
|
|
||
|
|
- **Primary button**: Material 3 default purple (`#6750A4`)
|
||
|
|
- **Secondary buttons**: Light purple container (`#E8DEF8`)
|
||
|
|
- **Background**: Near-white surface (`#FFFBFE`)
|
||
|
|
|
||
|
|
## Files Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
android/app/src/main/
|
||
|
|
├── kotlin/.../ConduitWidgetProvider.kt # Widget logic
|
||
|
|
├── res/
|
||
|
|
│ ├── layout/
|
||
|
|
│ │ └── conduit_widget.xml # Widget layout
|
||
|
|
│ ├── drawable/
|
||
|
|
│ │ ├── widget_background.xml # Surface background
|
||
|
|
│ │ ├── widget_button_primary.xml # Primary button
|
||
|
|
│ │ ├── widget_button_secondary.xml # Secondary buttons
|
||
|
|
│ │ ├── ic_widget_camera.xml # Camera icon
|
||
|
|
│ │ ├── ic_widget_photos.xml # Photos icon
|
||
|
|
│ │ ├── ic_widget_clipboard.xml # Clipboard icon
|
||
|
|
│ │ └── widget_preview.xml # Widget picker preview
|
||
|
|
│ ├── drawable-v31/ # Material You overrides
|
||
|
|
│ │ └── (same files with dynamic colors)
|
||
|
|
│ ├── values/
|
||
|
|
│ │ ├── colors.xml # Light mode colors
|
||
|
|
│ │ ├── dimens.xml # Widget dimensions
|
||
|
|
│ │ └── strings.xml # Widget strings
|
||
|
|
│ ├── values-night/
|
||
|
|
│ │ └── colors.xml # Dark mode colors
|
||
|
|
│ └── xml/
|
||
|
|
│ └── conduit_widget_info.xml # Widget metadata
|
||
|
|
└── AndroidManifest.xml # Widget receiver registration
|
||
|
|
```
|
||
|
|
|
||
|
|
## Deep Link Handling
|
||
|
|
|
||
|
|
The widget uses `homewidget://` URL scheme:
|
||
|
|
|
||
|
|
| Action | URL |
|
||
|
|
|--------|-----|
|
||
|
|
| New Chat | `homewidget://new_chat` |
|
||
|
|
| Camera | `homewidget://camera` |
|
||
|
|
| Photos | `homewidget://photos` |
|
||
|
|
| Clipboard | `homewidget://clipboard` |
|
||
|
|
|
||
|
|
## Widget Configuration
|
||
|
|
|
||
|
|
The widget is configured in `res/xml/conduit_widget_info.xml`:
|
||
|
|
|
||
|
|
- **Min size**: 250x110dp (3x2 cells)
|
||
|
|
- **Resizable**: Horizontal and vertical
|
||
|
|
- **Category**: Home screen
|
||
|
|
- **Update period**: Never (static widget)
|
||
|
|
|
||
|
|
## Testing
|
||
|
|
|
||
|
|
1. Build and install the debug APK:
|
||
|
|
```bash
|
||
|
|
flutter build apk --debug
|
||
|
|
flutter install
|
||
|
|
```
|
||
|
|
|
||
|
|
2. Long press on home screen
|
||
|
|
3. Tap "Widgets"
|
||
|
|
4. Search for "Conduit"
|
||
|
|
5. Drag widget to home screen
|
||
|
|
|
||
|
|
## Customization
|
||
|
|
|
||
|
|
### Changing the accent color
|
||
|
|
|
||
|
|
The widget automatically picks up the system's Material You palette on Android 12+. On older versions, modify the fallback colors in `values/colors.xml`:
|
||
|
|
|
||
|
|
```xml
|
||
|
|
<color name="widget_primary_fallback">#YOUR_COLOR</color>
|
||
|
|
```
|
||
|
|
|
||
|
|
### Changing widget size
|
||
|
|
|
||
|
|
Modify `res/xml/conduit_widget_info.xml`:
|
||
|
|
|
||
|
|
```xml
|
||
|
|
<appwidget-provider
|
||
|
|
android:minWidth="250dp"
|
||
|
|
android:minHeight="110dp"
|
||
|
|
android:targetCellWidth="3"
|
||
|
|
android:targetCellHeight="2"
|
||
|
|
...
|
||
|
|
/>
|
||
|
|
```
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
### Widget not appearing
|
||
|
|
|
||
|
|
- Ensure the app was installed (not just built)
|
||
|
|
- Try restarting the home launcher
|
||
|
|
- Check that `ConduitWidgetProvider` is registered in AndroidManifest.xml
|
||
|
|
|
||
|
|
### Colors not updating on theme change
|
||
|
|
|
||
|
|
- Widget colors are set at creation time
|
||
|
|
- User needs to re-add widget after theme change
|
||
|
|
- Or trigger update via `HomeWidget.updateWidget()` from Flutter
|
||
|
|
|