VT100.net VT330/VT340 Programmer Reference Manual

15 Using a Mouse or Tablet

Locator Devices

This chapter describes how to program your VT300 terminal for use with a locator device. You use a locator device to move the cursor and select position coordinates on the screen. With a locator device, you can easily move the graphics input cursor to a specific point or enter data to application programs.

There are two locator devices you can use with your terminal, a mouse or graphics tablet. You connect the device to the rear of the terminal. These devices use a serial line input/output format with the micro-DIN connector.

VSXXX-AA Mouse

Digital's VSXXX-AA mouse is a small handheld device, with three buttons on top and a roller ball on the bottom. You can write applications that use the mouse as an input device. You can use the three buttons on the mouse to send data to an application.

The roller ball controls cursor movement. When you move the mouse on a flat surface, the roller ball turns. The cursor moves in the direction you move the mouse. You can move the cursor in any direction, and place it anywhere on the screen.

If you pick the mouse up, the cursor stops moving on the screen. The cursor stays at this point until you put the mouse down and move the roller ball along the surface again.

VSXXX-AB Graphics Tablet

Digital's VSXXX-AB tablet has three parts.

The tablet has a flat, square surface similar to a tabletop. To move the cursor, you move the puck or stylus over this surface. The tablet has a position-sensitive grid that senses the position of the puck or stylus.

The puck is a handheld device with crosshair markings that help you select precise coordinates on the tablet. The puck has four buttons that serve the same purpose as the buttons on the mouse. You can program the buttons to send position reports when pressed or released.

The stylus is a handheld device that resembles a pen. The stylus has two buttons, a barrel and a tip. The barrel is a button on the side of the pen you can press to send data to an application. You activate the tip by pressing the pen down onto the tablet surface.

To move the cursor, you move the puck or stylus over the tablet surface. You do not have to touch the surface, but the tablet or stylus must be within 0.65 cm (0.25 in) of the surface to move the cursor. When the puck or stylus is close enough to the tablet surface to move the cursor, the puck or stylus is in proximity with the tablet.

If you remove the puck or stylus from the tablet surface while the tablet is plugged in, then the VT300 uses the last known tablet position.

Unlike the mouse, the tablet is an absolute positioning device. The layout of the tablet corresponds roughly to the layout of the screen. The next section explains tablet-to-screen mapping.

Tablet-to-Screen Mapping

The VT300 screen maps to the bottom two-thirds of the tablet surface. Applications cannot use the top third of the tablet. The points at the top third of the tablet map to the top visible scan line of the screen.

The complete horizontal extent of the tablet's coordinate system maps to the complete horizontal extent of the screen. However, the tablet has borders to compensate for the difference between the screen's coordinate system and the tablet's system.

The vertical extent at the bottom of the tablet's coordinate system maps to the complete vertical extent of the screen. The tablet must also have borders in the vertical direction.

The origin of the tablet's coordinate system is at the lower-left corner of the tablet surface, so the lower Y coordinates on the tablet map to the horizontal extent of the screen. The upper Y coordinates map to the top scan line of the screen.

Locator Cursor

The VT300 can use any one of the following cursor styles with a locator device.

Crosshair ReGIS, 4010/4014 (default input cursor)
Diamond ReGIS (default output cursor)
Rubber band line ReGIS
Rubber band box ReGIS
User-defined ReGIS

In ReGIS mode, software can select the cursor style by using the cursor control option to the screen command: S(C(I)). See Chapter 2 for details on the ReGIS screen command.

In 4010/4014 mode, the terminal only uses the crosshair cursor style.

Locator Buttons

In graphics input mode, pressing a locator button sends a cursor position report to the host. The mouse has three buttons. The graphics tablet includes a puck with four buttons, and a stylus with a barrel button and a tip switch. All the buttons serve the same purpose – they send locator data to the host.

A locator button can be in one of two states, up (released) or down (pressed). A change from one state to another is called a transition. You can program the buttons to send reports in three different ways.

You can also program the locator buttons to send specific codes or control functions to the host. Programming locator buttons is described later in this chapter. Table 15-1 shows the default codes that each button sends when pressed or released.

Table 15-1 Default Locator Button Codes
Button Device* Code (Pressed) Code (Released)
1 (left) mouse, puck, or stylus barrel CSI 241 ~ no report
2 (middle) mouse, puck, or stylus tip CSI 243 ~ no report
3 (right) mouse or puck CSI 245 ~ no report
4 (fourth) puck CSI 247 ~ no report

