How to Create Custom Keyboard Shortcuts in FunOS

Keyboard shortcuts make it faster to open applications, run commands, and perform common desktop actions. Instead of opening the application menu whenever you need a program, you can assign it a convenient key combination.

FunOS uses JWM (Joe’s Window Manager). In JWM, keyboard shortcuts are configured by editing a text-based key bindings file.

This guide explains how to create custom keyboard shortcuts in FunOS, check the configuration for errors, apply your changes, and troubleshoot common problems.

How Keyboard Shortcuts Work in FunOS

JWM keyboard shortcuts are stored in the following file:

~/.config/jwm/keys

Each shortcut is defined using a <Key> element. A typical application shortcut follows this format:

<Key mask="MODIFIER" key="KEY">exec:COMMAND</Key>

For example:

<Key mask="C4" key="f">exec:pcmanfm</Key>

This shortcut opens the File Manager when you press Ctrl + Super + F.

The shortcut contains three main parts:

  • mask="C4" specifies the modifier keys.
  • key="f" specifies the main key.
  • exec:pcmanfm tells JWM to run the pcmanfm command.

The exec: prefix is required when you want JWM to launch an application or run an external command.

JWM Modifier Keys

The mask attribute specifies which modifier keys must be held down.

CharacterModifier key
AAlt
CCtrl
SShift
1Mod1, usually Alt
2Mod2
3Mod3
4Mod4, usually the Super or Windows key
5Mod5

You can combine multiple modifier characters without spaces.

For example:

mask="CA"

means Ctrl + Alt, while:

mask="C4"

normally means Ctrl + Super.

The physical key assigned to a Mod value can vary depending on your keyboard layout and X keyboard configuration. On most systems, however, Mod4 corresponds to the Super or Windows key.

Step 1: Open a Terminal

Open a Terminal using one of the following methods:

  • Click Menu in the lower-left corner of the screen, then click Terminal.
  • Click the Terminal icon in the Tray.
  • Press Ctrl + Alt + T.

Step 2: Back Up the Key Bindings File

Before editing the configuration, create a backup of the existing key bindings file:

cp ~/.config/jwm/keys ~/.config/jwm/keys.bak

This backup allows you to restore the original keyboard shortcuts if something goes wrong.

Step 3: Open the Key Bindings File

Open the file in Mousepad:

mousepad ~/.config/jwm/keys

The file should begin with an opening <JWM> tag and end with a closing </JWM> tag.

A simplified file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<JWM>

    <!-- Key bindings are placed here -->

</JWM>

All keyboard shortcuts must be placed between the opening <JWM> and closing </JWM> tags.

Do not add a shortcut after </JWM>. Anything placed outside the main <JWM> section is not part of the JWM configuration.

Step 4: Add a Custom Keyboard Shortcut

In this example, we will create a shortcut that opens the File Manager when you press Ctrl + Super + F.

Add the following line before the closing </JWM> tag:

<Key mask="C4" key="f">exec:pcmanfm</Key>

Your configuration might look like this:

<JWM>

    <Key mask="C4" key="f">exec:pcmanfm</Key>

</JWM>

Here is what each part means:

mask="C4"

This specifies the Ctrl + Super modifier keys.

key="f"

This specifies the main key: F.

exec:pcmanfm

This tells JWM to run pcmanfm, which opens the File Manager.

Save the file after adding the shortcut.

Example: Adding a Shortcut to the Existing File

The following example shows how to add a custom shortcut to a typical JWM key bindings file.

Before Adding the Shortcut

<?xml version="1.0" encoding="UTF-8"?>
<JWM>

    <!-- Key bindings -->
    <Key key="Up">up</Key>
    <Key key="Down">down</Key>
    <Key key="Right">right</Key>
    <Key key="Left">left</Key>
    <Key key="h">left</Key>
    <Key key="j">down</Key>
    <Key key="k">up</Key>
    <Key key="l">right</Key>
    <Key key="Return">select</Key>
    <Key key="Escape">escape</Key>

    <Key mask="A" key="Tab">next</Key>
    <Key mask="A" key="F4">close</Key>
    <Key mask="A" key="#">desktop#</Key>
    <Key mask="A" key="F1">root:1</Key>
    <Key mask="A" key="F2">window</Key>
    <Key mask="A" key="F10">maximize</Key>
    <Key mask="A" key="Right">rdesktop</Key>
    <Key mask="A" key="Left">ldesktop</Key>
    <Key mask="A" key="Up">udesktop</Key>
    <Key mask="A" key="Down">ddesktop</Key>
    <Key mask="CA" key="t">exec:lxterminal</Key>

</JWM>

After Adding the Shortcut

The custom shortcut is added near the end of the file, immediately before the closing </JWM> tag:

<?xml version="1.0" encoding="UTF-8"?>
<JWM>

    <!-- Key bindings -->
    <Key key="Up">up</Key>
    <Key key="Down">down</Key>
    <Key key="Right">right</Key>
    <Key key="Left">left</Key>
    <Key key="h">left</Key>
    <Key key="j">down</Key>
    <Key key="k">up</Key>
    <Key key="l">right</Key>
    <Key key="Return">select</Key>
    <Key key="Escape">escape</Key>

    <Key mask="A" key="Tab">next</Key>
    <Key mask="A" key="F4">close</Key>
    <Key mask="A" key="#">desktop#</Key>
    <Key mask="A" key="F1">root:1</Key>
    <Key mask="A" key="F2">window</Key>
    <Key mask="A" key="F10">maximize</Key>
    <Key mask="A" key="Right">rdesktop</Key>
    <Key mask="A" key="Left">ldesktop</Key>
    <Key mask="A" key="Up">udesktop</Key>
    <Key mask="A" key="Down">ddesktop</Key>
    <Key mask="CA" key="t">exec:lxterminal</Key>

    <!-- Custom keyboard shortcuts -->
    <Key mask="C4" key="f">exec:pcmanfm</Key>

</JWM>

The only change is the addition of this line:

<Key mask="C4" key="f">exec:pcmanfm</Key>

Step 5: Check the JWM Configuration

Before restarting JWM, check the configuration for errors:

jwm -p

This command parses the JWM configuration and reports problems such as invalid XML syntax or incorrectly written settings.

When the configuration is valid, the command should finish without displaying an error.

When an error is reported, return to the key bindings file and look for problems such as:

  • A missing quotation mark
  • A missing closing </Key> tag
  • A shortcut placed outside the <JWM> section
  • A misspelled attribute
  • An XML special character that has not been escaped

Checking the configuration before restarting JWM can prevent a typing mistake from disrupting the desktop session.

Step 6: Restart JWM

Apply the changes by restarting JWM:

jwm -restart

The desktop may briefly refresh while JWM reloads its configuration.

You can now test the new shortcut. In this example, press Ctrl + Super + F. The File Manager should open.

Custom Keyboard Shortcut Examples

The following examples can be copied or adapted for other applications and commands.

Before using one of these combinations, make sure it is not already assigned to another action.

Open the File Manager

Press Super + F:

<Key mask="4" key="f">exec:pcmanfm</Key>

Open a Terminal

Press Ctrl + Alt + T:

<Key mask="CA" key="t">exec:lxterminal</Key>

This shortcut may already be included in the default FunOS configuration.

Open Firefox ESR

Press Ctrl + Alt + W:

<Key mask="CA" key="w">exec:firefox-esr</Key>

Open Mousepad

Press Super + E:

<Key mask="4" key="e">exec:mousepad</Key>

Open the Calculator

Press Super + C:

<Key mask="4" key="c">exec:galculator</Key>

Open the Home Folder

Press Ctrl + Super + H:

<Key mask="C4" key="h">exec:pcmanfm "$HOME"</Key>

The $HOME environment variable refers to your home directory.

Open a Website

Press Ctrl + Alt + F to open the FunOS website:

<Key mask="CA" key="f">exec:xdg-open https://funos.org/</Key>

The website will open in your default web browser.

Take a Screenshot

Press the Print Screen key:

<Key key="Print">exec:gnome-screenshot</Key>

This example uses GNOME Screenshot.

Lock the Screen

Press Super + L:

<Key mask="4" key="l">exec:xscreensaver-command -lock</Key>

