# JapaneseKeyboard Flick Input Types: CIRCULAR_FLICK, CROSS_FLICK, STANDARD_FLICK, and PETAL_FLICK Explained

> Explore the four JapaneseKeyboard flick input types: CIRCULAR_FLICK, CROSS_FLICK, STANDARD_FLICK, and PETAL_FLICK. Learn how each type affects popup geometry and character selection for efficient input.

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

---

**The JapaneseKeyboard library defines four distinct flick input types—`CIRCULAR_FLICK`, `CROSS_FLICK`, `STANDARD_FLICK`, and `PETAL_FLICK`—that control popup rendering geometry and determine whether a key offers four or eight alternative characters.**

The `kazumaproject/japanesekeyboard` repository implements these flick gestures in the `KeyType` enum to support both Japanese kana input and English QWERTY layouts. Selecting the correct flick input type ensures the visual guide matches the user's expected interaction model, whether they need eight-directional radial menus for complex glyphs or hierarchical petal selections for emoji categories.

## The Four Flick Input Types

### CIRCULAR_FLICK: Eight-Directional Radial Input

**`CIRCULAR_FLICK`** creates a **radial (circular) popup** that surrounds the pressed key. This layout supports up to **eight directional alternatives** (up, down, left, right, and four diagonals) plus the center tap.

Use this type when a single key must expose **many related glyphs**—for example, a kana character that requires voiced, semi-voiced, small-kana, and punctuation variants, or dense emoji groups. In [`KeyboardDefaultLayouts.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/KeyboardDefaultLayouts.kt), the *sumire* key is configured as `CIRCULAR_FLICK` to accommodate its extensive variant set (lines 4451‑4470).

### CROSS_FLICK: Classic Four-Direction Input

**`CROSS_FLICK`** generates the classic **cross-shaped popup** with four cardinal directions (up, down, left, right) plus the center tap, yielding **four alternatives** total.

This is the default choice for most Japanese keys (e.g., mapping "か" to "が" via right-flick) and for numeric or symbol keys where only four variants exist. The geometry is straightforward: each direction maps to a single `FlickChars` entry defined in [`AppCompatButtonExtension.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/AppCompatButtonExtension.kt).

### STANDARD_FLICK: QWERTY-Style Four-Direction Input

**`STANDARD_FLICK`** uses the same four-direction geometry as `CROSS_FLICK`, but the **character mapping follows QWERTY conventions**. For example, a right-flick might produce the next letter in the alphabet, while a left-flick produces the previous letter.

Reserve this type for the **English QWERTY keyboard** where users expect "shift-right/shift-left" behavior for capital letters, symbols, or number shortcuts. The underlying popup view is identical to `CROSS_FLICK`, but the `FlickChars` construction logic in [`AppCompatButtonExtension.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/AppCompatButtonExtension.kt) applies the English character set instead of Japanese kana rules.

### PETAL_FLICK: Hierarchical Flower Input

**`PETAL_FLICK`** renders a **petal-shaped popup**—center tap plus four surrounding petals offset at angles, creating a "flower-like" appearance. Like `CROSS_FLICK`, it supports **four alternatives**, but the visual distinction signals a different interaction pattern.

Deploy this type for **two-step or hierarchical** selections where the first popup shows a coarse set (e.g., emoji categories) and a second layer reveals the exact glyph. The petal shape provides a clear visual cue that the alternatives are organized hierarchically rather than as simple directional shifts. The repository uses this in conjunction with `TWO_STEP_FLICK` logic to implement sticky or layered key behaviors.

## Source Code Architecture

### Declaration in KeyModels.kt

The enum definition resides in [`custom_keyboard/src/main/java/com/kazumaproject/custom_keyboard/data/KeyModels.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/custom_keyboard/src/main/java/com/kazumaproject/custom_keyboard/data/KeyModels.kt) (lines 94‑108):

```kotlin
enum class KeyType {
    CIRCULAR_FLICK,
    CROSS_FLICK,
    STANDARD_FLICK,
    PETAL_FLICK,
    // ... additional hierarchical types
}

```

### Layout Assignment in KeyboardDefaultLayouts.kt

