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

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, 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.

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 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 (lines 94‑108):

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. For example:

// 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 (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 (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 (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:

// 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:

// 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.

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

Define the keyType property in your layout definition within 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 treats them identically, but 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}