# Mousetweaks Manual

## Introduction

Mousetweaks provides mouse accessibility enhancements for the GNOME Desktop. Indeed, it offers the following functions to the user:

- Simulated secondary click: it allows the user to perform a secondary click (menu click) by holding down the primary mouse button while keeping the pointer motionless.

- Dwell click: it allows the user to perform the various clicks without pressing any hardware button.

- Pointer capture: it allows the user to lock the pointer in a determined area of the panel until the user releases it by a predefined keystroke or mouse button.

Since version 2.31.3, mousetweaks does not depend any more on the AT-SPI accessibility framework.

## How To Start The Functions

The simulated secondary click and the dwell click depend on the mousetweaks process; however the pointer capture applet depends on the GNOME panel. Consequently, also the methods to start them vary.

### Starting The Simulated Secondary Click Function

You can start the Simulated Secondary Click in two ways:

- from the graphical user interface

- from the command line

#### Start From The Graphical User Interface

The graphical user interface to start the simulated secondary click is located in the Accessibility tab of the Mouse control panel. To open it, choose the menu System Preferences Control Center and the Control Center will open. By clicking on Mouse in the Control Center, the Mouse control panel will open and after clicking on the Accessibility tab, you will see the following settings:

Picture of the Mouse control panel

To start the simulated secondary click function, put a checkmark into the checkbox that says:

Trigger secondary click by holding down the primary button

Picture of the checkbox to start the simulated secondary click

#### Start From The Command Line

To start the simulated secondary click from the command line, open the Terminal and type the following:

`mousetweaks `--ssc``

### Starting The Dwell Click Function

You can start the dwell click function in three ways:

- from the Accessibility tab of the Mouse control panel

- from the command line

- from the On/Off button on the Dwell Click panel applet

#### Start From The Accessibility tab of the Mouse control panel

The graphical user interface to start the dwell click is located in the Accessibility tab of the Mouse control panel. To open it, choose the menu System Preferences Control Center and the Control Center will open. By clicking on Mouse in the Control Center, the Mouse control panel will open and after clicking on the Accessibility tab, you will see the following settings:

Picture of the Mouse control panel

To start the dwell click function, put a checkmark into the checkbox that says:

Initiate click when stopping pointer movement

Picture of the checkbox to start the dwell click function

#### Start From The Command Line

To start the dwell click function and show the click type window from the command line, open the Terminal and type the following:

`mousetweaks `--dwell --show-ctw``

The starting parameters --login and --daemonize were added to allow GDM to start and quit mousetweaks: the first disables the check for the Assistive Technologies framework at the start of mousetweaks; by not passing the second, mousetweaks will keep the pid that it got when it started, allowing GDM to shut it down by using the pid.

#### Start From The On/Off button On The Dwell Click Panel Applet

It is possible to start the Dwell Click by simply resting (dwelling) for a little delay with the pointer on the mouse icon displayed by the Dwell Click panel applet. In fact, this mouse icon is a dwellable On/Off button that provides feedback of the passing dwell time by filling its frame with another colour. When the frame is completely filled, the button displays its active state and the dwell click gets started.

Picture showing the click type applet at the right of the GNOME menus

For instructions about how to install the Dwell Click applet on the GNOME panel, please have a look at Starting The Pointer Capture Function where you can see how it is done for the Pointer Capture panel applet. The procedure for the Dwell Click panel applet is similar.

### Starting The Pointer Capture Function

As the Pointer Capture applet comes in the from of a panel applet, its starting method has to follow the rules dictated by the GNOME panel. Thus, to start the Pointer Capture function, you only have to install it on the panel and it will automatically run.

In order to add it to the panel, proceed as you do with any panel applet: perform a secondary click on the panel to open its contextual menu, choose Add to Panel, and you will get the window showing all the applets that can be installed on the GNOME panel.

By double clicking on the Pointer Capture item in the Add to Panel window, the Pointer Capture applet will be added to the panel, and it will run until it is removed from the GNOME panel.

## How To Quit The Functions

Similar to the starting of the functions, their quitting also depends on the feature that you want to quit.

### Quitting The Simulated Secondary Click

It is possible to quit the Simulated Secondary Click in two ways:

- By removing the mark from the corresponding checkbox in the control panel of Mousetweaks.

  Picture of the checkbox to start the simulated right click feature

  Please refer to Start The Simulated Secondary Click From The Graphical User Interface to locate the checkbox.

- By typing the following command at the command line:

  `mousetweaks` `--shutdown`

### Quitting The Dwell Click

It is possible to quit the dwell click in three ways:

- By removing the mark from the corresponding checkbox in the control panel of Mousetweaks.

  Picture of the checkbox to start the buttonless click feature

  Please refer to Start The Dwell Click From The Graphical User Interface to locate the checkbox.

- By typing the following command at the command line:

  `mousetweaks` `--shutdown`

- If the Dwell Click applet has been installed on the GNOME panel, the Dwell Click can be disabled by dwelling with the pointer on its On/Off button.

  Picture showing the click type applet at the right of the GNOME menus

### Quitting The Pointer Capture Function

As the Pointer Capture function comes in the form of a panel applet, you have to quit it the same way that you do it with other applets: you have to remove it from the GNOME panel. To do it, perform a right click on the handle of the applet and choose Remove From Panel from its contextual menu.

Picture showing the pointer capture area (green) with its contextual menu

When using the default GNOME theme, the handle of the Pointer Capture applet are the two vertical dotted lines at the left of the pointer capture area.

## Description Of The Functions

Mousetweaks offers three pointer accessibility functions to the user. In this section you will find the description of the three functions:

- mouse-a11y-ssc-description

- mouse-a11y-dwell-description

- mouse-a11y-pointer-capture-description

### Simulated Secondary Click Description

When the user activates this feature, he will be able to perform secondary clicks by using the primary mouse button. This is especially useful for users that have only one mouse button at their disposal.

Picture showing the settings belonging to the Simulated Secondary Click.

#### How Does It Work?

Let us assume that the user has enabled the Simulated Secondary Click feature.

To perform a simulated secondary click, the user has to keep the primary mouse button pressed without moving the pointer for the time determined by the delay slider of the Simulated Secondary Click feature. While the primary mouse button is kept pressed, the arrow of the pointer will be filled with a different color to give feedback about the passing time.

If the user releases the primary mouse button before the arrow of the pointer has been completely filled with the new color, the system will only receive the information of the primary mouse button press and release.

If the user releases the primary mouse button after the arrow of pointer has been completely filled with the new color, the primary mouse button events will be followed by a secondary mouse button click. In fact, mousetweaks creates this simulated secondary mouse button click as soon as the user releases the the primary mouse button.

The explanations above assumed that the pointer did not move between the primary mouse button press and release. If the pointer gets moved before the primary mouse button is released, no simulated secondary click will be created. Consequently, to cancel an initiated secondary click, the user only has to move the pointer before releasing the primary mouse button.

Moreover, the fact that the simulated secondary click is immediately preceded by a left click makes it behave differently than expected when the preceding left click has an incidence on the object that is to receive the simulated secondary click. Please, have a look at the section about the Differences To The Normal Secondary Click for more details.

#### The Delay Slider

How long the user has to hold the primary mouse button pressed, is determined by the Delay slider located under the activation checkbox. By using this slider, the user can choose the delay most appropriate to him.

#### Motion Threshold

People that have trouble to keep the pointer completely motionless can use the Motion Threshold slider of the Dwell Click feature. This setting makes mousetweaks ignore little mouse movements, so that the simulated secondary click is issued even if the pointer is not completely motionless. Please have a look at the section of the Motion Threshold slider of the Dwell Click feature for more information about it.

The Motion Threshold slider that is located under the Dwell Click feature is also effective for the Simulated Secondary Click feature, even if the Dwell Click feature is disabled.

#### Differences To The Normal Secondary Click

As the Simulated Secondary Click does not discard the primary mouse button press and release, the resulting primary click occurs just before the secondary click created by mousetweaks. Consequently, the simulated secondary click behaves a bit differently than the normal secondary click, because the latter is usually not preceded immediately by a primary mouse button click. For example:

