Skip to content

About

iOS port of MessageEase gesture-based keyboard

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

MessageEase Keyboard for iOS

A native iOS implementation of the MessageEase keyboard layout, ported from messagease-better.

About MessageEase

MessageEase is an ergonomic, gesture-based keyboard layout designed specifically for touchscreens. Instead of the traditional QWERTY layout, MessageEase uses:

  • 9 core letters (a, n, i, h, o, r, t, e, s) accessible by tapping the center of keys
  • Other letters accessible by swiping in 8 directions from those keys
  • Efficient text entry with minimal finger movement
  • Optimized for one-handed use on mobile devices

Features

  • ✅ Full MessageEase keyboard layout with all standard English letters
  • ✅ Numbers and symbols support
  • ✅ Multi-touch gesture recognition (tap + 8-way swipe)
  • ✅ Number mode toggle
  • ✅ Caps lock and shift support
  • ✅ Word-based cursor movement
  • ✅ Native iOS keyboard extension
  • ✅ Dark mode support

Project Structure

MessageEaseKeyboard/
├── MessageEaseKeyboard/           # Main app (container)
├── MessageEaseKeyboardExtension/   # Keyboard extension
│   ├── Models/
│   │   ├── Motion.swift           # Gesture direction enum
│   │   ├── Line.swift             # Gesture detection logic
│   │   ├── CapsMode.swift         # Capitalization modes
│   │   ├── KeyAction.swift        # Key action protocols
│   │   └── KeyboardLayout.swift   # Complete keyboard layout
│   ├── Views/
│   │   └── KeyboardView.swift     # Main keyboard view
│   ├── KeyboardViewController.swift
│   └── Info.plist
└── README.md

Setup Instructions

Prerequisites

  • macOS with Xcode 15.0 or later
  • iOS 16.0+ (for deployment)
  • An Apple Developer account (for testing on physical devices)

Step 1: Create the Xcode Project

  1. Open Xcode

  2. Create a new project:

    • File → New → Project
    • Choose "iOS" → "App"
    • Click "Next"
  3. Configure the project:

    • Product Name: MessageEaseKeyboard
    • Team: Select your development team
    • Organization Identifier: com.yourname (or your preference)
    • Interface: Storyboard
    • Language: Swift
    • Click "Next" and choose the MessageEaseKeyboard folder as the location
    • Important: Uncheck "Create Git repository" (we already have one)

Step 2: Add the Keyboard Extension Target

  1. Add a new target:

    • File → New → Target
    • Choose "iOS" → "Custom Keyboard Extension"
    • Click "Next"
  2. Configure the extension:

    • Product Name: MessageEaseKeyboardExtension
    • Make sure it's added to the main app target
    • Click "Finish"
    • When prompted about activating the scheme, click "Activate"
  3. Delete the default KeyboardViewController.swift created by Xcode (we have our own)

Step 3: Add Source Files to the Project

  1. Add the Models folder:

    • Right-click on MessageEaseKeyboardExtension in the Project Navigator
    • Select "Add Files to MessageEaseKeyboard..."
    • Navigate to MessageEaseKeyboardExtension/Models
    • Select the entire Models folder
    • Make sure "Create groups" is selected
    • Make sure only MessageEaseKeyboardExtension target is checked
    • Click "Add"
  2. Add the Views folder:

    • Repeat the above process for the Views folder
  3. Add KeyboardViewController.swift:

    • Right-click on MessageEaseKeyboardExtension
    • Select "Add Files to MessageEaseKeyboard..."
    • Select KeyboardViewController.swift
    • Click "Add"
  4. Replace the Info.plist:

    • In Xcode, select the MessageEaseKeyboardExtension group
    • Delete the existing Info.plist if prompted
    • Add the Info.plist we created

Step 4: Configure Build Settings

  1. Select the project in Project Navigator

  2. Select the MessageEaseKeyboardExtension target

  3. Set deployment target:

    • General tab → Deployment Info
    • Set "iOS Deployment Target" to 16.0 or higher
  4. Configure signing:

    • Signing & Capabilities tab
    • Enable "Automatically manage signing"
    • Select your Team

Step 5: Build and Run

  1. Select a simulator or device:

    • Choose iPhone 15 Pro (or your preferred simulator)
    • Or connect a physical iOS device
  2. Build the project:

    • Product → Build (⌘B)
    • Fix any errors if they appear
  3. Run the app:

    • Product → Run (⌘R)
    • The container app will launch (it will be blank - this is normal)

