====== Ubuntu - Mouse - Map Mouse Buttons to Arbitrary Functions ======

There are various options that can be used to allow a mouse button click to action an arbitrary function.

These include:

  * **xbindkeys** allows you to map any mouse (or keyboard) event to some program.
  * **xautomation** provides the **xte** program; which can generate fake input, including keystrokes and mouse-clicks.
  * **xvkbd** can send a keyboard key signal or mouse click to other programs.
  * **xdotool** can simulate keyboard input and mouse activity, move and resize windows, etc.

----

===== Install xbindkeys =====

<code bash>
sudo apt install xbindkeys
</code>

<WRAP info>
**NOTE:**  Xbindkeys is a program that allows to bind commands to certain keys or key combinations on the keyboard.

  * Xbindkeys works with multimedia keys and is window manager independent.

</WRAP>


----

===== Install xautomation =====

<code bash>
sudo apt install xautomation
</code>

<WRAP info>
**NOTE:** This provides the **xte** program; which can generate fake input, including keystrokes and mouse-clicks.
</WRAP>


----

===== Create the xbindkeys Configuration File =====

<code bash?>
xbindkeys --defaults > $HOME/.xbindkeysrc
</code>

<WRAP info>
**NOTE:**  The **$HOME/.xbindkeysrc** file could also be created manually.
</WRAP>

<WRAP info>
**NOTE:**  The format of this file is a series of paired lines.

  - The first line is a command to be executed for an event;
    * The quotation marks ("") around the command is required.
  - The second line is the associated mouse button.
    * The first mouse button (left) is called b:1, the second b:2 and so forth.
</WRAP>

----

===== Assign a function to a Mouse Button  =====

Edit the xbindkeys Configuration file, **~/.xbindkeysrc**:

Add commands similar to this:

<file bash ~/.xbindkeysrc>
"xte 'keydown Home' 'keyup Home'"  
b:6
</file>

<WRAP info>
**NOTE:**  This binds __button 6__ to the __home__ key

  * Raw keycodes can be used too, for example: <code>
"xte 'keydown Home' 'keyup Home'"
m:0x0 + b:6 
</code>

See: [[Ubuntu:Mouse:Map Mouse Buttons to Arbitrary Functions:Identify the key codes to use|Identify the key codes to use]]

</WRAP>

----

==== Another examples ====

<file bash ~/.xbindkeysrc>
# Refresh
"xte 'key F5'"
  b:4 + control
</file>

<WRAP info>
**NOTE:** This maps:

  * This will cause the forward mouse button and the CTRL key to emulate pressing the F5 key.
  * This is useful for refreshing a web page without moving your hand off the mouse.

</WRAP>

----

==== Other examples ====

<file bash ~/.xbindkeysrc>
# Back
"xte 'keydown Alt_L' 'key Left' 'keyup Alt_L'"
 b:8

# Forward
"xte 'keydown Alt_L' 'key Right' 'keyup Alt_L'"
  b:9
</file>

<WRAP info>
**NOTE:** This maps:

  * Button 8 is mapped to ALT+LEFT.
  * Button 9 is mapped to ALT+RIGHT.

</WRAP>

----

==== More complex examples ====

<file bash ~/.xbindkeysrc>
"/usr/bin/xte 'mouseclick 1' 'mouseclick 1' &"
b:8 + Release
</file>

<WRAP info>
**NOTE:**  This maps a double-left-click to button 8.

  * The **Release** option catches __release__ events instead of __press__ events.
</WRAP>


----

====== Restart xbindkeys ======

If any changes are made to the config file then xbindkeys needs to be restarted:

<code bash>
killall xbindkeys
xbindkeys
</code>



----

====== References ======

https://linux.die.net/man/7/xautomation

https://manpages.debian.org/stretch/xautomation/xte.1

https://linux.die.net/man/1/xte