This command locks the screen through XScreenSaver.

Open the Logout or Shutdown Window

You can assign a shortcut to the logout or shutdown application used by FunOS.

For example:

<Key mask="C4" key="Delete">exec:funos-logout</Key>

Before adding the shortcut, verify that the command exists:

command -v funos-logout

When the command exists, the Terminal will display its location. When no output appears, the command is not available under that name.

Creating a Shortcut for a Terminal Command

A keyboard shortcut can run almost any command that works from a Terminal.

For example, the following shortcut opens PulseAudio Volume Control when you press Super + V:

<Key mask="4" key="v">exec:pavucontrol</Key>

Before adding a command to the JWM configuration, test it in a Terminal:

pavucontrol

When the application opens successfully, the same command can normally be used after exec: in a JWM shortcut.

Testing the command first helps you determine whether a problem is caused by the command itself or by the keyboard shortcut configuration.

Creating a Shortcut for a Shell Command

Simple application commands can usually be written directly after exec:. More complex commands may need to be run through a shell.

This applies to commands that use features such as:

  • Multiple commands
  • Pipes
  • Output redirection
  • Environment variables
  • Shell operators such as && or ||

For example, the following shortcut creates a Screenshots folder when necessary and then opens it in the File Manager:

<Key mask="C4" key="s">exec:sh -c 'mkdir -p "$HOME/Pictures/Screenshots" &amp;&amp; pcmanfm "$HOME/Pictures/Screenshots"'</Key>

The actual shell command normally contains &&:

mkdir -p "$HOME/Pictures/Screenshots" && pcmanfm "$HOME/Pictures/Screenshots"

However, because the JWM key bindings file uses XML, each ampersand must be written as &amp;.

Therefore:

&&

must be written as:

&amp;&amp;

Avoid assigning administrative commands such as sudo apt update directly to a keyboard shortcut. Commands that require a password may not display a suitable password prompt when launched directly by JWM.

It is generally safer to open a Terminal and run administrative commands manually.

Finding an Application’s Command

A JWM shortcut must use the application’s executable command. This command may be different from the name shown in the application menu.

You can use one of the following methods to find the correct command.

Method 1: Use command -v

Run command -v followed by the likely command name:

command -v mousepad

When the command is installed and available in your command path, the Terminal displays its location.

For example:

/usr/bin/mousepad

You can normally use the shorter command name in the JWM configuration:

<Key mask="4" key="e">exec:mousepad</Key>

Method 2: Test the Command in a Terminal

Enter the likely application command:

mousepad

When the application opens, you have found a working command.

Close the application before continuing if you only opened it for testing.

Method 3: Check the Application’s Desktop Entry

Application menu entries are usually stored in one of the following directories:

/usr/share/applications/

or:

~/.local/share/applications/

Find the relevant .desktop file and look for a line beginning with Exec=.

For example:

Exec=mousepad %U

The %U portion is a desktop-entry field code. Similar field codes include %F, %f, and %u.

These field codes are usually unnecessary in a JWM keyboard shortcut. You can normally use only the executable command:

<Key mask="4" key="e">exec:mousepad</Key>

Some Exec= lines contain additional options or commands. Test the command in a Terminal before adding it to the key bindings file.

Using Special Keys

JWM uses X key symbol names in the key attribute.

Common key names include:

Keyboard keyJWM key name
EscapeEscape
EnterReturn
Spacebarspace
BackspaceBackSpace
DeleteDelete
TabTab
Print ScreenPrint
Left arrowLeft
Right arrowRight
Up arrowUp
Down arrowDown
F1 through F12F1 through F12

For example, the following shortcut runs a command when you press Ctrl + Alt + Escape:

<Key mask="CA" key="Escape">exec:COMMAND</Key>

Replace COMMAND with the command you want to run.

The value of the key attribute must be a valid X key symbol. Key names are case-sensitive, so enter them exactly as required.

Avoiding Shortcut Conflicts

Before adding a shortcut, check whether the same key combination is already assigned.

For example, the following command searches for entries that use the f key:

grep 'key="f"' ~/.config/jwm/keys

Review the matching lines and compare their mask values.

These two shortcuts do not conflict because they use different modifiers:

<Key mask="4" key="f">exec:pcmanfm</Key>
<Key mask="CA" key="f">exec:xdg-open https://funos.org/</Key>

The first uses Super + F, while the second uses Ctrl + Alt + F.

However, two entries with the same mask and key values may cause one shortcut to override the other or produce unexpected behavior.

Avoid replacing important default shortcuts unless you understand what they currently do.

Organizing Custom Shortcuts

You can use an XML comment to keep your custom shortcuts grouped together:

<!-- Custom keyboard shortcuts -->
<Key mask="4" key="f">exec:pcmanfm</Key>
<Key mask="4" key="e">exec:mousepad</Key>
<Key mask="4" key="w">exec:firefox-esr</Key>

An XML comment begins with:

<!--

and ends with:

-->

JWM ignores comments when reading the configuration, so they can be used to describe or organize your shortcuts.

How to Remove a Custom Keyboard Shortcut

Open the key bindings file:

mousepad ~/.config/jwm/keys

Find the shortcut you want to remove. For example:

<Key mask="4" key="f">exec:pcmanfm</Key>

Delete the entire line and save the file.

Check the configuration:

jwm -p

When no error is reported, restart JWM:

jwm -restart

The key combination will no longer launch the assigned command.

How to Restore the Original Key Bindings

When the configuration becomes unusable, restore the backup created earlier:

cp ~/.config/jwm/keys.bak ~/.config/jwm/keys

Check the restored configuration:

jwm -p

Then restart JWM:

jwm -restart

Your key bindings will return to the state they were in when the backup was created.

Troubleshooting

The Shortcut Does Nothing

First, test the application command directly in a Terminal.

For example:

pcmanfm

When the command does not work in a Terminal, it will not work from the JWM shortcut either.

Also check that:

  • The shortcut is between the <JWM> and </JWM> tags.
  • The application is installed.
  • The executable command is correct.
  • The modifier characters are correct.
  • The key name is valid.
  • The same key combination is not already assigned.
  • The file was saved.
  • JWM was restarted after the file was changed.

JWM Reports an XML Error

Check the configuration:

jwm -p

Read the error message and inspect the indicated part of the configuration.

For example, the following line is invalid:

<Key mask="4 key="f">exec:pcmanfm</Key>

The quotation mark after 4 is missing.

The corrected line is:

<Key mask="4" key="f">exec:pcmanfm</Key>

Other common XML problems include missing closing tags, incorrectly nested elements, and unescaped special characters.

A Command Contains an Ampersand

A raw ampersand can make the XML invalid.

The following shortcut is incorrect:

<Key mask="4" key="s">exec:command1 && command2</Key>

Run the commands through a shell and replace each ampersand with &amp;:

<Key mask="4" key="s">exec:sh -c 'command1 &amp;&amp; command2'</Key>

This allows the XML parser to read the command correctly.

The Super Key Does Not Work

The Super or Windows key is normally represented by Mod4:

mask="4"

To view the current modifier assignments, run:

xmodmap -pm

Look for mod4 in the output and confirm that it contains a Super key, such as Super_L or Super_R.

When the Super key is assigned to a different modifier, you may need to use the corresponding modifier number in the shortcut.

The Shortcut Uses the Wrong Key

Make sure the value in the key attribute is a valid X key symbol.

You can use the following command to identify a key:

xev

A small window will appear. Press the key you want to identify and look for the keysym value in the Terminal output.

Close the xev window when finished.

The Shortcut Works Only After Logging In Again

Make sure you restarted JWM after saving the file:

jwm -restart

When the shortcut still does not work, log out and log back in to reload the complete desktop session.

Conclusion

Creating custom keyboard shortcuts in FunOS is straightforward once you understand the JWM <Key> syntax. Each shortcut combines a modifier mask, a main key, and an action or command.

Before making changes, create a backup of the key bindings file. Test application commands in a Terminal, run jwm -p to check the configuration, and restart JWM with jwm -restart to apply the changes.

With a few carefully chosen shortcuts, you can open frequently used applications and perform common desktop tasks more quickly.

Leave a Reply

Your email address will not be published. Required fields are marked *