=pod

=head1 NAME

 icewm-keys - icewm keys configuration file

=head1 SYNOPSIS

=over

=item F<$ICEWM_PRIVCFG/keys>

=item F<$XDG_CONFIG_HOME/icewm/keys>

=item F<$HOME/.icewm/keys>

=item F</etc/icewm/keys>

=item F</usr/share/icewm/keys>

=back

=head1 DESCRIPTION

Global key bindings to launch applications (not window manager related).
IceWM allows launching of arbitrary programs with any key combination.
This is configured in the F<keys> file.

Global keybindings to launch applications, which need not be window
manager related.  Each non-empty line starts with the word C<key>.
After one or more spaces follows a double-quoted string of the bound X11
key combination like C<Alt+Ctrl+Shift+X>.  Then after at least one space
follows a shell command line which will be executed by B<icewm> whenever
this key combination is pressed.  For example, the following line
creates a hotkey to reload the B<icewm> configuration:

    key "Ctrl+Shift+r"      pkill -x -HUP icewm

=head1 FORMAT

The syntax of the F<keys> file is as follows:

=over

=over

=item B<key> B<">I<key_combination>B<"> I<program> I<options>

=back

=back

Where,

=over

=item B<key>

The literal string keyword.

=item B<switchkey>

The literal string keyword, used as alternative to C<key> to build
menu-like quickswitch popups.

=item I<key_combination>

Any combination of keys, separated by plus-sign (C<+>).

=item I<program> I<options>

I<program> is the name of the executable or full path to the executable
file that will be run in response to selecting the menu item.  When used
with the B<switchkey> keyword, the I<program> must print on standard
output the contents of the popup like it would be used for dynamic menus.

I<options> is the options and arguments passed to the I<program>
verbatim.

=back

=head1 EXAMPLES

Following is the example F<keys> file that ships with L<icewm(1)>:

    # This is an example for IceWM's hotkey definition file.
    #
    # Place your variants in @CFGDIR@ or in $HOME/.icewm
    # since modifications to this file will be discarded when
    # you (re)install icewm.
    #
    # A list of all valid keyboard symbols can be found in
    # /usr/include/X11/keysym.h, keysymdefs.h, XF86keysym.h,
    # ...  You'll have to omit XK_ prefixs and to replace
    # XF86XK_ prefixes by XF86. Valid modifiers are Alt,
    # Ctrl, Shift, Meta, Super and Hyper.
    #
    key "Alt+Ctrl+t" xterm
    key "Alt+Ctrl+b" xdg-open about:blank
    key "Alt+Ctrl+s" xdg-open https://www.google.com

    key "Super+KP_Subtract" amixer sset PCM 5%-
    key "Super+KP_Add" amixer sset PCM 5%+

    # "Multimedia key" bindings for XFree86. Gather the
    # keycodes of your advanced function keys by watching the
    # output of the xev command whilest pressing those keys
    # and map those symbols by using xmodmap.

    key "XF86AudioLowerVolume" amixer sset PCM 5%-
    key "XF86AudioRaiseVolume" amixer sset PCM 5%+
    key "XF86AudioMute" amixer sset PCM 0%
    key "XF86HomePage" xdg-open about:blank
    key "XF86Search" xdg-open https://www.google.com
    key "XF86Eject" eject

    # display and select monitor setup configurations
    switchkey "Super+p" icewm-menu-xrandr

=head1 FILES

Locations for the F<keys> file are as follows:

=over

=item F<$ICEWM_PRIVCFG/keys>

=item F<$XDG_CONFIG_HOME/icewm/keys>

=item F<$HOME/.icewm/keys>

=item F</etc/icewm/keys>

=item F</usr/share/icewm/keys>

=back

=head1 SEE ALSO

L<icewm(1)>.

=head1 AUTHOR

Brian Bidulock L<mailto:bidulock@openss7.org>.

=head1 LICENSE

B<IceWM> is licensed under the GNU Library General Public License.
See the F<COPYING> file in the distribution.

=cut

# vim: set sw=4 tw=72 nocin spell spelllang=en_ca:
