Configuring window manager button bindings

Configuring button bindings

To modify an existing button binding or to create a new button binding, perform the following steps.

Open the desired window manager configuration file for editing.
- pmwm mode:
  
  /usr/lib/X11/system.pmwmrc for system-wide changes
  $HOME/.pmwmrc for individual changes
- mwm mode:
  
  /usr/lib/X11/system.mwmrc for system-wide changes
  $HOME/.mwmrc for individual changes

Locate the button binding section in the window manager configuration file. The button binding section uses the following syntax:

   Buttons  bindings_set_name
   {
       button  context     function
       button  context     function
       button  context     function
                 .
                 .
       button  context     function
   }

Configure the button binding specification, if desired.
Configure the function specification, if desired.
Configure the context specification, if desired.
Restart the window manager and test your new button binding.

Step 1: Editing a window manager configuration file

If you want to make system-wide changes to the default button bindings, open the system-wide window manager configuration file, /usr/lib/X11/system.pmwmrc if you are using pmwm mode or system.mwmrc if you are using mwm mode. The system-wide file contains the default functionality for the window manager button bindings.

If you want to customize the button bindings in your local Graphical Environment, edit your personal window manager configuration file, $HOME/.pmwmrc if you are using pmwm mode or $HOME/.mwmrc if you are using mwm mode. The personal configuration file is not provided with the system by default. If it does not already exist, you must create your own by copying the appropriate system-wide window manager configuration file to .pmwmrc or .mwmrc in your $HOME directory.

NOTE: Once the .pmwmrc or .mwmrc file exists in $HOME, it completely overrides the system-wide window manager configuration file. Therefore, make sure you copy the entire system file to your home directory, to avoid losing critical functionality.

Step 2: Locating the button binding section

When you locate the appropriate button binding section, you see entries with the following syntax:

   Buttons  bindings_set_name
   {
       button  context     function
       button  context     function
                 .
                 .
   }

Buttons: the type of the binding set being defined.
bindings_set_name: the name assigned to a set of bindings. The default name is ``DefaultButtonBindings''.
button: the specification that defines the mouse button action or the mouse button action plus a key sequence.
context: the specification that defines the window manager context in which the button specification becomes active. For example, the context of a window indicates that the pointer must be on a client window or a window management frame for the button specification to be effective.
function: the specification that defines one of the many window manager functions or actions. See ``Using window manager functions'' for a list of these functions.

Step 3: Configuring the button binding specification

The window manager configuration files use window manager functions to define the behavior and control the functionality of button events. A button event describes an action that you take, such as pressing mouse button 1, to execute a function (for example: raising a window). The button event specification has the following syntax:

button = [modifier_list]button_event_name

where:

modifier_list = modifier_name {modifier_name}

``Button event definitions'' lists the values that can be used for button_event_name. ``Modifiers'' lists the values that can be used for modifier_name.

Button event definitions

button_event_name Description

Btn1Down Button 1 press

Btn1Up Button 1 release

Btn1Click Button 1 press and release

Btn1Click2 Button 1 double click

Btn2Down Button 2 press

Btn2Up Button 2 release

Btn2Click Button 2 press and release

Btn2Click2 Button 2 double click

Btn3Down Button 3 press

Btn3Up Button 3 release

Btn3Click Button 3 press and release

Btn3Click2 Button 3 double click

Btn4Down Button 4 press

Btn4Up Button 4 release

Btn4Click Button 4 press and release

Btn4Click2 Button 4 double click

Btn5Down Button 5 press

Btn5Up Button 5 release

Btn5Click Button 5 press and release

Btn5Click2 Button 5 double click

To make sure you are not selecting already existing button-action combinations, you might want to modify the button event by requiring a simultaneous key press with the button action. These required key presses are called ``modifiers''. All modifiers specified are exclusive; that is, only the specified modifiers can be present when the button event occurs. ``Modifiers'' indicates the values that can be used for modifier_name.

button_event_name	Description
Btn1Down	Button 1 press
Btn1Up	Button 1 release
Btn1Click	Button 1 press and release
Btn1Click2	Button 1 double click
Btn2Down	Button 2 press
Btn2Up	Button 2 release
Btn2Click	Button 2 press and release
Btn2Click2	Button 2 double click
Btn3Down	Button 3 press
Btn3Up	Button 3 release
Btn3Click	Button 3 press and release
Btn3Click2	Button 3 double click
Btn4Down	Button 4 press
Btn4Up	Button 4 release
Btn4Click	Button 4 press and release
Btn4Click2	Button 4 double click
Btn5Down	Button 5 press
Btn5Up	Button 5 release
Btn5Click	Button 5 press and release
Btn5Click2	Button 5 double click

NOTE: The <Alt> key is frequently labeled Extend or Meta. Alt and Meta can be used interchangeably for an event specification.

Modifiers

modifier_name Description

Ctrl Control Key

Shift Shift Key

Alt Alt/Meta Key

Meta Meta/Alt Key

Lock Lock Key

Mod1 Modifier1

Mod2 Modifier2

Mod3 Modifier3

Mod4 Modifier4

Mod5 Modifier5

For example, in the following sample button binding definition, the button specification is Meta<Btn3Down>. When the pointer is in a client window and you press the Meta key simultaneously with mouse button 3, you execute the f.move function.

modifier_name	Description
Ctrl	Control Key
Shift	Shift Key
Alt	Alt/Meta Key
Meta	Meta/Alt Key
Lock	Lock Key
Mod1	Modifier1
Mod2	Modifier2
Mod3	Modifier3
Mod4	Modifier4
Mod5	Modifier5

   Buttons  bindings_set_name
   {
       Meta<Btn3Down>  window     f.move
             .
             .
   }

If you are editing an existing button binding, replace the old button specification with the new one. Make sure you do not try to reconfigure the default button bindings listed in ``Default button bindings''.

If you are adding a new button binding, put the new button specification on a new line.

Step 4: Configuring the function specification

The syntax for naming a function is the same, no matter what type the function describes. The syntax for naming a function is:

function = function_name [function_args]

function_name is one of the valid window manager functions, and function_args is a valid argument to the function. If function_args contains more than one word, the argument must be contained in quotes.

If you are editing an existing button binding, replace the old function specification with the new one.

If you are adding a new button binding, put the new function specification on a new line, after the related button specification.

Step 5: Configuring the context specification

The context specification defines the window manager context in which the button specification becomes active; it indicates where the pointer must be for the button specification to be effective. For example, the context of a window indicates that the pointer must be on a client window or a window management frame for the button binding to be effective. The button specification can be active in more than one context.

``Button binding contexts'' lists and describes the values that can be used for context.

Button binding contexts

Context Description

app The button binding is effective when the pointer is on the application window, not including the window management frame.

border The button binding is effective when the pointer is on the border of the window management frame, not including the title bar.

frame The button binding is effective when the pointer is on the window management frame around a client window, border, and title bar.

icon The button binding is effective when the pointer is on an icon. Note that icon refers to window manager icons only, not Desktop icons.

root The button binding is effective when:

the pointer is on the Root window, and

neither a client window nor an icon is to be acted upon by the function.

title The button binding is effective when the pointer is on the title area of the window management frame.

window The button binding is effective when the pointer is on a client window, title bar, or a window management frame.

If you are editing an existing button binding, replace the old context specification with the new one.

Context	Description
app	The button binding is effective when the pointer is on the application window, not including the window management frame.
border	The button binding is effective when the pointer is on the border of the window management frame, not including the title bar.
frame	The button binding is effective when the pointer is on the window management frame around a client window, border, and title bar.
icon	The button binding is effective when the pointer is on an icon. Note that icon refers to window manager icons only, not Desktop icons.
root	The button binding is effective when: the pointer is on the Root window, and neither a client window nor an icon is to be acted upon by the function.
title	The button binding is effective when the pointer is on the title area of the window management frame.
window	The button binding is effective when the pointer is on a client window, title bar, or a window management frame.

If you are adding a new button binding, put the context specification on a new line, after the related button and function specifications. See ``Function constraints'' and ``Where functions can be used'' for a list of the contexts that are available to each of the window manager functions.

Step 6: Restarting the window manager

After you configure your new button bindings, you must restart the window manager before your changes can take effect. Restart the window manager by selecting the Restart Window Manager option from the Root menu. The Root menu is accessed by pressing and holding mouse button 1 on the Desktop background or, if the Desktop is not running, in the Root window.

Verify that the new button bindings are configured correctly by testing your new button sequences in the appropriate contexts. The button bindings are effective immediately after the window manager is restarted.