Step 6: Enable the Keyboard on iOS

  1. On the iOS device/simulator:

    • Go to Settings → General → Keyboard → Keyboards
    • Tap "Add New Keyboard..."
    • Find "MessageEase" in the list
    • Tap it to add
  2. Test the keyboard:

    • Open any app with a text field (Notes, Messages, Safari, etc.)
    • Tap in a text field
    • Tap the globe icon (🌐) on the system keyboard to switch keyboards
    • Select "MessageEase"

How to Use MessageEase

Basic Typing

  • Tap the center of a key to type the main letter (a, n, i, h, o, r, t, e, s)
  • Swipe in any of 8 directions to type other letters

Key Layout

First Row:
┌─────────┬─────────┬─────────┬─────────┐
│    A    │    N    │    I    │         │
│  v - $ │ l ! + / │  x ? = €│         │
└─────────┴─────────┴─────────┴─────────┘

Second Row:
┌─────────┬─────────┬─────────┬─────────┐
│    H    │    O    │    R    │  MODE   │
│  k ( [ │q u p b j│ ↑ m @ | │ 123/ABC │
│    { _ │  c g d  │ ↓ ) ] } │         │
└─────────┴─────────┴─────────┴─────────┘

Third Row:
┌─────────┬─────────┬─────────┬─────────┐
│    T    │    E    │    S    │   DEL   │
│  y * < │  w z . │  f & ° │   ←     │
│  ~ – — │  " ' : ,│  # ; > │         │
└─────────┴─────────┴─────────┴─────────┘

Fourth Row:
┌────────────────────────────────┬─────────┐
│           SPACE                │ RETURN  │
│       ← (swipe) →             │         │
└────────────────────────────────┴─────────┘

Special Features

  • Shift: Swipe UP on the 'R' key
  • Caps Lock: Swipe DOWN on the 'R' key
  • Number Mode: Tap the MODE key (shows 1-9 on main keys)
  • Space: Tap the spacebar
  • Move Cursor: Swipe LEFT/RIGHT on the spacebar
  • Delete: Tap backspace key
  • Delete Word: Swipe UP-LEFT or UP-RIGHT on backspace
  • Voice Input: Swipe UP on backspace
  • Dismiss Keyboard: Swipe DOWN on backspace

Function Key Swipes (MODE key):

  • ↑ Compose mode (for accented characters)
  • ↖ Select all
  • ↗ Copy
  • ↘ Paste
  • ↓ Emoji picker (to be implemented)
  • ↙ Cut
  • ← Jump to start of word
  • → Jump to end of word

Testing with TestFlight (Optional)

To test on external devices:

  1. Archive the app:

    • Product → Archive
    • Wait for the archive to complete
  2. Upload to App Store Connect:

    • In Organizer, select your archive
    • Click "Distribute App"
    • Choose "App Store Connect"
    • Follow the prompts to upload
  3. Add testers in App Store Connect:

    • Go to TestFlight tab
    • Add internal or external testers
    • They'll receive an email to install via TestFlight

Known Limitations

Due to iOS keyboard extension sandboxing:

  • Clipboard operations (copy/cut) are restricted for security
  • Undo/Redo are not available through the keyboard API
  • Select all has limited implementation
  • Emoji picker needs additional implementation
  • Full access permission would be required for some features (consider privacy implications)

Development Notes

Gesture Detection Algorithm

The keyboard uses angle-based gesture detection:

  • Calculates angle using atan2(dy, dx)
  • Maps to 8 directions using 45° sectors (22.5° boundaries)
  • Threshold of 1/4 key size prevents accidental swipes

Architecture

  • MVVM-inspired: KeyboardView handles both view and logic
  • Protocol-based actions: Each key action conforms to Action protocol
  • Declarative layout: Complete keyboard defined in KeyboardLayout.swift
  • Multi-touch support: Tracks each touch independently

Customization

To modify the keyboard layout, edit KeyboardLayout.swift:

// Example: Change 'A' key to 'B'
.none: KeyAction("b", "1")  // was KeyAction("a", "1")

// Example: Add a new symbol
.upLeft: SecondaryKeyAction("@")

Credits

License

This project is licensed under the AGPL-3.0-or-later license, matching the original messagease-better project.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Future Enhancements

  • Emoji picker implementation
  • Compose/dead key system for accented characters
  • Haptic feedback
  • Sound effects
  • Customizable themes
  • Alternative keyboard layouts (other languages)
  • Settings panel within the keyboard
  • Long-press repeat for delete/cursor movement
  • Swipe-to-delete on keys
  • Statistics/word prediction

Support

If you encounter issues:

  1. Check that the keyboard is enabled in Settings
  2. Try deleting and re-adding the keyboard
  3. Restart the iOS device
  4. Rebuild and reinstall the app

For bugs or feature requests, please open an issue on GitHub.


Happy typing with MessageEase! 🎹✨

About

iOS port of MessageEase gesture-based keyboard

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages