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.
Usage
CALL "W$MOUSE" USING OP-CODE, parameters, GIVING MOUSE-STATUS
Parameters
OP-CODE Numeric parameter
This indicates the desired operation. Level 78 symbolic names for these operations can be found in the file "acugui.def".
MOUSE-STATUS A numeric data item
Holds the return value from W$MOUSE. This is only used with the ENABLE-MOUSE, TEST-MOUSE-PRESENCE, and GET-MOUSE-SHAPE operations.
OP-CODE parameters
Vary depending on the OP-CODE chosen
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". 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, 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-1. 03 MOUSE-COL PIC 9(4) COMP-1. 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 - 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.
find-mouse-menu-row.
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 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 The second parameter 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 |
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, if the mouse is outside of the legal boundaries, the GET-MOUSE-STATUS and GET-MOUSE-SCREEN-STATUS functions no longer return zero in the row and column fields. 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 When the second parameter is "1", this opcode turns the mouse pointer into a help-mode pointer--the mouse is captured and the pointer takes the shape of a question mark. When the second parameter is "0", the help-mode state is turned off--the mouse is released and the pointer returns to its default shape. This option is only supported under MS Windows.