- It is not possible to perform a secondary click on multiple items because the primary click issued before the secondary click deselects the items.

- When performing a simulated secondary click on a link in a web page, the primary click, that precedes the simulated secondary click, opens the referenced page before the simulated secondary click has a chance to open the contextual menu of the link.

  The contextual menu of a link in a web page can be opened by performing a simulated secondary click while keeping the Ctrl modifier pressed. This works because the referenced page opens in a new tab when the link receives a primary click in conjunction with a pressed Ctrl modifier; which is also what happens as a side effect when opening the contextual menu of a link by using the simulated secondary click in conjunction with the Ctrl modifier.

  However the browser has to be configured to not automatically switch to the new tab when it opens; otherwise the page with the link disappears as the new tab becomes visible and the contextual menu does not appear.

- When the simulated secondary click is performed on the trash icon in the panel, not only does the contextual menu appear, but the trash folder also opens. (The former is caused by the secondary click, the latter by the primary click preceding the secondary click.)

It is not possible to provide a list of all diverging behaviours, because it depends on the reaction of the application receiving the secondary click preceded by a primary click.

Looking at it the other way, it is not possible to perform a long motionless primary mouse button press without also triggering the secondary click, unless the pointer is moved before the primary mouse button release. This may also have unexpected consequences for some users. For example:

- When releasing the primary button after keeping it pressed on the arrow of a scrollbar for more than the delay time, the scrollbar jumps to the bottom. This is in fact the normal behaviour of a secondary click on an arrow of a scrollbar.

  To avoid that the scrollbar jumps to the bottom, simply move the pointer away from the arrow of the scrollbar before releasing the primary button; this way, the initiated simulated secondary click gets cancelled.

### Dwell Click Description

There are users that cannot use any hardware button. By activating the Dwell Click, they can have the mouse perform the various clicks without pressing any mouse button. The click types that can be performed are: single primary click, double click, drag click and secondary click.

When the dwell click is active, the mouse buttons remain functional and it is still possible to click with the mouse buttons. Moreover, If the user performs a click with a mouse button while a dwell click is in progress, the dwell click gets stopped and no dwell click is generated; to initiate a new dwell click, the user has to move and stop moving the mouse as usual for the dwell click.

#### How Does It Work?

Each time the pointer stops moving, a dwell click is initiated. To give feedback to the user, mousetweaks will fill the arrow of the pointer with another color while it is counting down the time before the click completion kicks in.

How the click is completed and how the click type is chosen depends on what dwell mode the user has selected. The two available modes are:

- Choose type of click beforehand

- Choose type of click with mouse gestures

Picture showing the radio buttons to select dwell mode

To select the mode, the user only has to click on the radio button that corresponds to his choice.

##### Automatic Click Completion With Click Type Choice Beforehand

This mode is active when the user selects Choose type of click beforehand. In fact, after the mouse has been motionless for the time defined by the Delay slider, the system will automatically perform the click type that is selected in the Click Type Window shown here:

Picture showing the click type window

To display the Click Type Window on the screen, the user has to put a checkmark in the checkbox named Show click type window:

Picture with the checkbox to display the click type window

After the click has occurred, the single click type will be automatically restored. In order to choose another click type, the user has to perform an automatic click on the button in the Click Type Window that corresponds to his click type choice.

Instead of the Click Type Window some users might prefer to use the Dwell Click panel applet, that has some advantages:.

Picture showing the click type applet at the right of the GNOME menus

Indeed, by using the Dwell Click panel applet:

- The user does not need the Click Type Window that might cover other windows on the desktop.

- The user has a direct way to start and stop the dwell click by using the On/Off button of the Dwell Click applet. This is especially useful when he wants to disable dwelling for a little while to read some text without the interference of a dwell click.

To display the Dwell Click applet on the GNOME panel, the user has to follow the usual procedure to add applets to the GNOME panel. An example about how to do it can be found in the section Starting The Pointer Capture Function.

