Metadata-Version: 2.4
Name: mojify
Version: 0.4.0
Summary: A Wayland-native emoji picker for Ubuntu/GNOME — search, select, paste.
Author-email: Piyush Doorwar <piyushdoorwar+mojify@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/piyushdoorwar/mojify
Project-URL: Repository, https://github.com/piyushdoorwar/mojify
Project-URL: Issues, https://github.com/piyushdoorwar/mojify/issues
Keywords: emoji,picker,wayland,ubuntu,gnome,gtk,clipboard
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: GTK
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/piyushdoorwar/mojify/main/assets/logo.png" alt="mojify logo" width="128" height="128">
</p>

<h1 align="center">mojify</h1>

**A Wayland-native emoji picker for Ubuntu/GNOME.**

Press a shortcut, type to search, hit Enter — the emoji is copied to your
clipboard. Paste it anywhere with `Ctrl + V`.

```
pip install mojify
```

---

## Why it exists

GNOME's built-in emoji picker only works inside GTK apps, and most
third-party pickers (rofi-emoji, etc.) rely on `xdotool` / `ydotool` to *type*
the emoji — which **does not work on Wayland** because Wayland blocks programs
from synthesizing keystrokes into other apps for security reasons.

**mojify takes the Wayland-friendly route:** it copies the emoji to your
clipboard and lets you paste it yourself with `Ctrl + V`. That works in *every*
application — your terminal, browser, editor, chat app, anywhere — with no
input-injection hacks.

It's built on **GTK3 (PyGObject)**, which already ships with Ubuntu's GNOME
desktop, so the only thing you need to add is the clipboard helper.

---

## Install

```bash
pip install mojify
```

### Required dependency: `wl-clipboard`

mojify uses `wl-copy` to put the emoji on your clipboard:

```bash
sudo apt install wl-clipboard
```

> GTK3 / PyGObject already come with Ubuntu's GNOME desktop. If you're on a
> stripped-down system and the picker won't start, install them with:
> `sudo apt install python3-gi gir1.2-gtk-3.0`

---

## Usage

Launch the picker directly:

```bash
mojify
```

Other commands:

```bash
mojify --version    # print the version
mojify --list       # print every bundled emoji (char<TAB>name<TAB>keywords)
mojify --stdout     # print the chosen emoji to stdout instead of copying
mojify --no-notify  # skip the "Copied" desktop notification
```

`--list` is handy for scripting, e.g. piping into your own fuzzy finder:

```bash
mojify --list | fzf | cut -f1 | wl-copy
```

---

## Set up the `Super + .` keyboard shortcut (GNOME)

The whole point is to summon mojify with one keystroke. Bind it as a custom
shortcut:

1. Open **Settings → Keyboard → View and Customize Shortcuts**.
2. Scroll to the bottom and click **Custom Shortcuts**, then the **+** button.
3. Fill in:
   - **Name:** `mojify`
   - **Command:** `mojify`
     *(if that doesn't work, use the absolute path — run `which mojify` to find it, e.g. `/home/you/.local/bin/mojify`)*
   - **Shortcut:** press `Super + .`
4. Click **Add**.

Now press `Super + .` anywhere and the picker pops up.

> **Note:** `Super` is the Windows/⌘ key. If GNOME says the shortcut is
> already in use, pick another combo (e.g. `Super + E`) — the steps are the
> same.

> **Tip:** if you installed with `pip install --user`, make sure
> `~/.local/bin` is on your `PATH`, or just use the absolute path in the
> command field.

---

## Show mojify in the app grid / dock (optional)

To register mojify as a desktop app (with its icon) so it appears in the GNOME
app grid, search, and dock — and can be pinned:

```bash
mojify --install-desktop      # installs a .desktop file + icon
mojify --uninstall-desktop    # removes them
```

You may need to log out/in for the icon to refresh. Note the picker itself is a
borderless pop-up, so it intentionally has no titlebar icon.

## How it works

1. Press your shortcut (e.g. `Super + .`).
2. A small floating search window appears in the center of the screen,
   always on top, with no titlebar.
3. Browse by **category tab** — starting with a **🕒 Recent** tab of your
   most-used emojis — or just start typing to **search by name or keyword**
   (`fire`, `smile`, `heart`, `rocket`, …). Search spans every category and
   updates in real time.
4. Use **arrow keys** to move through the grid, or click with the mouse.
5. Press **Enter** (or click) to select. The emoji is copied to your
   clipboard and the window closes instantly.
6. Press **`Ctrl + V`** wherever you want the emoji.
7. Press **Escape** at any time to dismiss the picker without selecting.

---

## Known limitation

**You have to paste manually with `Ctrl + V`.** mojify cannot type the emoji
into the focused app for you, because Wayland deliberately prevents
applications from injecting keystrokes into other windows. Copy-to-clipboard
is the robust, secure way to do this on Wayland — and it works everywhere.

---

## Project layout

```
mojify/
├── mojify/
│   ├── __init__.py
│   ├── __main__.py     # CLI entry point (python -m mojify / `mojify`)
│   ├── picker.py       # GTK3 floating picker window
│   └── emojis.py       # bundled emoji dataset + search
├── setup.py
├── pyproject.toml
├── README.md
└── LICENSE
```

---

## Contributing

Contributions are very welcome! 🎉

1. **Fork** the repo and create a feature branch.
2. Make your change. The codebase is small and dependency-light:
   - **Adding emojis?** Edit [`mojify/emojis.py`](mojify/emojis.py). Each entry
     is a `(character, name, keywords)` tuple. Add generous keywords —
     they're what make search forgiving.
   - **UI tweaks?** They live in [`mojify/picker.py`](mojify/picker.py).
3. Test locally with an editable install:
   ```bash
   pip install -e .
   mojify
   ```
4. Open a pull request describing the change.

Please keep the zero-heavy-dependency philosophy: GTK3 (already on Ubuntu) for
the UI and `wl-clipboard` for the clipboard — nothing more.

---

## License

[MIT](LICENSE) © 2026 Piyush Doorwar