Individual keys receive their `keyType` assignment in [`KeyboardDefaultLayouts.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/KeyboardDefaultLayouts.kt). For example:

```kotlin
// Circular layout for complex variants
"sumire" -> KeyType.CIRCULAR_FLICK

// Standard cross layout for Japanese kana
"ka" -> KeyType.CROSS_FLICK

// QWERTY layout for English input
"e" -> KeyType.STANDARD_FLICK

// Petal layout for emoji hierarchies
"emoji_smile" -> KeyType.PETAL_FLICK

```

### Rendering Logic in FlickKeyboardView.kt

The view layer switches on `key.keyType` to instantiate the correct popup class. In [`FlickKeyboardView.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/FlickKeyboardView.kt) (lines 570‑720), a when-expression branches to draw either radial guides, cross guides, or petal shapes based on the enum value.

### Character Mapping in AppCompatButtonExtension.kt

The `FlickChars` data class construction and visual guide attachment occur in [`tenkey/src/main/java/com/kazumaproject/tenkey/extensions/AppCompatButtonExtension.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/tenkey/src/main/java/com/kazumaproject/tenkey/extensions/AppCompatButtonExtension.kt) (lines 166‑210). This file maps specific characters to directional vectors (left, right, top, bottom) and wires the `setTenKeyTextJapaneseWithFlickGuide` extension function to the corresponding `KeyType`.

### Event Dispatch in TenKey.kt

Finally, the core `FlickListener` implementation in [`TenKey.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/TenKey.kt) (lines 1200‑1280) dispatches `GestureType.Flick` events based on the user's detected flick direction, completing the input chain from visual guide to character insertion.

## Practical Configuration Examples

### Configuring a Circular Flick Key

To enable eight-directional input for a key with multiple glyph variants:

```kotlin
// In KeyboardDefaultLayouts.kt
KeyData(
    key = "shi",
    keyType = KeyType.CIRCULAR_FLICK,
    flickChars = FlickChars(
        center = "し",
        right = "じ",
        left = "ぢ",
        top = "シ",
        bottom = "ジ",
        topRight = "゛",
        topLeft = "゜",
        bottomRight = "っ",
        bottomLeft = "ッ"
    )
)

```

### Configuring a Standard Flick Key for QWERTY

To implement left/right alphabet shifting on the English keyboard:

```kotlin
// In KeyboardDefaultLayouts.kt
KeyData(
    key = "e",
    keyType = KeyType.STANDARD_FLICK,
    flickChars = FlickChars(
        center = "e",
        right = "f",
        left = "d",
        top = "E",
        bottom = "3"
    )
)

```

## Summary

- **CIRCULAR_FLICK** provides a radial popup with up to eight alternatives, ideal for complex kana or dense emoji sets.
- **CROSS_FLICK** offers the standard four-direction cross layout used for most Japanese keys and numeric input.
- **STANDARD_FLICK** applies the same four-direction geometry but follows QWERTY character mapping conventions for English input.
- **PETAL_FLICK** renders a flower-shaped popup designed for hierarchical or two-step selection flows.

## Frequently Asked Questions

### What is the maximum number of alternatives for each flick input type?

`CIRCULAR_FLICK` supports up to **eight** directional alternatives plus the center tap. `CROSS_FLICK`, `STANDARD_FLICK`, and `PETAL_FLICK` each support **four** directional alternatives plus the center tap. These limits are enforced by the `FlickChars` data class structure in [`AppCompatButtonExtension.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/AppCompatButtonExtension.kt).

### How do I assign a flick input type to a specific key?

Define the `keyType` property in your layout definition within [`KeyboardDefaultLayouts.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/KeyboardDefaultLayouts.kt). For example, assign `KeyType.CROSS_FLICK` to a kana key or `KeyType.STANDARD_FLICK` to an English letter key. The `FlickKeyboardView` will automatically render the appropriate popup geometry based on this enum value.

### What is the difference between CROSS_FLICK and STANDARD_FLICK?

Both use an identical four-direction cross-shaped popup geometry. The distinction lies in **character mapping logic**: `CROSS_FLICK` expects Japanese kana variants (e.g., voiced marks), while `STANDARD_FLICK` expects QWERTY navigation (next/previous letter). The visual rendering code in [`FlickKeyboardView.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/FlickKeyboardView.kt) treats them identically, but [`AppCompatButtonExtension.kt`](https://github.com/kazumaproject/japanesekeyboard/blob/main/AppCompatButtonExtension.kt) selects different character sets for each.

### When should I use PETAL_FLICK instead of CIRCULAR_FLICK?

Choose `PETAL_FLICK` when you need a **visual cue for hierarchical selection** or when the key triggers a secondary popup layer (e.g., emoji categories that expand into specific glyphs). While `CIRCULAR_FLICK` offers more directions (eight vs. four), `PETAL_FLICK` signals to the user that the four visible options are entry points into sub-menus rather than direct character substitutions.