If the host requests a report when none of the buttons are in use, the terminal responds with a null-button code: CSI 240 ~.

Entering Data with the Locator Device

Before you can enter data with a locator device, the terminal must be in a graphics input mode. You can use three different graphics input modes with the VT300.

ReGIS One-Shot Graphics Input Mode

An application can select this mode with the following ReGIS command.

R(I0)

In one-shot mode, the terminal suspends processing of received characters and commands. The terminal buffers all received characters, until it leaves one-shot mode.

When the terminal enters graphics input mode, the input cursor appears on the screen.

Moving the Graphics Cursor

You can move the input cursor around the screen by moving the locator device.

Mouse
The input cursor moves as you move the mouse over a flat surface.

Tablet
The input cursor moves as you move the stylus or puck across the tablet surface.

Arrow Keys
The input cursor moves as you press the corresponding arrow key on the keyboard. If a mouse is connected to the locator port, you can use the arrow keys or the mouse interchangeably to move the cursor. If a tablet is connected, you can use the arrow keys to move the cursor only when the puck or stylus is not in proximity with the tablet surface.

Requesting a Cursor Position Report

In one-shot mode, the terminal cannot send a position report until the application sends a request to the terminal. You use the ReGIS report position interactive command to request a position report.

R(P(I))

After sending the report position interactive command, the application does not receive a report until you press an active key or locator button.

Sending a Cursor Position Report

You can send a cursor position report from the keyboard or locator device.

Mouse Press any mouse button.
Tablet Press any puck, or stylus button.
Keyboard Press any non-arrow key that is active.

When you send a report, the following actions occur.

  1. If you use the keyboard
    The terminal sends the character code or control function of the key pressed to the host.

    If you use the mouse or tablet
    The terminal sends the code of the button pressed to the host. Table 15-1 lists the default codes. Digital's mouse has three buttons, the tablet's puck has four.

    Your application can redefine the codes that the locator buttons send to the host. User-defined codes override the default codes. See "Programming Locator Device Buttons" later in the chapter.

  2. The terminal sends the position report.
    The terminal sends the current coordinates of the input cursor to the host. The terminal sends this report as an absolute bracketed extent in ReGIS coordinates (such as [X,Y]).

  3. The terminal exits one-shot mode.
    The graphics input cursor disappears from the screen when the terminal exits graphics input mode.

ReGIS Multiple Graphics Input Mode

An application can select this mode with the following ReGIS command.

R(I1)

In multiple mode, the user moves the cursor and sends reports as in one-shot mode. Multiple mode differs from one-shot mode in the following ways.

Sending a Cursor Position Report

In multiple mode, there are two ways for the application to receive a report.

Notes on Multiple Mode

ReGIS Locator Reports

Locator reports begin with the code(s) of the active non-arrow key or locator button pressed. Following this code is the current position of the input cursor. The terminal sends the input cursor position as an absolute bracketed extent in user coordinates. The report ends with the carriage return character (CR).

The following list shows some examples of locator reports and their meaning.

Synchonizing Locator Reports Between the Terminal and Application

The way you synchronize input cursor position reports between the terminal and your application depends on whether the terminal is in one-shot graphics input mode, or multiple graphics input mode.

In One-Shot Mode

In one-shot mode, the terminal cannot send a report until it receives the ReGIS R(P(I)) command. To synchronize reports, your application must keep count of the R(P(I)) commands sent to the terminal.

In Multiple Mode

In multiple mode, the terminal can send a report at any time. To synchronize reports, the application must be able to recognize the format of each ReGIS input cursor position report. See "ReGIS Locator Reports" earlier in this chapter for the report formats.

Tektronix Graphics Input (GIN) Mode

Tektronix GIN mode is available only when the terminal is in 4010/4014 mode. Tektronix GIN mode is similar to ReGIS one-shot mode. The cursor moves and the terminal sends reports as in ReGIS one-shot mode.

An application can select this mode with the following escape sequence.

ESC SUB
1/11 1/10

The only input cursor available in Tektronix GIN mode is the crosshair. See Chapter 13 for the format of the 4010/4014 mode position report.

Using a Locator Device with Dual Sessions

This section describes how a locator device acts in a dual-session environment. You may want to review the chapter on dual sessions (Volume 1, Chapter 14) before you continue.

