msgProc: Gestures

Mouse gestures let users trigger actions by drawing shapes with the right mouse button. Drag left to go back, drag right to go forward. When recognized, msgProc receives MSG_GESTURE events with pattern details for building browser-style navigation shortcuts.

How Gestures Work

The gesture system tracks right-button drag motions and converts them into directional patterns:

1. User presses and holds the right mouse button
2. User drags in a pattern (left, right, L-shape, etc.)
3. User releases the right mouse button
4. System analyzes the path and matches it against registered patterns
5. If matched, MSG_GESTURE is sent to msgProc

Mouse Gesture (MSG_GESTURE)

MSG_GESTURE fires when a registered gesture pattern is recognized after the user completes a right-button drag motion. The event contains detailed information about the gesture including the pattern name, direction sequence, timing, and bounding box. Use this to implement browser-style navigation shortcuts, custom actions, or context-sensitive commands.

Message Parameters

Detail Properties

Example: Simple Navigation

msgProc(event) {
    if (event.message === wakaPAC.MSG_GESTURE) {
        switch(event.detail.pattern) {
            case 'left':
                this.navigateBack();
                return false;

            case 'right':
                this.navigateForward();
                return false;

            case 'up':
                this.scrollToTop();
                return false;

            case 'down':
                this.scrollToBottom();
                return false;
        }
    }
}

Built-in Gesture Patterns

WakaPAC includes common single-direction and L-shape patterns:

Custom Gesture Registration

Register your own gesture patterns using direction codes. Custom gestures must be registered before initializing WakaPAC.

Direction Codes

Example: Register Custom Patterns

// Register before initializing WakaPAC
wakaPAC.registerGesture('refresh', ['U', 'D']);        // Up then down
wakaPAC.registerGesture('undo', ['L', 'R']);           // Left then right
wakaPAC.registerGesture('zigzag', ['R', 'L', 'R']);    // Right-left-right

wakaPAC('#app', { /* ... */ });

Example: Handle Custom Gestures

msgProc(event) {
    if (event.message === wakaPAC.MSG_GESTURE) {
        switch(event.detail.pattern) {
            case 'refresh':
                this.reload();
                return false;

            case 'undo':
                this.cancelOperation();
                return false;

            case 'zigzag':
                this.closePanel();
                return false;
        }
    }
}

Unregister Gestures

wakaPAC.unregisterGesture('refresh');

Gesture Configuration

Gestures have built-in constraints for reliable recognition:

Gesture Recognition Details

How Direction Segments Are Detected

1. System tracks mouse position at regular intervals during right-drag
2. When movement distance exceeds 30 pixels, direction is calculated
3. If new direction differs from previous by more than 45°, a new segment begins
4. Segments are recorded as 'L', 'R', 'U', or 'D' based on dominant axis
5. On mouse release, the sequence is matched against registered patterns

Diagonal Movement

Diagonal movements are resolved to the dominant axis (horizontal or vertical):

• Movement within 45° of horizontal → 'L' or 'R'
• Movement within 45° of vertical → 'U' or 'D'

Pattern Matching

After mouse release, the recorded direction sequence is compared against all registered patterns. The first exact match fires MSG_GESTURE with that pattern name.

Gesture and Context Menu Interaction

Gestures and right-clicks are separate actions. A stationary right-click fires MSG_RCLICK, which you can use to show a context menu. A right-button drag that matches a registered pattern fires MSG_GESTURE, which you can use for navigation shortcuts. This lets you support both context menus and gesture shortcuts without conflict.

Event Sequence

Stationary right-click:
1. MSG_RBUTTONDOWN → User presses right button
2. MSG_RBUTTONUP   → User releases right button
3. MSG_RCLICK      → Right-click event fires

Right-button drag (gesture):
1. MSG_RBUTTONDOWN          → User presses right button
2. MSG_MOUSEMOVE (multiple) → User drags
3. MSG_RBUTTONUP            → User releases right button
4. MSG_GESTURE              → Gesture pattern recognized (if registered)

Example: Gestures + Context Menu

msgProc(event) {
    // Handle gestures for navigation shortcuts
    if (event.message === wakaPAC.MSG_GESTURE) {
        switch(event.detail.pattern) {
            case 'left':
                this.navigateBack();
                return false;

            case 'right':
                this.navigateForward();
                return false;
        }
    }

    // Handle stationary right-click for context menu
    if (event.message === wakaPAC.MSG_RCLICK) {
        const pos = wakaPAC.MAKEPOINTS(event.lParam);
        this.showContextMenu(pos.x, pos.y);
        return false;
    }
}

Best Practices

• Keep patterns simple: One or two segments (L, R, U, D) work best. Complex patterns are hard to remember and draw accurately
• Return false: Always return false when handling gestures to stop event processing
• Use alongside MSG_RCLICK: Gestures handle shortcuts while stationary right-clicks handle context menus — they're separate actions
• Test on different devices: Gestures work great with mouse, less reliable with trackpads
• Provide visual feedback: Consider drawing the gesture path or showing recognized pattern
• Don't rely solely on gestures: Provide alternative ways to trigger actions (buttons, keyboard shortcuts)
• Limit pattern count: 4-6 gestures maximum to avoid overwhelming users
• Use familiar patterns: Borrow from browser conventions (right = forward, left = back)