EF*CK — Emoji Filter / Unicode Chat Keyboard

FAQ / Docs

Basic program operation

How do I cancel / close / exit the app?

To close EFCK, like any cancelable dialog, simply use Escape (Esc) key. See here for additional keyboard shortcuts.

What keyboard shortcuts are available?

EFCK responds to the following keyboard keys with the specified actions:

How do I use GIFs?

Rather than activate the chosen GIF with Enter key (works on X11), you can drag and drop it into the target receiver application.

The window has no titlebar / handle. How do I move / resize?

It is very modern for windows to draw their own window frames and reinvent procedures for common window actions like resizing, moving, toggling state … These are called client-side decorations and branding. Who gives a f— what the user likes on their desktop. "We gave you an app; you will submit to us, fully." Digression over.

To resize the window, you can use the size grip in the bottom right window corner.

To move the window, you can "pick it" on any background window surface (i.e. not the tabbar, not the text input field, not the main list view, but everything else).

Where are program configuration / extensions kept?

EFCK stores it's files in user's local config home folder. This location is platform dependent:

In all above cases, {APP_NAME} stands for "efck-chat-keyboard".

Custom emoji

How do I create custom emoji?

Emoji text characters are well-defined codepoints in the Unicode Standard, released by the Unicode Consortium. You can't create your own emoji in an interoperable manner, but you can propose to the Unicode Consortium that a new emoji be added to Unicode standard. Here is a list of current emoji proposals with their latest status.

You can also add custom emoji sequences and override text bindings in EFCK.

You could forge a new font with custom images you pick assigned arbitrary codepoints from the Unicode private use blocks and then make all your recipients use your font file, but that's all unlikely and not really worthwhile.

How to add custom emoji sequences / alias text bindings?

You can create custom text aliases for emoji by adding lines to emoji-custom-strings.txt file kept in your config home folder.

If the file doesn't exist, create it. The expected format is simply the emoji character or sequence (no whitespace allowed) followed by the desired text alias. E.g.:

# Comments are prefixed with '#' symbol and ignored
# Line format: emoji_sequence any_text_alias
👨🏿‍❤️‍💋‍👨🏿  gay
😂🔫  blow brains out

For more inspiration, see bundled emoji-custom-strings.txt.

What emoji fonts are available?

Most fonts work well on Android/GNU/Linux/X11/fontconfig. Presently, only the platform-shipped default fonts work on Widows and macOS.

Note again, what emoji images your recipients see depends solely on what emoji fonts are loaded on their machines, therefore one might as well just stick with platform defaults.

How do I use a custom emoji font?

By default, EFCK uses platform-default emoji font, with fallback alternatives configured as are known to be supported. You can force use of a custom emoji font family by setting environment variable ICON_FONT. E.g.:

export ICON_FONT="Twitter Color Emoji"

See instructions how to set environment variables on Linux, on macOS, and on Windosw.

Of course, the font has to be installed beforehand. See here for emoji font alternatives.

Troubleshooting and debugging

Some emoji glyphs are white / empty / placeholder / missing ...

EFCK ships with official emoji sequences for the latest Unicode Standard. And cooking new emoji sequences is all the rage these days. If you see only white empty squares, your platform emoji font (see #fonts) and any of the available fallback emoji fonts are, in fact, missing glyphs for the associated code points. What you can do is update your font to the latest version.

The keyboard never types out the selected emoji ...

Typing out the text into the previously focused window may not be supported on your platform. Typeout was tested working on Widosw, macOS, Linux/X11 (using xdotool), and Linux/Wayland (using ydotool or wtype).

If it's not working for you on one of these platforms, please submit a bug report.

Doesn't seem to work on macOS ...

Make sure you have followed macOS installation notes.

I only get some weird characters typed out ...

If instead of the expected emoji or text the program types out unexpected characters like empty rectangles or rectangles with some numbers (like one of 𪛗�۝□) or Chinese letters or strings like <ffffffff>, the issue likely lies with the receiving program. Please only raise new bug reports if you can't make it work in a quality program like Firefox or Chromium.

Generally works, but doesn't paste into some fields ...

The typeout function only works with programs that retain keyboard focus on the focused input field even as their windows are deactivated (unfocused). Therefore, it works, for instance, with most browsers' location fields, but it doesn't work with Windos' File Manager file rename operation since the rename operation is canceled once the window loses focus.

To augment the typeout function, you can force use of system clipboard in Options tab.

Debugging CLI switch and log file location

Use --debug command line switch to print debug messages on stderr and into the log file. Log file location is "$TMPDIR/efck-chat-keyboard-{timestamp}.log" where variable $TMPDIR is resolved as per the algorithm of Python's tempfile.gettempdir() function.

Reporting bugs / issues

Please report bugs on the issue tracker on GitHub. Please kindly revise contributing guidelines, in particular, see how to report bugs effectively. Thanks!

Extending the application

How do I make custom tabs?

EFCK is written in Python programming language and based on Qt widget framework, so you'll need some grasp of both. In order to write a custom tab, simply extend efck.tab.Tab class in your module file that you put in your config dir "tabs" subdirectory (create it if doesn't exist, or if the whole app config directory doesn't exist, simply run efck-chat-keyboard for the first time to create it). Any Tab-extending class will be automatically picked up by the app.

See bundled tabs for code inspiration and don't hesitate to drop by the discussion forum if you decide you need help.

If you write a custom feature tab that you consider may endure wider interest of the public, please don't hesitate to submit it for reference / promotion / inclusion.

How can I customize text filters?

Create a python module in your config dir "filters" subdirectory (create it if doesn't exist). The module name will become the filter's name and will affect its sort order. The module needs to define one function as below:

def func(text: str) -> str:
    transformed: str = ...  # transform text
    return transformed

example = 'Placeholder to pass through func and show when text empty'

To disable a built-in filter, name an empty file module the same as the built-in filter you want to disable (e.g. create empty file $CONFIG_HOME/filters/bold.py to disable "bold" text transform).

See bundled filters for more transforming inspiration. See also above question on customizing tabs.

Buy me a coffee