Locator Device Attributes in a Dual-Session Environment

Programming Locator Device Buttons (DECLBD)

You can program the locator device buttons to send codes that are different from the default codes. Table 15-1 lists the default codes.

Programming locator buttons is similar to programming function keys on the keyboard (Volume 1, Chapter 11). You use a device control string containing button definitions.

There are three programmable buttons on Digital's mouse, four on the tablet's puck, and two on the tablet's stylus. The VT300 lets you program all the buttons on the device you use. Each button can send a different code when pressed or released.

The VT300 lets you program up to six characters for each transition (up or down).

The terminal does not save your locator button codes in nonvolatile RAM (NVR). When you turn off or reset the terminal, you lose any locator button codes you defined. Unlike user-defined keys (UDKs), you cannot program the locator buttons from set-up.

DECLBD Device Control String

You use the following device control string to define the function of locator buttons.

DCS Pc $ w Ky1/Std1/Stu1 ;...; Kyn/Stdn/Stun ST

where

DCS (9/0) introduces device control strings. DCS is a C1 control character that you can also express as ESC P (1/11 5/0) when coding for a 7-bit environment.

Pc is the clear parameter. Pc determines how the locator buttons are cleared.

Pc Meaning
0 or none Clear all button definitions before loading new values (default).
1 Clear one button at a time, before loading a new value.

NOTE: You can only use 6 characters per button transition (pressed or released).

$ w (2/4, 7/7) are the intermediate and final characters that identify this device control string as a DECLBD string.

Ky1/Std/Stu ; ... are the button definition strings.

Ky1 is the number of the button you are defining.

Ky1 Button Device
1 Left Mouse, puck, or stylus barrel
2 Middle Mouse, puck, or stylus tip
3 Right Mouse or puck
4 Fourth Puck only

/ (2/15) is the slash character. This character separates the button selector number, up button value, and down button value in each button definition.

Std is the down string value. This value represents the code the selected locator button sends when pressed. The value is a string of hex pairs, each representing one 8-bit character.

You can use hex values in the following ranges.

3/0 through 3/9 (0 through 9)
4/1 through 4/6 (A through F)
6/1 through 6/6 (a through f)

When you combine these hex values, you can represent any 8-bit code. You can use up to 6 characters (6 hex pairs) for each Std value.

Stu is the up string value. This value represents the code the selected locator button sends when released. You code this value the same as Std above.

; (3/11) is a separator character. This character separates each button definition string.

ST (9/12) is the string terminator and indicates the end of the DCS. ST is a C1 control character that you can also express as ESC \ (1/11, 5/12) when coding for a 7-bit environment.

Notes on DECLBD

Examples of Locator Button Definitions

Summary

Table 15-2 is a summary of the control functions and commands described in this chapter.

Table 15-2 Locator Command Summary
Name Command Function
ReGIS
One-shot graphics input mode R(I0)
  1. Selects one-shot mode.
  2. In multiple mode, exits multiple mode and selects one-shot mode.
Multiple graphics input mode R(I1) Selects multiple mode.
Request cursor position report R(P(I))

In one-shot or multiple mode, requests a cursor position report from the terminal.

In one shot mode, the terminal sends the report when you press a locator button.

In multiple mode, the terminal sends the report immediately. The terminal also sends a report when you press a locator button.

4010/4014 Mode
GIN mode ESC SUB Selects graphics input mode.
Programming Locator Device Buttons (DECLBD)

DCS Pc $ w Ky1/Std1/Stu1 ; ... ; Kyn/Stdn/Stun ST

where

Pc  =  clear parameter.
0 or none  =  clear all button definitions before loading new values (default).
1  =  clear one button at a time, before loading a new value.

NOTE: You can only use 6 characters per button transition (pressed or released).

Ky1/Std/Stu ; ... are the button definition strings.

Ky1 = number of the button you are defining.
Ky1 Button Device
1 Left Mouse, puck, or stylus barrel
2 Middle Mouse, puck, or stylus tip
3 Right Mouse or puck
4 Fourth Puck only
Std =

the code the selected locator button sends when pressed. The value is a string of hex pairs, each representing one 8-bit character.

You can use hex values in the following ranges.

3/0 through 3/9 (0 through 9)
4/1 through 4/6 (A through F)
6/1 through 6/6 (a through f)

Stu = the code the selected locator button sends when released. You code this value the same as Std above.