# taodo2291/xgesture_flutter architecture

> Architecture diagram of the GitHub repository taodo2291/xgesture_flutter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/taodo2291/xgesture_flutter
- Repository: https://github.com/taodo2291/xgesture_flutter

## Overview

##### Project type and purpose
- This is a Flutter plugin / package (“gesture_x_detector”) that provides a customizable gesture‐detector widget for Flutter apps.
- It includes:
- The core Dart library in lib/ (the XGestureDetector widget and related event classes)
- Unit tests in test/
- An example Flutter app under example/ (with separate Android and iOS native shells and a Dart “canvas_playground.dart” demo).

##### File structure
- Top level:
- pubspec.yaml / pubspec.lock – package metadata and dependencies
- lib/gesture_x_detector.dart – main library entry point
- test/gesture_x_detector_test.dart – unit tests for core logic
- example/ – full Flutter example project, with android/ and ios/ native projects plus example/lib for Dart usage demos
- Patterns:
- A typical Flutter plugin/package layout
- The example folder mirrors a real Flutter app build, showing integration points
- No server or backend—everything runs in the Flutter engine on the device or simulator

##### Key insights from README
- The package exposes one main widget (XGestureDetector) that wraps any child widget and dispatches gesture callbacks: taps, double taps, scales, long-press, move, scroll.
- Configuration options allow customizing timing thresholds and bypass behaviors.
- Example code demonstrates how pointer events flow through Flutter to XGestureDetector and into client callbacks.

##### Components
a. Main components
1. Flutter Application Layer (example/lib)
- MaterialApp → XGestureExample → XGestureDetector widget
2. XGestureDetector Plugin Layer (lib/)
- PointerEventListener → GestureStateMachine → Event classes (TapEvent, MoveEvent, ScaleEvent, ScrollEvent)
3. Flutter Engine / Rendering Pipeline
- GestureBinding / GestureArena
- Platform channels (if any native integration; here none)
4. Unit Tests (test/)
- gesture_x_detector_test.dart targets the GestureStateMachine logic
5. Native App Shells (example/android & example/ios)
- AndroidManifest, MainActivity.kt, Gradle config
- iOS AppDelegate.swift, Xcode project

b. Relationships & interactions
- User touches screen → Flutter Engine captures raw PointerEvents
- GestureBinding routes to widgets; XGestureDetector’s RenderObject listens
- XGestureDetector feeds events into its internal GestureStateMachine
- State machine tracks tap‐vs‐double‐tap timing, long‐press, move thresholds
- On state transitions, plugin emits high‐level callbacks to the Flutter widget tree
- Example app’s stateful widget receives callbacks and updates UI
- Unit tests simulate pointer events against the state machine

c. Architectural patterns / design principles
- Separation of Concerns:
- Core detection logic isolated in lib/
- Presentation and example usage in example/lib
- State Machine for gesture detection
- Stateless plugin surface + stateful internal logic
- Test-driven approach: core behaviors covered in unit tests

d. Technologies & libraries
- Flutter framework (GestureBinding, Widget tree, Dart)
- Dart language for plugin, examples, tests
- Android Studio / Gradle for Android shell
- Xcode / CocoaPods for iOS shell

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External user
    UserTouch((User Touch)):::external

    %% Flutter Core Layer
    subgraph "Flutter Core / Engine"
        FlutterEngine["Flutter Engine"]:::core
        GestureBinding["GestureBinding / GestureArena"]:::core
    end

    %% Plugin Layer
    subgraph "XGestureDetector Plugin Layer"
        XGestureDetectorWidget(("XGestureDetector Widget")):::plugin
        GestureStateMachine["GestureStateMachine"]:::plugin
        EventClasses["Event Classes<br/>(Tap, Move,<br/>Scale, Scroll)"]:::plugin
    end

    %% Example App Layer
    subgraph "Example App Layer"
        AppUI(("Example App UI")):::example
        CanvasDemo(("Canvas Playground Demo")):::example
    end

    %% Native Shells
    subgraph "Native App Shells"
        subgraph "Android Shell"
            MainActivity["MainActivity.kt"]:::native
            AndroidManifest["AndroidManifest.xml"]:::native
            Gradle["build.gradle"]:::native
        end
        subgraph "iOS Shell"
            AppDelegate["AppDelegate.swift"]:::native
            XcodeProj["Runner.xcodeproj"]:::native
        end
    end

    %% Unit Tests
    subgraph "Unit Test Suite"
        UnitTest["gesture_x_detector_test.dart"]:::test
    end

    %% Metadata
    PubspecRoot["pubspec.yaml"]:::metadata
    PubspecExample["example/pubspec.yaml"]:::metadata

    %% Connections
    UserTouch -->|"raw PointerEvent"| FlutterEngine
    FlutterEngine -->|"routes event"| GestureBinding
    GestureBinding -->|"listens"| XGestureDetectorWidget
    XGestureDetectorWidget -->|"feeds"| GestureStateMachine
    GestureStateMachine -->|"uses"| EventClasses
    GestureStateMachine -->|"emits callbacks"| AppUI
    GestureStateMachine -->|"emits callbacks"| CanvasDemo
    UnitTest -->|"simulates events"| GestureStateMachine
    PubspecRoot -.->|"defines package"| XGestureDetectorWidget
    PubspecExample -.->|"defines example deps"| AppUI

    %% Click Events
    click AppUI "https://github.com/taodo2291/xgesture_flutter/blob/master/example/lib/main.dart"
    click CanvasDemo "https://github.com/taodo2291/xgesture_flutter/blob/master/example/lib/canvas_playground.dart"
    click XGestureDetectorWidget "https://github.com/taodo2291/xgesture_flutter/blob/master/lib/gesture_x_detector.dart"
    click UnitTest "https://github.com/taodo2291/xgesture_flutter/blob/master/test/gesture_x_detector_test.dart"
    click MainActivity "https://github.com/taodo2291/xgesture_flutter/blob/master/example/android/app/src/main/kotlin/com/example/examples/MainActivity.kt"
    click AndroidManifest "https://github.com/taodo2291/xgesture_flutter/blob/master/example/android/app/src/main/AndroidManifest.xml"
    click Gradle "https://github.com/taodo2291/xgesture_flutter/blob/master/example/android/app/build.gradle"
    click AppDelegate "https://github.com/taodo2291/xgesture_flutter/blob/master/example/ios/Runner/AppDelegate.swift"
    click XcodeProj "https://github.com/taodo2291/xgesture_flutter/blob/master/example/ios/Runner.xcodeproj/project.pbxproj"
    click PubspecRoot "https://github.com/taodo2291/xgesture_flutter/blob/master/pubspec.yaml"
    click PubspecExample "https://github.com/taodo2291/xgesture_flutter/blob/master/example/pubspec.yaml"

    %% Styles
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px
    classDef plugin fill:#90ee90,stroke:#333,stroke-width:1px
    classDef example fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef native fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef test fill:#d3d3d3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef metadata fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef external fill:#ffffff,stroke:#333,stroke-width:1px
```
