The runtime system contains a library routine called "W$MOUSE" that you can use to control the behavior of the mouse. You use this routine with the CALL statement in your COBOL program.
Before you use "W$MOUSE" to respond to mouse actions, be sure that you have unmasked the actions you want to notice.
The first parameter you pass to "W$MOUSE" is an operation code. This code tells "W$MOUSE" what to do. The number and type of the remaining parameters depend on the operation code. All parameters are passed by REFERENCE (the default in COBOL).
The valid operation codes are defined in the COPY file "acugui.def". So if you're going to use the W$MOUSE routine, add this statement to the Working-Storage section of your program:
copy "acugui.def"
The operation code can be one of the following:
ENABLE-MOUSE
Turns on the mouse on character-based systems. (By default the mouse is invisible.) The value of RETURN-CODE is set to "1" if a mouse is present, "0" if no mouse is found. (Takes no additional parameters.) You can also turn on the mouse with the COBOL configuration variable "USE-MOUSE." Set USE-MOUSE to a non-zero value before the runtime starts.
On some machines there is an appreciable delay when the mouse is enabled.
Under graphical environments such as Windows, a call to W$MOUSE using ENABLE-MOUSE is not necessary--it sets the value of RETURN-CODE properly, but no other action occurs, because the mouse is always enabled in these environments.
TEST-MOUSE-PRESENCE
Used to detect the presence of a mouse. The value of RETURN-CODE is set to "1" if a mouse is available on the system. It is set to "0" if no mouse is present. (Takes no additional parameters.) Note that on character-based systems the mouse must be enabled before its presence can be detected. So if you haven't enabled the mouse (see ENABLE-MOUSE above), RETURN-CODE will have a value of "0".
GET-MOUSE-STATUS
Returns information about the mouse's location and the state of each of its buttons. You must pass a group item with the following structure:
01 MOUSE-INFO.
03 MOUSE-ROW PIC 9(4) COMP-4.
03 MOUSE-COL PIC 9(4) COMP-4.
03 LBUTTON-STATUS PIC 9.
03 MBUTTON-STATUS PIC 9.
03 RBUTTON-STATUS PIC 9.
The file "acugui.def" contains a group item with this layout. The routine fills in this structure with data about the mouse. Each of the three "status" fields is set to "1" if the corresponding button is depressed. Otherwise, they are set to zero. The row and column fields are set to the location of the mouse within the current ACUCOBOL-GT window. If the mouse is outside of the current window, then these values are set to zero.
Here's an example of a call to "W$MOUSE" that returns the menu item the mouse is pointing to:
find-mouse-menu-row.
* find-mouse-menu-row - returns (in mouse-row)
* the menu item that the mouse pointer is currently
* on. If the mouse is not on a menu item, it
* returns zero.
call "w$mouse" using get-mouse-status, mouse-info
if
mouse-row >= menu-row and
mouse-row < menu-row + num-menu-items * 2
compute mouse-row = mouse-row - menu-row + 1
else
move zero to mouse-row.
After an ACCEPT statement is executed, all CALLs to "W$MOUSE" pertain to that ACCEPT statement, until another ACCEPT is executed. So you always get the right mouse status. By synchronizing the mouse actions with the appropriate exception values, the runtime ensures that you process the mouse correctly.
GET-MOUSE-SCREEN-STATUS
This function is the same as the GET-MOUSE-STATUS function except that the row and column coordinates are relative to the application's virtual screen (the drawing space allocated to the application), instead of the current window. If the mouse is not located anywhere in the application's window, then the coordinates are set to zero.
SET-MOUSE-POSITION
You must pass a group item with the same structure as described under GET-MOUSE-STATUS. The mouse is placed at the coordinates named by MOUSE-ROW and MOUSE-COL, relative to the current ACUCOBOL-GT window. The button-status fields are not used.
SET-MOUSE-SCREEN-POSITION
This is the same as SET-MOUSE-POSITION, except that the position is relative to the application's virtual screen.
SET-MOUSE-SHAPE
You must pass a second parameter that defines the desired shape of the mouse pointer. The shape is changed immediately, even if the mouse has not been moved. The possible values are:
- ARROW-POINTER The default arrow shape
- BAR-POINTER A vertical bar
- CROSS-POINTER Cross hairs
- HELP-POINTER A question mark
- WAIT-POINTER An hourglass
These are defined in "acugui.def". Note that the runtime system changes the shape of the mouse when you are using automatic mouse handling. When an ACCEPT statement finishes execution, the last shape defined by SET-MOUSE-SHAPE is restored.
SET-DELAYED-MOUSE-SHAPE
This is identical to SET-MOUSE-SHAPE, except that the mouse pointer is not changed immediately. Instead, it is changed as soon as the user moves it. The automatic mouse handler uses this function to provide a smoother mouse appearance.
GET-MOUSE-SHAPE
The value of RETURN-CODE is set to the current mouse shape. If SET-DELAYED-MOUSE-SHAPE is in effect, waiting for the mouse to move, then the delayed shape is returned. (Takes no additional parameters.)
CAPTURE-MOUSE
Normally, only mouse actions that occur within the application's virtual screen are processed by the runtime system. (The virtual screen is the drawing space allocated to the application.) Actions that occur outside of this space are handled by other applications or by the environment. The CAPTURE-MOUSE function causes the runtime to process all mouse messages, regardless of where they occur. This should be done only in special cases, because it prevents the user from using the mouse in any other application. Normally, you capture the mouse only when the user is marking or dragging some object on the screen. By capturing the mouse, you can control the action even if the user accidentally moves the mouse outside of the application. (Takes no additional parameters.)
When the mouse is captured, the GET-MOUSE-STATUS and GET-MOUSE-SCREEN-STATUS functions no longer return zero in the row and column fields if the mouse is outside of the legal boundaries. Instead, the row and column fields contain the nearest legal coordinate to the mouse's actual position.
RELEASE-MOUSE
This reverses the effects of the CAPTURE-MOUSE function. You must call this sometime after calling CAPTURE-MOUSE, or the environment will not be able to use the mouse again. (Takes no additional parameters.)
SET-MOUSE-HELP
Depending on the value of the second parameter, this option sets or releases the help-mode pointer. When the value of the second parameter is "1", the mouse pointer is captured and its shape is changed to a question mark. When the second parameter is "0", the mouse is released and the pointer returns to its default shape. This option is only supported under MS Windows.