# How to Configure Flick Sensitivity and Angle Ranges in JapaneseKeyboard

> Customize JapaneseKeyboard flick sensitivity and angle for personalized input. Learn to tune pixel thresholds and define directional mappings for optimal typing.

- Repository: [Kazu/japanesekeyboard](https://github.com/kazumaproject/japanesekeyboard)
- Tags: how-to-guide
- Published: 2026-03-05

---

**Configure flick sensitivity and angle ranges in JapaneseKeyboard by calling `setFlickSensitivityValue()` for pixel-threshold tuning and `setAngleAndRange()` for custom directional mappings.**

The JapaneseKeyboard project provides granular control over flick gesture interpretation across all keyboard layouts, including TenKey, Tablet, and the custom circular-flick interface. By adjusting sensitivity thresholds and angular segment boundaries, developers can tailor the typing experience to specific device sizes, user dexterity levels, or custom design languages.

## Understanding Flick Sensitivity

Flick sensitivity acts as a pixel-based threshold that determines whether a touch movement registers as a **tap** or a **flick**. The default value is `100` pixels, defined in each keyboard view implementation.

When the absolute distance of a touch move is less than the sensitivity value, the system interprets the gesture as a tap. Exceeding this threshold triggers flick detection logic.

### Setting Sensitivity Programmatically

To configure sensitivity directly on a keyboard view instance, call `setFlickSensitivityValue()`:

```kotlin
// FlickKeyboardView.kt, TabletKeyboardView.kt, or TenKey.kt
val keyboard = FlickKeyboardView(context)
keyboard.setFlickSensitivityValue(80)   // More sensitive (shorter swipes trigger flicks)
keyboard.setFlickSensitivityValue(150)  // Less sensitive (requires longer swipes)

```

The internal motion handling logic in [`FlickKeyboardView.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/FlickKeyboardView.kt) (around line 1840) applies this threshold:

```kotlin
abs(distanceX) < flickSensitivity && abs(distanceY) < flickSensitivity -> GestureType.Tap

```

### Reading from SharedPreferences

The production implementation reads user preferences from [`pref_custom.xml`](https://github.com/kazumaproject/japanesekeyboard/blob/main/pref_custom.xml) and applies them via [`IMEService.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/IMEService.kt):

```kotlin
// IMEService.kt
keyboardView.setFlickSensitivityValue(flickSensitivityPreferenceValue ?: 100)
tabletView.setFlickSensitivityValue(flickSensitivityPreferenceValue ?: 100)
customLayoutDefault.setFlickSensitivityValue(flickSensitivityPreferenceValue ?: 100)

```

The preference key `flickSensitivityPreferenceValue` is defined in [`app/src/main/res/xml/pref_custom.xml`](https://github.com/kazumaproject/japanesekeyboard/blob/main/app/src/main/res/xml/pref_custom.xml).

## Customizing Circular Flick Angle Ranges

For the circular-flick layout, the keyboard divides the popup into four directional segments: **UP**, **DOWN**, **UP_RIGHT_FAR**, and **UP_LEFT_FAR**. Each segment is defined by a start angle and sweep size in degrees.

### Default Angle Configuration

When no custom ranges are provided, [`FlickKeyboardView.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/FlickKeyboardView.kt) uses the following default map in the `attachKeyBehavior` block:

```kotlin
mapOf(
    FlickDirection.UP to Pair(225f, 90f),           // 225° to 315°
    FlickDirection.UP_RIGHT_FAR to Pair(315f, 90f), // 315° to 45° (wraps around)
    FlickDirection.DOWN to Pair(45f, 90f),           // 45° to 135°
    FlickDirection.UP_LEFT_FAR to Pair(135f, 90f)    // 135° to 225°
)

```

### Defining Custom Ranges

To override the defaults programmatically, construct a `Map<FlickDirection, Pair<Float, Float>>` where each pair represents `(startAngle, sweepAngle)`:

```kotlin
val customRanges = mapOf(
    FlickDirection.UP to Pair(210f, 80f),
    FlickDirection.UP_RIGHT_FAR to Pair(310f, 100f),
    FlickDirection.DOWN to Pair(30f, 80f),
    FlickDirection.UP_LEFT_FAR to Pair(130f, 80f)
)

val viewScale = 1.2f  // Makes the popup 20% larger
flickKeyboardView.setAngleAndRange(customRanges, viewScale)

```

The `setAngleAndRange()` method in [`FlickKeyboardView.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/FlickKeyboardView.kt) stores these values in `customAngleAndRange` and passes them to `CustomAngleFlickController` for gesture calculation.

### Applying Changes via Settings UI

The [`CircularFlickSettingsFragment.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/CircularFlickSettingsFragment.kt) provides a user interface for adjusting angles visually. When the user modifies a segment, the fragment builds an `angleData` map and applies it to both the preview and the active keyboard:

```kotlin
// CircularFlickSettingsFragment.kt (simplified)
val ranges = angleData // Map<FlickDirection, Pair<Float, Float>>
binding.previewView.setRanges(ranges)          // Update preview only
keyboardView.setAngleAndRange(ranges, scale) // Update actual keyboard

```

## Complete Configuration Pipeline

When the IME service initializes, it orchestrates both sensitivity and angle configurations through the following flow:

1. **Read Preferences**: [`IMEService.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/IMEService.kt) retrieves `flickSensitivityPreferenceValue` from [`pref_custom.xml`](https://github.com/kazumaproject/japanesekeyboard/blob/main/pref_custom.xml).
2. **Apply Sensitivity**: The service calls `setFlickSensitivityValue()` on `FlickKeyboardView`, `TabletKeyboardView`, and `TenKey` instances.
3. **Apply Custom Angles**: If the user previously configured custom circular-flick angles via `CircularFlickSettingsFragment`, those values are loaded and applied through `setAngleAndRange()`.
4. **Runtime Updates**: Both settings can be updated programmatically at any time by calling the respective setter methods on the active keyboard view.

## Summary

- **Flick sensitivity** controls the pixel threshold distinguishing taps from flicks, defaulting to `100` pixels and configurable via `setFlickSensitivityValue()`.
- **Angle ranges** define the directional segments for circular-flick keyboards using a `Map<FlickDirection, Pair<Float, Float>>` of start angles and sweeps.
- **Key files** include [`FlickKeyboardView.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/FlickKeyboardView.kt) for implementation, [`IMEService.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/IMEService.kt) for preference application, and [`CircularFlickSettingsFragment.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/CircularFlickSettingsFragment.kt) for UI-based customization.
- Both mechanisms can be adjusted programmatically or through the Settings UI, allowing real-time adaptation to user preferences and device characteristics.

## Frequently Asked Questions

### How do I make the keyboard more sensitive to short flick gestures?

Decrease the flick sensitivity value below the default of `100` pixels. Call `setFlickSensitivityValue(60)` on your keyboard view instance, or adjust the preference in [`pref_custom.xml`](https://github.com/kazumaproject/japanesekeyboard/blob/main/pref_custom.xml) to a lower value. Smaller numbers require less finger travel to trigger a flick action.

### Can I change the angle ranges for the circular flick without modifying source code?

Yes. The `CircularFlickSettingsFragment` provides a visual interface for adjusting start angles and sweep sizes for each directional segment. Changes are persisted and applied automatically to the active keyboard view via `setAngleAndRange()`. You only need to modify source code if you want to change the default hard-coded values in [`FlickKeyboardView.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/FlickKeyboardView.kt).

### What happens if I provide an incomplete angle range map?

The keyboard view checks if `customAngleAndRange` is empty before creating the controller. If your map is missing entries or is empty, the system falls back to the default angle map defined in the `attachKeyBehavior` block. Always ensure your map contains all four `FlickDirection` entries (UP, DOWN, UP_RIGHT_FAR, UP_LEFT_FAR) for predictable behavior.

### Where is the flick sensitivity threshold actually enforced?

The threshold is enforced in the motion event handling logic of each keyboard view. In [`FlickKeyboardView.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/FlickKeyboardView.kt) (around line 1840), the code compares the absolute distance of touch movement against `flickSensitivity`. If both X and Y distances are below the threshold, the gesture is classified as a `GestureType.Tap`; otherwise, it proceeds to flick detection and angle calculation.