VolineUI is an Android UI component library by 5Degree. It provides production-ready form controls, feedback components, image handling, and platform utilities with two parallel APIs:
- View-based — custom
Viewsubclasses usable from XML layouts and traditional Activities/Fragments - Jetpack Compose — matching composables under
in.fivedegree.volineui.compose
The companion :app module in this repository is a demo app with side-by-side View and Compose examples for every component.
VolineUI is published on Maven Central as io.github.5degree:volineui. The transitive :volinecore module (Firebase, Room, offline queue, etc.) is pulled in automatically — you do not need to add it separately.
// app/build.gradle.kts
dependencies {
implementation("io.github.5degree:volineui:4.0.0")
}Maven Central is included by default in modern Android projects (AGP 7+), so no repositories {} changes are required.
// app/build.gradle
dependencies {
implementation 'io.github.5degree:volineui:4.0.0'
}[versions]
volineui = "4.0.0"
[libraries]
volineui = { module = "io.github.5degree:volineui", version.ref = "volineui" }// app/build.gradle.kts
dependencies {
implementation(libs.volineui)
}| Min SDK | 24 |
| Compile SDK | 36 |
| JVM target | 17 |
| Kotlin | 2.0+ (Compose-enabled) |
| Button | Button (Variants) | Input Field |
![]() |
![]() |
![]() |
| Dropdown | Radio | Date Time Picker |
![]() |
![]() |
![]() |
| Dialog | Toast | Image View |
![]() |
![]() |
![]() |
| Image View (Gallery) | Image View (Preview) | Image Carousel |
![]() |
![]() |
![]() |
PermissionManager, LocationManager, and PhotoCaptureManager are singletons that should be initialized once in your Application class:
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
PermissionManager.init(
this,
Manifest.permission.CAMERA,
Manifest.permission.ACCESS_FINE_LOCATION,
Manifest.permission.ACCESS_COARSE_LOCATION,
)
LocationManager.init(this)
PhotoCaptureManager.init(this)
}
}Register the class in AndroidManifest.xml:
<application android:name=".MyApp" ... />For global toast and dialog helpers in Compose, add containers once at the root of your UI:
@Composable
fun MyApp() {
MaterialTheme {
VolineToast.Container()
VolineDialog.Container()
// ... rest of app
}
}Then show feedback from anywhere:
VolineToast.success("Saved!")
VolineDialog.confirm(
title = "Delete?",
message = "This cannot be undone.",
onConfirm = { /* ... */ }
)| Component | View (XML) | Compose | Notes |
|---|---|---|---|
| AdvancedButton | ✓ | ✓ | Filled, outlined, text, FAB, chip, icon styles; loading/success/error states |
| InputField | ✓ | ✓ | Validation, masks, password toggle, trailing text, visual states |
| Dropdown | ✓ | ✓ | Single/multi select, search, chips, filtering |
| Radio | ✓ | ✓ | Segmented control with animated pill indicator |
| DateTimePicker | — | ✓ | Date, time, or date+time; styled like InputField |
| RulerValuePicker | ✓ | ✓ | Draggable ruler slider; horizontal/vertical, fling, snapping, labels, haptics |
| SignaturePad | ✓ | — | Drawing, undo/redo, export (PNG, JPG, SVG, Base64) |
| AdvancedImageView | ✓ | ✓ | URL/file/bitmap/URI/base64 sources; camera capture |
| ImageCarousel | ✓ | ✓ | Horizontal image list with indicators and full-screen preview |
| ActionButtonChip | — | ✓ | Compact action chip used by image components |
| Component | View | Compose |
|---|---|---|
| VolineToast | ✓ (VolineToast.show(activity, ...)) |
✓ (VolineToast.Container() + static helpers) |
| VolineDialog | ✓ (VolineDialog.show(context) { ... }) |
✓ (VolineDialog.Container() + static helpers) |
Toast types: DEFAULT, SUCCESS, ERROR, WARNING, INFO.
Dialog types: DEFAULT, SUCCESS, ERROR, WARNING, INFO, CONFIRMATION, DESTRUCTIVE.
| Manager | Purpose |
|---|---|
| PermissionManager | Request/check permissions with callbacks; handles permanent denial and settings redirect |
| LocationManager | Cached, one-shot, and streaming location via Fused Location Provider |
| PhotoCaptureManager | Camera capture and gallery picker with compression, watermark, and GPS stamping |
LocationManager and PhotoCaptureManager integrate with PermissionManager automatically.
<in.fivedegree.volineui.InputField
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:hint="Email address"
app:label="Email"
app:validationType="email"
app:enableValidation="true"
app:showClearIcon="true" />Supported validation types: none, email, phone, url, custom (with customValidationPattern). Input masks use # as the placeholder character (e.g. (###) ###-####).
VolineDialog.show(context) {
title = "Confirm Action"
message = "Are you sure you want to proceed?"
type = DialogType.CONFIRMATION
primaryButtonText = "Confirm"
secondaryButtonText = "Cancel"
onPrimaryClick = { /* handle */ }
}var text by remember { mutableStateOf("") }
InputField(
value = text,
onValueChange = { text = it },
label = "Email",
hint = "Enter your email",
validationType = ValidationType.EMAIL,
showClearIcon = true,
)val options = listOf(
DropdownOption(id = "1", label = "Option A"),
DropdownOption(id = "2", label = "Option B"),
)
Dropdown(
options = options,
label = "Choose one",
selectionMode = DropdownSelectionMode.SINGLE,
onSelectionChanged = { selected -> /* ... */ },
)<in.fivedegree.volineui.RulerValuePicker
android:id="@+id/ruler"
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:rulerMinValue="150"
app:rulerMaxValue="210"
app:rulerStep="1"
app:rulerMajorStep="10"
app:rulerValue="160"
app:rulerUnit="cm" />ruler.setOnValueChangeFinishedListener { value ->
// value is snapped and clamped
}val state = rememberRulerValuePickerState(
minValue = 150.0,
maxValue = 210.0,
step = 1.0,
majorStep = 10.0,
initialValue = 160.0,
unit = "cm",
)
RulerValuePicker(
state = state,
modifier = Modifier
.fillMaxWidth()
.height(120.dp),
tickShape = RulerTickShape.ROUNDED_LINE,
)val config = PhotoCaptureConfig(
watermarkText = "Field Survey",
printFreshLatLng = false,
targetFileSizeKB = 200,
)
PhotoCaptureManager.instance.capturePhoto(config) { result ->
when (result) {
is PhotoCaptureResult.Success -> { /* use result.file / result.bitmap */ }
is PhotoCaptureResult.Error -> { /* handle error */ }
is PhotoCaptureResult.Cancelled -> { /* user cancelled */ }
}
}Photo capture opens VolineUI's own in-app camera screen (CameraX) — it does
not launch a system camera app, and there is no fallback to one: if the
in-app camera cannot start, capturePhoto reports an Error. The camera
screen inherits the host app's Material theme for its controls, and offers
a preview sized to the selected aspect ratio, back camera and flash off
by default, flash, tap-to-focus, pinch-to-zoom, an iPhone-style ruler
zoom control whose range comes from the camera itself (swipe left to
zoom in, right to zoom out), and a Retake / Use photo review step
with text buttons. The aspect ratio and the front camera are
host-driven through PhotoCaptureConfig: aspectRatio defaults to
a locked 4:3 (the aspect pill is hidden, so the user cannot change
it); AspectRatio.NONE shows the pill and lets the user switch
4:3 / 16:9 for that capture only, nothing is remembered; and
allowFrontCamera (default false) hides the switch-camera button
and keeps the capture on the back camera, while true shows the
button on devices that have a front camera. The review image is rotated
by the photo's EXIF orientation, so it matches the returned photo.
Front-camera photos are saved as captured (not mirrored to match the
preview).
A host that wants a guided capture sets captureGuide in the config
(default NONE, today's behaviour). PERSON draws a person-shaped
outline over the live preview with a dimmed surround: the outline is
green and the shutter enabled while a person is framed inside it, red
and the shutter disabled otherwise (live selfie segmentation, ML Kit,
on-device, no network). After the user taps Use photo, face-mesh
detection runs on the finished photo and the result carries it in
addition to everything else: Success.faceMesh holds 468 points,
a bounding box, and the triangle indices between the points, in the
delivered photo's pixel space, as plain data the host can send to a
server as JSON. Joining each triangle's three points draws the full
wireframe; the points alone draw dots. If no usable face is found,
the photo is still returned with an empty mesh — that never fails
the capture. DOCUMENT launches Google's document-scanner UI instead
of this camera screen (single page, gallery import off, full cleaning:
crop, filters, shadow and stain removal); the cleaned page comes back
into the confirmation screen, then the OCR step if fields were given,
and the cleaned image is the returned photo. Note the scanner is
Play-services-based, unlike the bundled segmentation and face-mesh
models: it downloads on first use and cannot work on devices without
Play services, where it reports an Error. Both ML Kit guide models
are still beta, and add roughly 4.5 MB (segmentation) and 6.4 MB
(face mesh) to the app.
val personConfig = PhotoCaptureConfig(captureGuide = CaptureGuide.PERSON)
val documentConfig = PhotoCaptureConfig(captureGuide = CaptureGuide.DOCUMENT)
PhotoCaptureManager.instance.capturePhoto(personConfig) { result ->
if (result is PhotoCaptureResult.Success) {
println(result.faceMesh) // 468 points + box + triangles, or empty when no face
}
}A host that wants the mesh drawn on the photo does not need to do
the Canvas work itself: PhotoCaptureManager.instance.drawFaceMeshOverlay(bitmap, mesh)
returns a copy of the photo with the mesh drawn on it (green
wireframe, white dots, green box by default). Pass the bitmap and
faceMesh from the same Success result — the mesh is in that
photo's pixel space, so it lands exactly on the face. A
FaceMeshOverlayStyle changes the colours or turns a layer off
(wireframe only, dots only). The demo's example screen draws its
overlay through this function.
A host that wants photos taken only inside a particular area passes a polygon in the config:
val siteConfig = PhotoCaptureConfig(
allowedCaptureArea = listOf(
GeoPoint(19.07555, 72.87725),
GeoPoint(19.07555, 72.87815),
GeoPoint(19.07645, 72.87815),
GeoPoint(19.07645, 72.87725)
)
)
PhotoCaptureManager.instance.capturePhoto(siteConfig) { result ->
// ...
}The polygon is one ring of at least 3 points; it auto-closes, the winding order does not matter, and a point on the boundary counts as inside. The check is planar, which is correct for site-sized areas (tens/hundreds of metres). An empty list (the default) means no restriction.
When the user taps the shutter, the library fetches the current
location and the photo is only taken when the location is inside the
polygon. Otherwise no photo is taken and the user sees a dialog
naming the reason — outside the allowed area, location unavailable,
location not precise enough, or permission needed — and can dismiss
it, move inside the area, and tap the shutter again. If the user
then closes the camera, the host receives a distinct
PhotoCaptureResult.Error carrying
PhotoCaptureException.ERROR_OUTSIDE_ALLOWED_AREA (or the
reason-specific message) instead of Cancelled, so the host can
tell a geofence abandonment apart from a plain cancel. A failed
check on its own fires nothing to the host; the callback is
one-shot, so the error is only delivered when the capture ends.
Three knobs control the check: geofenceLocationMode picks which
location counts — FRESH_ONLY (a cached fix never counts, even on
timeout), FRESH_WITH_CACHE_FALLBACK (the default: fresh first,
last-known on timeout), or CACHE_ONLY (last-known only, no fresh
request); geofenceLocationTimeoutMs (default 30 seconds) bounds
the fresh wait; geofenceMaxAccuracyM (default 10) is the worst
GPS accuracy accepted — a fix worse than that, or with unknown
accuracy, fails the check, because it cannot prove it is inside
the area.
Location permission and GPS are gated before the camera opens
(the permission/settings launchers belong to the host activity, so
they cannot be resolved from the camera screen): if permission is
denied or GPS is off at launch, the host gets an Error or a
cancel, exactly like the watermark location gate. At shutter time
the check only fetches a fix. The geofence applies to camera
captures only — not to gallery picks, and not to DOCUMENT
captures, where the scanner UI replaces the camera (a polygon with
a DOCUMENT capture is ignored and logged).
A host that wants data read off a document photo passes the fields it wants in the capture config. After the user confirms the photo, an OCR step runs on-device (ML Kit, Latin + Devanagari, no network, so the photo never leaves the device) and the user picks a field, then taps its words on the photo — pinch-zoom and pan included — for each field. Tapping a word of the active field removes it, tapping a word of another field moves it, and a field's value is its words in tap order. Nothing can be typed by hand. Done is disabled until every required field has a value; optional fields left empty are absent from the result. The photo itself goes through the unchanged pipeline (watermark, compression, gallery save) and comes back together with the collected values. The same OCR step opens for gallery picks.
val config = PhotoCaptureConfig(
ocrFields = listOf(
OcrField("personName", "Person Name", required = true),
OcrField("dob", "Date of Birth", required = true),
OcrField("gender", "Gender", required = false),
OcrField("documentNumber", "Document Number", required = true)
)
)
PhotoCaptureManager.instance.capturePhoto(config) { result ->
if (result is PhotoCaptureResult.Success) {
println(result.ocrData) // e.g. {personName=..., dob=..., documentNumber=...}
}
}If recognition fails or finds no text, the user is offered Retry scan, Continue with photo only (empty OCR data), and Retake (camera) or Cancel (gallery). Back from the OCR step returns to the photo confirmation screen; in the gallery flow it cancels.
// Instant cached location
LocationManager.instance.getCachedLocation { location ->
location?.let { println(it.coordinatesString) }
}
// Stream updates every 5 seconds
val id = LocationManager.instance.startLocationUpdates(5000L) { location ->
println(location.coordinatesString)
}
LocationManager.instance.stopLocationUpdates(id)PermissionManager.instance.requestPermission(Manifest.permission.CAMERA) { result ->
if (result.isGranted) {
openCamera()
} else if (result.isPermanentlyDenied) {
PermissionManager.instance.openAppSettings()
}
}in.fivedegree.volineui
├── AdvancedButton, InputField, Dropdown, Radio, SignaturePad
├── AdvancedImageView, ImageCarousel
├── RulerValuePicker
├── VolineDialog, VolineToast
├── PermissionManager, LocationManager, PhotoCaptureManager
├── button/ — shared button enums and defaults
├── camera/ — in-app CameraX camera activity and screen
├── compose/ — Jetpack Compose equivalents
├── dialog/ — dialog types and defaults
├── dropdown/ — options, filters, state
├── imageview/ — image sources, filters, full-screen viewer
├── inputfield/ — validation, masks, colors
├── locationmanager/ — location result types
├── permissionmanager/
├── photocapturemanager/
├── radio/
├── ruler/ — scale, enums, colors, dimensions
├── signaturepad/
└── toast/
The library manifest declares permissions used by camera, location, and network features. Merge these into your app and request runtime permissions as needed:
CAMERAACCESS_FINE_LOCATION/ACCESS_COARSE_LOCATIONINTERNETVIBRATE(haptic feedback on buttons)
No FileProvider setup is needed for camera capture anymore: the in-app
camera writes directly to a file created by PhotoCaptureManager. (A
FileProvider in a host app is harmless, but it is no longer on the
capture path.)
VolineUI pulls in:
- AndroidX Core, AppCompat, Material
- Jetpack Compose (Material 3)
- Google Play Services Location
- AndroidX ExifInterface
- Glide (View image loading)
- Coil 3 (Compose image loading, GIF, network)
- CameraX 1.6.2 (in-app camera: core, camera2, lifecycle, view)
View components read colors from your app theme (e.g. colorPrimary for dialog/toast accents). Compose components accept explicit color parameters via *Defaults and *Colors objects (e.g. InputFieldDefaults, DropdownDefaults, RadioDefaults).
Run the :app module to explore all components. MainActivity links to View-based and Compose example screens for buttons, inputs, dropdowns, radios, dialogs, toasts, image views, carousels, date/time pickers, ruler pickers, signature pad, permissions, location, and photo capture.
Apache License 2.0