The Click Type Window and the Dwell Click applet can be used simultaneously or each on its own.

##### Click Completion And Click Type Choice By Mouse Gesture

This mode is active when the user selects Choose type of click with mouse gestures. In fact, after the mouse has been motionless for the delay defined by the Delay slider, the shape of the pointer will change for a little time lapse; let's call this shape the gesture shape:

- If the user moves the pointer while it is showing the gesture shape, a click is performed at the location where the pointer was last motionless; finally the pointer returns to its normal shape. The type of click performed depends on the direction of the movement of the mouse. During the movement of the pointer, a line is drawn following the movement of the pointer to give feedback to the user.

- If the user keeps the pointer motionless until it returns to its normal shape, the user can move the mouse without a click being performed. The next dwell click can be performed at the next pointer stop.

The user also has the possibility to match click type with movement direction by using the 4 popups available:

Picture showing the configuration options to map click type to movement direction

There is also a Disabled menu item in each popup. The user can select it if he does not want some click types to be performed automatically. This is especially interesting for users that have problems with only certain click types.

#### Dwell Delay Setting

With the Delay slider, the user can configure how long the pointer has to be motionless for the click to be initiated.

Picture showing the delay slider of the dwell click

The dwell delay only works in the context of the dwell click.

#### Motion Threshold Setting

For people that have trouble to keep the mouse motionless, there is the Motion Threshold slider.

Picture showing the motion threshold slider of the dwell click

When the slider is set towards low, even little mouse movements are considered; however, by setting a higher threshold, the pointer has to travel a bigger distance before it is considered as moving.

The Motion Threshold setting does not only work for the Dwell Click, but also for the Simulated Secondary Click, even if the Dwell Click is disabled.

### Locking The Pointer Description

There are people that have to use their pointing device not only for the computer. These people would welcome a way to lock the pointer into an area of the screen, so that they can use their pointing device for other tasks.

In fact, the Pointer Capture panel applet creates an area on the panel, into which the user can lock the pointer until he releases it in a determined way.

Have a look at Starting The Pointer Capture Function for instructions about how to install the pointer capture applet on the GNOME panel.

Picture showing the pointer capture area (green) with its contextual menu

Picture of the pointer capture area when the pointer has been captured

By choosing Preferences in the contextual menu of the Pointer Capture applet, the user gets a window with the options of the Pointer Capture applet:

Picture showing the preferences of the Pointer Capture applet

The Preferences window of the Pointer Capture applet has three sections:

- In the Capture Pointer section, the user can specify under what circumstances the pointer gets captured when it moves into the capture area. For example: if the control modifier is checked, the pointer gets captured when it is over the capture area and the user presses the Control modifier key. If no modifier is checked and the mouse button is set to 0, the pointer only has to move into the capture area to get locked.

  It is also possible to specify a combination of modifiers and mouse button.

- In the Release Pointer section, the user can specify what modifier or mouse button releases the pointer.

  It is also possible to specify a combination of modifiers and mouse button.

- In the Size of Capture Area section, the user can specify the width of the capture area on the GNOME panel.

## About Mousetweaks

### Authors and hosting site

Mousetweaks is based on a specification hosted on Launchpad. It was implemented by Gerd Kohlberger ( gerdk@svn.gnome.org ), and I ( frfumanti@svn.gnome.org ) helped with testing and logistics.

You can find more informations about Mousetweaks on Launchpad and on GNOME Live.

### Feedback

To report a bug or make a suggestion regarding the mousetweaks module, its user interface or its manual, please use the facilities provided by GNOME's Bugzilla. If it concerns the layout of the Accessibility tab of the Mouse control panel, please file it against the gnome-control-center module; for anything else regarding mousetweaks, please file it against the mousetweaks module.

### License

Mousetweaks is distributed under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. A copy of the license can be found at this link, or in the file COPYING.GPL included with the source code of this program.

This manual is distributed under the terms of the The GNU Free Documentation License as published by the Free Software Foundation; either version 1.3 of the License, or (at your option) any later version. A copy of the license can be found at this link, or in the file COPYING.FDL included with the source code of this program.