Metadata-Version: 2.4
Name: rofimoji
Version: 6.8.0
Summary: Simple character picker using rofi
Project-URL: homepage, https://github.com/fdw/rofimoji
Project-URL: repository, https://github.com/fdw/rofimoji
Author-email: Fabian Winter <5821180+fdw@users.noreply.github.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: configargparse<2.0,>=1.3
Description-Content-Type: text/markdown

# Rofimoji: A character picker for rofi
Do you want to use one of those fancy emojis? Or one of those other interesting characters Unicode offers? But you haven't found a good picker yet?

Fear no more, `rofimoji` invokes the power of [rofi](https://github.com/DaveDavenport/rofi/) (and [other dmenu-derivatives](#supported-selectors)) to give you exactly the picker you always wanted.

## Main features
- Insert the select character directly, or copy it to the clipboard.
- Characters (and especially emojis) are fuzzy-searchable with keywords.
- [It remembers the ones you use most and presents them first.](#most-recently-used-characters)
- Emojis by default, but you can have any Unicode block you want - you can even [use your own](#custom-character-files-and-descriptions)!

## How does it look?
### Default
![Screenshot of rofimoji](screenshot.png?raw=true)

### With a [grid theme](#rofi-theming)
![Screenshot of rofimoji with a grid theme](screenshot-grid.png?raw=true)


# Usage
## Standalone
Call `rofimoji` as a standalone tool.

1. Run `rofimoji`
2. Search for the character you want
3. (optional) Select multiple emoji with `shift+enter`
4. Hit `enter` to for the default action or use one of the [shortcuts](#actions) to do something else.\
   `alt+1` directly chooses the most most recently used character (`alt+2` for the second most recently one etc.)
5. Maybe select a skin color
6. 🦾

## As a rofi mode
Integrate `rofimoji` as just another rofi mode.

1. Call rofi with `rofi -modi "emoji:rofimoji" -show emoji`
2. Search for the character you want
3. Hit `enter` to execute your default action; \
   `Alt+Shift+1` for copying to the clipboard \
   `Alt+Shift+3` for the "[clipboard](#insertion-method)" insertion method \
   `alt+1` inserts the most recently used character (`alt+2` for the second most recently one etc.)
4. Maybe select a skin color
5. 🐉

### Caveats when running `rofimoji` as a rofi mode
There are some limitations to this approach, though:
Running as rofi mode has several drawbacks that cannot be changed:
- Because `rofi` is the main process, `rofimoji` cannot directly type to any window. Only copying the character works, so set the `--action` accordingly.
- You can only select one character at a time.
- The custom keyboard shortcuts are still there, but mapped to `Alt+Shift+1` (on a Qwerty keyboard) etc.

The configuration still works as described. You can have several modes in a `combi` for different character sets, for example, or set a default action and skin tone.

# Configuration
You can configure `rofimoji` either with cli arguments or with a config file called `$XDG_CONFIG_HOME/rofimoji.rc`. For the file, use the long option names without double dashes.

## Options

| long option                                                                                                                                            | short option | possible values                                                                                                | default value                                        | description                                                                                                                                                                                                                                                                                                         |
|--------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|----------------------------------------------------------------------------------------------------------------|------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--action`                                                                                                                                             | `-a`         | `type`, `copy`, `clipboard`, `type-numerical`, `unicode`, `copy-unicode`, `print`, `menu`                      | `type`                                               | Choose what `rofimoji` should do with the selected characters. See [Actions](#actions) below for details.                                                                                                                                                                                                           |
| `--files`                                                                                                                                              | `-f`         | `all`, `<yourfile>` or [any of the files in `data`](https://github.com/fdw/rofimoji/tree/main/src/picker/data) | `emojis`                                             | Define which file(s) to load characters from. A file name without extension (f.e. `emojis_smileys_emotion`) is enough for the distributed ones or any in `${XDG_DATA_HOME}/rofimoji/data`. Globbing with `*` is possible.<br/>`all` is a shortcut for all default files at once. Use with caution, that is a *lot*. |
| `--skin-tone`                                                                                                                                          | `-s`         | `light`, `medium-light`, `moderate`, `dark brown`, `black`, as well as `neutral` and `ask`                     | `ask`                                                | Define the skin tone of supporting emojis. `ask` will always ask the user.                                                                                                                                                                                                                                          |
| `--max-recent`                                                                                                                                         |              | 0-10                                                                                                           | 10                                                   | Show at most this many recently picked characters. The number will be capped at 10. Set to `0` to disable the whole feature.                                                                                                                                                                                        |
| `--no-frecency`<br/>(`no-frecency=True` in the config file)                                                                                            |              | -                                                                                                              | `<false>`                                            | By default, `rofimoji` shows frequently used items first. With this option, they're shown in the order of the file.                                                                                                                                                                                                 |
| `--hidden-descriptions`<br/>(`hidden-descriptions=True` in the config file)                                                                            |              | -                                                                                                              | `<false>`                                            | Only list the characters, but not their description. This is useful for [grid themes](#rofi-theming) in `rofi`. Note that they're still searchable, even though the description is not shown. Not used with other selectors.                                                                                        |
| `--use-icons`                                                                                                                                          |              |                                                                                                                | `false`                                              | Show characters as icons in `rofi`. Not used for other selectors.                                                                                                                                                                                                                                                   |
| `--prompt`                                                                                                                                             | `-r`         | any string                                                                                                     | `😀 `                                                | Define the prompt text for `rofimoji`.                                                                                                                                                                                                                                                                              |
| `--selector-args`                                                                                                                                      |              |                                                                                                                |                                                      | Define arguments that `rofimoji` will pass through to the selector.<br/>Please note that you need to specify it as `--selector-args="<selector-args>"` or `--selector-args " <selector-args>"` because of a [bug in argparse](https://bugs.python.org/issue9334)                                                    |
| `--selector`                                                                                                                                           |              | `rofi`, `wofi`, `fuzzel`, `dmenu`, `tofi`, `bemenu`, `wmenu`, `choose`, `hyprlauncher`                         | (automatically chosen)                               | Show the selection dialog with this application.                                                                                                                                                                                                                                                                    |
| `--clipboarder`                                                                                                                                        |              | `xsel`, `xclip`, `wl-copy`, `pbcopy`                                                                           | (automatically chosen)                               | Access the clipboard with this application.                                                                                                                                                                                                                                                                         |
| `--typer`                                                                                                                                              |              | `xdotool`, `wtype`, `ydotool`, `cliclick`, `wl-ime-type`                                                       | (automatically chosen)                               | Type the characters using this application.                                                                                                                                                                                                                                                                         |
| `--keybinding-copy`, `--keybinding-type`, `--keybinding-clipboard`, `--keybinding-type-numerical`, `--keybinding-unicode`, `--keybinding-copy-unicode` |              |                                                                                                                | `Alt+c`, `Alt+t`, `Alt+p`, `Alt+n`, `Alt+u`, `Alt+i` | Choose different keybindings than the default values.                                                                                                                                                                                                                                                               |

## Example config file
`~/.config/rofimoji.rc`:
```
action = copy
files = [emojis, math]
skin-tone = moderate
```

## Actions

The `--action` (`-a`) option defines what action will be taken when a character is selected. Multiple actions can be specified with a space character in between (for example: `-a type copy`).
The options are:

| name             | shortcut | description                                                                                                                                    |
|------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `type`           | `alt+t`  | Directly type the characters into the last active window. This is the *default*                                                                |
| `copy`           | `alt+c`  | Copy them to the clipboard.                                                                                                                    |
| `clipboard`      | `alt+p`  | Insert the selected characters through pasting from the clipboard, instead of directly typing them. See [Insertion Method](#insertion-method). |
| `type-numerical` | `alt+n`  | Directly type the emoji(s) by using their Unicode codepoints; this simulates Ctrl+Shift+U<codepoint> on the keyboard                           |
| `unicode`        | `alt+u`  | Type the unicode codepoints of the selected characters.                                                                                        |
| `copy-unicode`   | `alt+i`  | Copy the codepoints to clipboard.                                                                                                              |
| `print`          |          | Print the chosen characters to `stdout`.                                                                                                       |

## Insertion method
By default, `rofimoji` types the characters using either `xdotool`, `wtype`, `ydotool`, or `wl-ime-type` (see [display server support](#display-server-support)). You can enforce this behavior with `--action type` (`-a type`).

For some applications (f.e. Firefox), this does not work reliably. To work around this, `rofimoji` can copy the emojis to your clipboard and insert them from there with `shift+insert`. Afterwards, it will restore the previous contents.
Unfortunately, it depends on the receiving application whether `shift+insert` uses the clipboard or the primary selection.
Therefore, `rofimoji` uses both and also restores both.
To use this workaround, you can either use the keybinding `alt+p` or start it as `rofimoji --action clipboard` (`-a clipboard`).
If you want to have it directly typed instead, you can hit `alt+t`, even though it was started with `--action clipboard`. Note that you can [change the keybindings](#options).

Finally, with `--action copy` (or `-a copy`) you can also tell `rofimoji` to only copy the selected characters to your clipboard.

## Display server support
`rofimoji` supports both X11 and Wayland by using the correct tools for each environment (see [Supported Selectors](#supported-selectors)). It tries to automatically choose the right one for the currently running session.
If you want to manually overwrite this, have a look at the `--selector`, `--clipboarder` and `--typer` options [above](#options).

`rofimoji` also supports MacOS in a best-effort fashion (see below)

## Most recently used characters
By default, `rofimoji` will show the last ten recently used characters separately; you can insert them with `alt+1`, `alt+2` and so on. It will use the default [insertion method](#insertion-method).
If you don't want this, you can set `--max-recent` to `0`.

Additionally, `rofimoji` also remembers in general which characters are used more frequently and sorts the list accordingly. You can disable this behavior with `--no-frecency`.

## Rofi theming
By default, `rofimoji` re-uses the existing rofi configuration, but you can pass your own using `--selector-args` (for example `--selector-args="-theme ~/your-rofi-theme.rasi"`).

If you would like a more character-focused theme, you can use packaged [`grid.rasi`](https://github.com/fdw/rofimoji/blob/main/src/picker/contrib/grid.rasi) together with the `--hidden-descriptions` parameter. This theme still imports the existing `rofi` configuration but moves the entries into a grid. Of course, you can base your own theme on this. (If you have improvements, please open a PR!)
To use the arrow keys in `rofi` only for the grid and not the query, pass these `-selector-args`: `-kb-row-left Left -kb-row-right Right -kb-move-char-back Control+b -kb-move-char-forward Control+f`.

![Screenshot of rofimoji with a grid theme](screenshot-grid.png?raw=true)

# Supported characters
- [Unicode emojis](https://home.unicode.org/emoji/about-emoji/) with the official descriptions and tags. Also supports skin tones and gender variants.
- All other [Unicode](https://home.unicode.org/) characters, split into the official blocks
- CJK character sets from Unicode
- [Font Awesome 6](https://fontawesome.com/)
- [Nerd Fonts](https://www.nerdfonts.com/)
- [Gitmoji](https://gitmoji.dev/)
- Kaomoji, from [w33ble](https://github.com/w33ble/emoticon-data)
- [HTML Named Character References](https://html.spec.whatwg.org/multipage/named-characters.html)

If you miss something, please open an issue!

## Custom character files and descriptions
### New character sets
If the predefined character sets are not enough, you can define additional ones yourself and load them with `-f` (see [options](#options)). They can lie wherever you want, as you need to pass the full path to `rofimoji`.
In each line, one 'character' can be defined, followed by a single space character (` `). After that, you can write whatever description you want.

For example, if you want a small set for your most often used characters, you can use a new file with the following content:

```
🎷 sax, saxophone, jazz
🎻 violin, strings, classical
🎸 guitar, electric guitar, rock
🥁 drums, percussion
```

If the character is also in another selected file, all descriptions will be combined. If you give it the same name as one of those included with `rofimoji`, yours will be preferred. This means you can effectively "replace" the built-in sets.

If you think your file is useful to others, please open a PR to include it in a future version of `rofimoji`.

### Additional descriptions
For added comfort, `rofimoji` will automatically load an "additional" file for predefined ones. This file needs to called `<filename>.additional.csv` and lie in `${XDG_DATA_HOME}/rofimoji/data/`. For example, if you want to extend `emojis_smileys_emotion`, call the file `emojis_smileys_emotions.additional.csv`.
This is helpful if you want additional descriptions: You can define such an additional character file, add the character and your description and your descriptions will now also be shown. You can add localized descriptions, for example: `😊 glücklich` adds a German description to the emoji.

# Installation
## From distribution repositories
[![Packaging status](https://repology.org/badge/vertical-allrepos/rofimoji.svg)](https://repology.org/project/rofimoji/versions)

## From PyPI
`rofimoji` is on [PyPI](https://pypi.org/project/rofimoji/). You can install it with `pipx install rofimoji` (or `sudo pipx install rofimoji`).

## From Github
Download the wheel file of the [latest release](https://github.com/fdw/rofimoji/releases/) and install it with  `sudo pip install $filename` (or you can use `pip install --user $filename` to only install it for the local user).
Afterwards, there should be a `rofimoji` on your `$PATH`.
This also installs the python dependency `configargparse`.

## Dependencies
What else do you need:
- Python 3.8 or higher
- A font that can display your scripts, (for emojis, [EmojiOne](https://github.com/emojione/emojione) or [Noto Emoji](https://www.google.com/get/noto/) work)
- Optionally, a tool to programmatically type characters into applications. Either `xdotool` for X11 or `wtype`/`ydotool`/`wl-ime-type` for Wayland
- Optionally, a tool to copy the characters to the clipboard. `xsel` and `xclip` work on X11; `wl-copy` on Wayland

### Supported Selectors
Please note that several advanced features are only supported by `rofi` (both on X and Wayland):
- custom keyboard shortcuts
- `--use-icons` and `--hidden-descriptions`, and thus a grid theme
- multiple selections
- recently used characters
 
All other selectors can be used for the basic functionality.

#### X.org
- [rofi](https://github.com/davatorium/rofi)
- [bemenu](https://github.com/Cloudef/bemenu)
- [dmenu](https://tools.suckless.org/dmenu/)

#### Wayland
- also [rofi](https://github.com/davatorium/rofi)
- [wofi](https://hg.sr.ht/~scoopta/wofi)
- [fuzzel](https://codeberg.org/dnkl/fuzzel)
- [tofi](https://github.com/philj56/tofi)
- [bemenu](https://github.com/Cloudef/bemenu)
- [wmenu](https://git.sr.ht/~adnano/wmenu)

#### MacOS
- [choose](https://github.com/chipsenkbeil/choose)

### MacOS support

A light support of MacOS was brought to `rofimoji` through:
- `pbcopy` / `pbpaste` to manage the clipboard
- `choose` as selector alternative to `rofi`
- `cliclick` as typer alternative to `xdotool`

Support is for now limited and `type`, `type-numerical` and `unicode` are not supported yet.
