# Directives

SETMOUSE | Control/Set Mouse

## Formats

1. Define Mouse Region: | SETMOUSE [*-@(col,ln,width,hi){= | : | ^} expression
2. Use String to Define Event: | SETMOUSE [*]string${ | :} expression
3. Use Current Window Size: | SETMOUSE [*]@(*){ | :} expression
4. Clear All Settings: | SETMOUSE CLEAR
5. Enable/Disable: | SETMOUSE {ON | OFF}

Where

* | Optional. The first instance of an * (asterisk) in Formats 2 through 4 defines the mouse event as being for all windows. The second instance of the * (asterisk) in Format 3 is a size option. See @(col,ln,width,hi) below.
@(col,ln,width,hi) | Mouse region coordinates. Numeric expressions: starting column, starting line, width (number of columns) and height (number of lines). Using an optional single * (asterisk) instead of col,ln,width,hi defines the mouse region for the event as equal in size to the current window.
= | : | ^ | Operators control mouse event processing:
: | (colon) | When mouse button is pressed/dragged in the region
= | (equals sign) | When mouse button is released in the region
^ | (exponentiation symbol) | When mouse hovers over the selected area (added in PxPlus 2019)
expression | Expression to define the type of function for mouse events in the specified region: if numeric, the CTL value to return, and if string, the directive to execute. #### Note: The hover option ( ^ ) only supports numeric expressions.
string$ | Character string to be compared to the current screen contents. String expression.

## Description

Use the SETMOUSE directive to define and control mouse events. By default, the mouse events are tied to the current window only. The SETMOUSE directive supports fractional coordinates to two decimal places.

#### Note:
Only a single SETMOUSE directive can be active for the same region at any time.

## Format 1

Define Mouse Region

SETMOUSE [*-@(col,ln,width,hi){= | : | ^} expression

Use this format to define the region in which a mouse event can occur.

Use an optional * (asterisk) to define the mouse event as being for all windows instead of just the current window.

Example:

> 0010 rem Return CTL=4 when mouse released on line 20 in columns 0 through 5
> 0010 setmouse on
> 0020 print 'CS',@(0,20),"[Quit]",
> 0030 setmouse @(0,20,6,1)=4
> 0100 input @(10,10),"Enter name:",X$
> 0110 if ctl=4 then goto 9000 ! Wrap-up

## Format 2

Use String to Define Event

SETMOUSE [*]string${ | :} expression

Use this format to define a character string to set the function the mouse event will generate. To remove a mouse event definition, use a null "" expression.

Use an optional * (asterisk) to define the mouse event as being for all windows instead of just the current window.

Example:

This logic returns CTL=6 whenever the mouse is released on the string 'Help' and CTL=4 on the string 'Quit'. Whenever the mouse is released on the word 'Calc', PxPlus calls "CALC" and then returns to the current statement after "CALC" is executed.

> setmouse on
> setmouse *"Help"=6 ! Help request
> setmouse *"Quit"=4 ! Quit
> setmouse *"Calc"="CALL ""CALC"""

## Format 3

Use Current Window Size

SETMOUSE [*]@(*){ | :} expression

The first optional * (asterisk) defines the mouse event as being for all windows instead of just the current window. Use the second * (asterisk) in this format to define the mouse region as equal to the dimensions of the current window.

## Format 4

Clear All Settings

SETMOUSE CLEAR

Use this format to remove all previously defined SETMOUSE regions.

## Format 5

Enable/Disable Mouse

SETMOUSE {ON | OFF}

Use SETMOUSE ON to enable the mouse or SETMOUSE OFF to disable it.

When SETMOUSE OFF is used, mouse signals in the menu bar, tool bar and status bar regions of a window are ignored. (Windows Only)

The ON | OFF state is reflected in the mse(1,1) system variable, as in the following example:

Example:

> print hta(mid(mse,1,1))
> 00
> setmouse off
> print hta(mid(mse,1,1))
> FF

(Support for SETMOUSE OFF to ignore mouse signals in the stated regions was added in PxPlus 2018.)

## See Also

MSE Mouse State