Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / EDITORES / TSCREDD2.ZIP / SCRDISK3.EXE / MANUAL.PT2 < prev next >

Wrap

Text File | 1990-04-29 | 39.8 KB | 1,025 lines

Page I-7 MOUSE SUPPORT........................................(Section M) How to use the Mouse section of the manual............... M-1 A word to the wise about using Turbo ScrEdit mouse....... M-1 How Turbo ScrEdit Mouse Support Works.................... M-2 Compiler Directives to include/exclude mouse procedures.. M-2 Example Programs: Pascal................................................ M-3 C......................................................M-4 Global Variables and Constants........................... M-5 Initializing the mouse procedures........................ M-6 S_ActivateMouse.......................................... M-6 S_AnalizeMouse........................................... M-7 S_DisableMouse........................................... M-8 S_HideMouse.............................................. M-9 S_RemoveMouse............................................ M-9 S_ResetMouse............................................. M-10 S_ResetMouseFlags........................................ M-10 S_RestoreMouse........................................... M-11 S_SetMouseCursor......................................... M-12 S_SetMouseEvent.......................................... M-13 S_SetMouseRange.......................................... M-14 S_ShowMouse.............................................. M-15 Alphabetical listing of Mouse System global variables: S_Buttons...........................................3 4 5 S_MouseInstalled....................................3 4 5 S_MouseEvent..(Pascal)..............................3 4 5 7 S_Ms-MouseEvent (C).................................3 4 5 7 10 S_MsLeftPressed.....................................3 4 5 7 10 S_MsLeftReleased....................................3 4 5 7 10 S_MsMiddlePressed...................................3 4 5 7 10 S_MsMiddleReleased..................................3 4 5 7 10 S_MsRightPressed....................................3 4 5 7 10 S_MsRightReleased...................................3 4 5 7 10 S_MsRow.............................................4 5 7 S_MsColumn..........................................3 4 5 7 Page M-1 How to use the MOUSE SUPPORT manual. ----------------------------------------------------------------- This portion of the "Turbo ScrEdit User Manual" explains each of the procedures used to interact with the mouse device driver, and provides an example of the procedures usage in the context of a program. Pages M-3 and M-4 contain small program listings of "C" and PASCAL coding that use most of the Turbo ScrEdit mouse processing functions. The files "TestMous.Pas" and "TestMous.C" that came in your Turbo ScrEdit package, contain the actual working programs listed here. Also You will find a thorough walk through and explanation of these programs in Part II of the Turbo ScrEdit Tutor. In the program listings on pages M-3 and M-4 you will find that certain lines of code have been marked with 20 indicators, "==1>" through "==20>". Each procedural reference in this section of the manual describes one of the mouse functions, procedures, or global variables. In each description you will find a reference to one of these 19 markers as the programming example that will allow you to see how the particular function or variable is used in context in a program. There are three procedures that are not included in the programming example: S_RemoveMouse, S_RetoreMouse, and S_ResetMouse. These procedures are explained in there section and no example of their usage is provided. A Word to the wise about using Turbo ScrEdit Mouse procedures. ----------------------------------------------------------------- To avoid loosing your work, before beginning to program with the mouse procedures BE SURE TO SET YOU PROGRAMMING ENVIRONMENT AUTO SAVE OPTION TO "ON" SO IT WILL AUTOMATICALLY SAVE THE PROGRAM THAT YOU HAVE SPENT HOURS WORKING ON BEFORE IT EXECUTES... Under certain conditions while testing new programs, the mouse procedures can cause your system to HANG so only rebooting will get it going again. Turbo ScrEdit Mouse uses the mouse driver event handler to monitor for mouse activity. The benefit of using the mouse event handler is that the mouse driver interrupts your program when the specified mouse event occurs so your program does not have to make frequent interrupt calls to check for mouse activity. The disadvantage to using the mouse event handler is that your program must pass the mouse driver a memory location that it is to call when the specified mouse event occurs. This memory location is expected to have some kind of a programmed procedure that can handle the mouse event and then return to the mouse driver via a far return. When your program ends and another program is loaded into memory, the mouse event handler will not realize this and will respond to a mouse event and execute any object code that is in memory at the time. Page M-2 How Turbo ScrEdit Mouse Support Works. ----------------------------------------------------------------- Turbo ScrEdit Mouse Support (TSMS) is designed to work with the MicroSoft and LogiTech mouse device drivers and supports two or three button mouse devices. TSMS takes advantage of the mouse driver event task handler (Interrupt $33, function 12.) The procedure S_SetMouseEvent passes the mouse driver the memory address of the procedure S_SetMouseFlags and a bit pattern representing the events to be monitored, such as a button being pressed or the mouse device being moved. See the complete description of S_SetMouseEvent in this document. Once programmed, the mouse driver monitors the mouse activity until one of the specified events occurs. It then interrupts your program and performs a far call to the procedure S_SetMouseFlags, passing the status of the mouse to your program in cpu registers. If you look at the procedure S_SetMouseFlags you will see that it stores the cpu registers and set a global boolean variable "S_MouseEvent" to true. It is important to understand that the mouse is always active in the background, but THE MOUSE CURSOR WHEN SET TO VISIBLE IS ONLY SEEN ON THE SCREEN WHILE TURBO SCREDIT IS WAITING FOR A KEY TO BE PRESSED. As soon as a key is pressed or a mouse event occurs, the mouse cursor will disappear from the screen while Turbo ScrEdit processes the keystroke. As a rule Turbo ScrEdit handles the keystroke quick enough that the mouse cursor appears to remain on the screen. Compiler Directive to include/exclude mouse procedures. ----------------------------------------------------------------- MOUSE ------------------------------------------------------------- This compiler directive is used to determine if the compiler will include the mouse procedures in the "C" object module or pascal unit created when the Turbo ScrEdit interface modules are compiled. Turbo Pascal: At the beginning of the source file ScrEdit.Pas you will find: {$Define MOUSE} Turbo C: Located in the global defines file "#defines.C" #define MOUSE Page M-3 Example of a PASCAL program using mouse calls: ---------------------------------------------------------------- ==1> uses Crt,Scredit,ScrMouse; Begin ClrScr;gotoxy(20,4); ==2> If Not S_MouseInstalled Then Begin WriteLn('Mouse Driver is not in memory!');Halt; End; ==3> WriteLn('Mouse Driver is ACTIVE and has ', S_Buttons:1,' buttons.'); Gotoxy(32,10);Writeln('Press ESC to end.'); ==4> S_ActivateMouse; ==5> S_SetMouseEvent('01111110'); ==6> S_ShowMouse; ==7> S_SetMouseRange(10,6,70,9); Repeat GoToxy(20,6); ==8> Write('Mouse Cursor Location.. Row:', S_MsRow:2,' Column:',S_MsCol:2); Gotoxy(10,8); ==9> If S_MsLeftPressed Then Write('[ Left Pressed ]') ==10> Else If S_MsLeftReleased Then Write('[ Left Released ]') Else Write('[ *** Left *** ]'); Gotoxy(50,8); ==11> If S_MsRightPressed Then Write('[ Right Pressed ]') ==12> Else If S_MsRightReleased Then Write('[ Right Released ]') Else Write('[ *** Right *** ]'); Gotoxy(30,8); ==13> If S_MsMiddlePressed Then Write('[ Middle Pressed ]') ==14> Else If S_MsMiddleReleased Then Write('[ Middle Released ]') Else Write('[ *** Middle *** ]'); ==15> S_ResetMouseFlags; S_NextKey; ==16> If S_MouseEvent Then ==17> S_AnalizeMouse; ==18> If S_F1 Then S_SetMouseCursor($00,$00,$07,$18); If S_F2 Then S_SetMouseCursor($77,$FF,$77,$00); Until S_Esc; ==19> S_HideMouse; ==20> S_DisableMouse; End. Page M-4 Example of a "C" program using mouse calls: ----------------------------------------------------------------- #include <stdlib.h> #include <conio.h> ==1> #include "scredit.h" void main() { clrscr();gotoxy(20,4); ==1> S_Init(); ==2> if (!S_MouseInstalled) { cprintf("Mouse Driver is not in memory!\n\c");exit(0); } ==3> cprintf("Mouse Driver is ACTIVE and has %d buttons", S_Buttons); gotoxy(32,10);cprintf("Press ESC to end."); ==4> S_ActivateMouse(); ==5> S_SetMouseEvent("01111110"); ==6> S_ShowMouse(); ==7> S_SetMouseRange(10,6,70,9); while (!S_Esc) { gotoxy(20,6); ==8> cprintf("Mouse Cursor Location.. Row:%2d Column:%2d", S_MsRow,S_MsCol); gotoxy(10,8); ==9> if (S_MsLeftPressed) cprintf("[ Left Pressed ]"); ==10> else if (S_MsLeftReleased) cprintf("[ Left Released ]"); else cprintf("[ *** Left *** ]"); gotoxy(50,8); ==11> if (S_MsRightPressed) cprintf("[ Right Pressed ]"); ==12> else if (S_MsRightReleased) cprintf("[ Right Released]"); else cprintf("[ *** Right ***]"); gotoxy(30,8); ==13> if (S_MsMiddlePressed) cprintf("[Middle Pressed ]"); ==14> else if (S_MsMiddleReleased) cprintf("[Middle Released]"); else cprintf("[ *** Middle ***]"); ==15> S_ResetMouseFlags(); S_NextKey(); ==16> if (S_Ms->MouseEvent) ==17> S_AnalizeMouse(); ==18> if (S_F1) S_SetMouseCursor(0x00,0x00,0x07,0x18); if (S_F2) S_SetMouseCursor(0x77,0xFF,0x77,0x00); } ==19> S_HideMouse(); ==20> S_DisableMouse(); } Page M-5 Global Variables and Constants. ----------------------------------------------------------------- S_Buttons............ Program example ==3> (Integer)Indicates the number of buttons on the mouse. This field receives a value when mouse initialization is performed. S_MouseInstalled..... Program example ==2> (Boolean) Indicates if the mouse driver was found in memory during initialization. True = Mouse driver is active in memory. False = Mouse drive is not in memory. (Pascal) S_MouseEvent (C) S_Ms->MouseEvent. Program example ==16> (Boolean) Indicates to your program when a mouse event has occurred. See S_AnalizeMouse for further details on how to use this field. S_MsLeftPressed...... Program example ==9> (Boolean) True if the left mouse button has been pressed. S_MsLeftReleased..... Program example ==10> (Boolean) True if the left mouse button has been released. S_MsRightPressed..... Program example ==11> (Boolean) True if the right mouse button has been pressed. S_MsRightReleased.... Program example ==12> (Boolean) True if the right mouse button has been released. S_MsMiddlePressed.... Program example ==13> (Boolean) True if the middle mouse button has been pressed. S_MsMiddleReleased... Program example ==14> (Boolean) True if the middle mouse button has been released. S_MsCol S_MsRow.............. Program example ==8> These field have two uses: 1 - First to returns the screen row and column position of the mouse cursor when the most recent mouse event occurred. 2 - To specify a new row and column position for the mouse cursor. See the details for procedures S_ShowMouse and S_MoveMouse. Page M-6 Initializing the mouse procedures. ----------------------------------------------------------------- It is important the Turbo ScrEdit Mouse system be properly initialized before you attempt to use them. Initialization is different depending on the language that you are programming with. Program example ==1>. Turbo Pascal: Initialization of the mouse unit is automatic when the program is loaded. Turbo C: Initialization is perform when you initialize Turbo ScrEdit procedures using "S_Init()". As with using Turbo ScrEdit procedures you MUST PERFORM S_INIT() BEFORE YOU ATTEMPT TO USE ANY MOUSE SUPPORT PROCEDURES. FAILURE TO DO SO WILL RESULT IN UNPREDICTABLE RESULTS. The best way to avoid problems is to perform S_Init() as one of the first steps in a program. S_ActivateMouse ---------------------------------------------------------------- Program example ==4> Function: Activates the mouse and re-establishes the most recent mouse event criteria (See S_SetMouseEvent for details on the EVENT HANDLER). Remarks: There are two occasions during the execution of your program that you will want to perform this procedure. 1 - Once the mouse procedures have been initialized they are ready to be used. However, before any mouse call will render any results the mouse system must be activated. 2 - Any time after the S_DisableMouse procedure has been used that you wish to resume mouse event processing. (See S_DisableMouse and S_SetMouseEvent). Defined for Turbo C as: void S_ActivateMouse() Defined for Turbo Pascal as: Procedure S_ActivateMouse; Parameter description: None. Page M-7 S_AnalizeMouse ---------------------------------------------------------------- Program example ==17> Function: Analyzes the register values stored when the most recent mouse event occurred and sets global variables to reflect the status of the registers. Remarks: When a mouse event occurs, the mouse driver interrupts your program by calling S_SetMouseFlags and passes the mouse status information to your program in cpu registers. S_SetMouseFlags stores the values of the cpu registers and sets the boolean variable S_MouseEvent (S_Ms->MouseEvent for C) to TRUE. At any point in your program when S_MouseEvent tests TRUE you can perform a call to S_AnalizeMouse and it will examine the stored register values and set the the global boolean variables to indicate which mouse event has occurred. You can then examine the global variables to see if a button has been pressed or released, and the current row and column position of the mouse cursor when the last event occurred. ** NOTE ** It is important to understand that this call ACCUMULATES button status information. You must perform the routine S_RestMouseFlags after you have finished analyzing the mouse event to clear the button indicators. See S_SetMouseEvent for details on the EVENT HANDLER. Also see S_ResetMouseFlags for more details. Variables that are set by this procedure: S_MsRow (returns current mouse cursor row) S_MsCol (returns current mouse cursor col) S_MsLeftPressed S_MsLeftReleased S_MsRightPressed S_MsRightReleased S_MsMiddlePressed S_MsMiddleReleased (Pascal) S_MouseEvent (set to false) (C) S_Ms->MouseEvent (set to false) Defined for Turbo C as: void S_AnalizeMouse(void) Defined for Turbo Pascal as: Procedure S_AnalizeMouse; Parameter description: None. Page M-8 S_DisableMouse ---------------------------------------------------------------- Program example ==19> Function: Disables the mouse functions. Remarks: When this procedure is called the mouse status is set to invisible, the mouse is removed from the screen, the mouse event handler is disabled. When the mouse is disabled calling other mouse routines will have no visible effect until the mouse is reactivated. See S_Activate mouse for details on reactivating the mouse. *** IMPORTANT NOTE *** Turbo "C" programmers.. It is very important that you disable the mouse driver before your program ends normally or otherwise. Failure to do so will leave the current mouse event handler active in memory and programmed to respond when the specified mouse event occurs. The mouse driver will blindly call the memory address that it is programmed to use. What ever codes are in memory it will try to execute. IN THE EVENT THAT YOUR PROGRAM ENDS ABNORMALLY DURING TESTING, BE VERY CAREFUL NOT TO MOVE THE MOUSE OR PRESS ANY MOUSE BUTTONS. Turbo Pascal programmers.. Turbo Pascal has facilities used by Turbo ScrEdit that handle disabling the mouse when the program ends normally or abnormally. Defined for Turbo C as: void S_AnalizeMouse(void) Defined for Turbo Pascal as: Procedure S_AnalizeMouse; Parameter description: None. Page M-9 S_HideMouse ---------------------------------------------------------------- Program example ==18> Function: Removes the mouse cursor from the screen. Remarks: This procedure causes the mouse cursor to become invisible on the screen. Event though the mouse cursor is not visible on the screen it will still move when the mouse is moved, and all buttons will still be detected and able to cause the mouse event to occur. See S_SetMouseEvent and S_AnalizeMouse for more details on mouse event processing. See S_ShowMouse for details on making the mouse cursor visible on the screen. Defined for Turbo C as: void S_HideMouse(void) Defined for Turbo Pascal as: Procedure S_HideMouse; Parameter description: None. S_RemoveMouse ---------------------------------------------------------------- Program example - None Function: Calls function 2 of the mouse driver and removes the mouse cursor from the screen. Remarks: This procedure will remove the mouse cursor from the screen. If you use this call it will be when your program has used your languages I/O procedures to interact with the user of the program and you are ready to resume using Turbo ScrEdit procedures. See S_RestoreMouse for more information. You will not normally use this procedure. It is used by Turbo ScrEdit in the S_GetKey routine. The mouse cursor is only visible when Turbo ScrEdit is waiting for a key to be pressed. Each time a key is pressed the mouse will blink or disappear while Turbo ScrEdit handles the key. This is necessary so that the mouse cursor character does not get pulled into Turbo ScrEdit fields and window backgrounds when video memory is read. Defined for C as: void S_RemoveMouse(void); Defined for Pascal as: Procedure S_RemoveMouse; Parameter description: None. Page M-10 S_ResetMouse ---------------------------------------------------------------- Program example - None. Function: Calls function 0 of the mouse driver to reset the mouse driver to its default initialized state. Remarks: This procedure resets the mouse driver to its original initialized state. The mouse cursor is centered in the screen, the event handler is reset, all button status flags are reset. Generally you will not need to use this procedure. Defined for C as: void S_ResetMouse(void); Defined for Pascal as: Procedure S_ResetMouse; Parameter description: None. S_ResetMouseFlags ---------------------------------------------------------------- Program example ==15> Function: Sets all mouse button status boolean variables to FALSE. Remarks: Resets S_MsLeftPressed S_MsLeftReleased S_MsRightPressed S_MsRightReleased S_MsMiddlePressed S_MsMiddleReleased Defined for C as: void S_ResetMouseFlags(void); Defined for Pascal as: Procedure S_ResetMouseFlags; Parameter description: None. Page M-11 S_RestoreMouse ---------------------------------------------------------------- Program example - None. Function: Calls function 1 of the mouse driver and makes the mouse cursor visible on the screen. Remarks: Use this procedure when you wish have the mouse cursor visible while using you language's screen and keyboard I/O procedures (such as readln, writeln, readkey, or printf, scanf, bioskey, ect) to interact with the user of your program. See S_RemoveMouse for directions on removing the mouse cursor before resuming the use of Turbo ScrEdit procedures. Normally You will not use this procedure. It is used by Turbo ScrEdit in the S_GetKey routine. The mouse cursor is only visible when Turbo ScrEdit is waiting for a key to be pressed. Each time a key is pressed the mouse will blink or disappear while Turbo ScrEdit handles the key. This is necessary so that the mouse cursor character does not get pulled in to Turbo ScrEdit fields and window backgrounds. Defined for Turbo C as: void S_RestoreMouse(void); Defined for Turbo Pascal as: Procedure S_RestoreMouse; Parameter description: None. Page M-12 S_SetMouseCursor ---------------------------------------------------------------- Program example ==18> Function: Calls function 10 of the mouse driver and sets the appearance and attributes of the mouse cursor. Remarks: This procedure allows you to change the mouse cursor to suit your needs. When the mouse procedures are initialized the mouse cursor is defined as a light gray arrow (ASCII char 18 hex) on a black background. Using this procedure you may change the cursor to any ASCII character on any combination of background and foreground colors. See examples for more details. Defined for Turbo C as: void S_SetMouseCursor(unsigned char mask1L, unsigned char mask1H, unsigned char mask2L, unsigned char mask2H) Additional Example of usage: {set light gray arrow on black background} S_SetMouseCursor(0X00,0X00,0X07,0X18); {set to translucent block cursor} S_SetMouseCursor(0X77,0XFF,0X77,0X00); Defined for Turbo Pascal as: Procedure S_SetMouseCursor(Mask1L, Mask1H, Mask2L, Mask2H:Byte); Additional Example of usage: {set light gray arrow on black background} S_SetMouseCursor($00,$00,$07,$18); {set to translucent block cursor} S_SetMouseCursor($77,$FF,$77,$00); Parameter description: The mouse driver uses two software cursor masks, MASK1 the screen mask, and MASK2 the cursor mask, to control the appearance of the cursor on the screen. Each mask is divided into the high and low order bytes, thus Mask1L and Mask1H, and Mask2L and Mask2H. For use in text mode, you will usually pass zero values in mask1 (see examples.) Mask2 is used to specify the cursor character and color: Mask2L - specifies the color of the cursor character in the format of $BF (Pascal) 0xFB (C): Where 'F' is a foreground color code 0 - 7 and 'B' is a background color code 0 - F Mask2H - specifies the ASCII character to be used as the cursor character. Where $18 (0x18) is the up arrow character. $02 (0x02) is an inverse smiley face. $40 (0x40) is an @ sign. Page M-13 S_SetMouseEvent ---------------------------------------------------------------- Program example ==5> Function: Calls function 12 of the mouse driver and programs the event task that the mouse will monitor for. Remarks: This procedure is used to tell the mouse driver what mouse activity you want reported to your program. The global variable S_MouseEvent in pascal, or S_Ms->MouseEvent in C will test TRUE when one of the requested events has occurred. When S_Ms->MouseEvent tests true, call the procedure S_AnalizeMouse to set the global program flags that indicate the action or actions that triggered the mouse event. Defined for Turbo C as: void S_SetMouseCursor(char *Bits); Defined for Turbo Pascal as: Procedure S_RemoveMouse(Bits:S_Str8); Parameter description: This procedure accepts a string of 8 characters as an argument. Each of the 8 characters represents a bit in a mask that is passed to the mouse driver to tell it what mouse actions are to trigger an event: Position 1 = Monitor for cursor movement 2 = Monitor for LEFT button pressed. 3 = Monitor for LEFT button released. 4 = Monitor for RIGHT button pressed. 5 = Monitor for RIGHT button released. 6 = Monitor for MIDDLE button pressed. 7 = Monitor for MIDDLE button released. 8 = not used. Coding a '1' in any of the 8 positions of the mask will set monitoring for the corresponding mouse action. Any character in the mask other than a "1" sets monitoring for the corresponding function to passive. ** VERY IMPORTANT NOTE FOR C USERS ** During initialization the mouse event handler is passed the address of a procedure in the mouse interface module. The mouse driver does not check to see if the address it has is a valid address or not, it simply performs a far call to the stored address any time one of the requested mouse events occur. If your program ends abnormally before you can perform the procedure S_DisableMouse, the mouse driver will continue to monitor for an event. Consequently your Page M-14 computer can hang if a mouse event occurs after your program is terminated and some other application is loaded into memory. To avoid this problem, always perform S_DisableMouse at the end of your program. This routine sets the mouse event handler to monitor for '0000000' events. While testing a program you may want to keep a program around that simply calls S_ActivateMouse followed by a call to S_DisableMouse. S_SetMouseRange ---------------------------------------------------------------- Program example ==7> Function: Calls function 7 and 8 of the mouse driver and sets the row and column ranges for mouse cursor movement. Remarks: Use this procedure to "fence in" the mouse curser. This procedure establishes a window that the mouse cursor can move around in. Once established the mouse cursor will not move beyond the borders of the area defined. Defined for Turbo C as: void S_SetMouseCursor(unsigned char TopCol, unsigned char TopRow, unsigned char BotCol, unsigned char BotRow) Defined for Turbo Pascal as: Procedure S_RemoveMouse(Top_Col, Top_Row, Top_Col, Top_Row:Byte); Parameter description: TopCol - An integer value in the range of 1 to 80 that specifies the top Left Column of the area of the screen that the mouse is to be confined to. TopRow - An integer value in the range of 1 to 25 that specifies the top left row of the area of the screen that the mouse is to be confined to. BotCol - An integer value in the range of 1 to 80 that specifies the bottom right column of the area of the screen that the mouse is to be confined to. BotRow - An integer value in the range of 1 to 25 that specifies the bottom right row of the area of the screen that the mouse is to be confined to. Page M-15 S_ShowMouse ---------------------------------------------------------------- Program example ==6> Function: Moves the mouse cursor to the row and column specified in S_MsRow and S_MsCol, and makes the mouse cursor visible on the screen. Remarks: It is important to understand that the mouse cursor will only be visible on the screen while Turbo ScrEdit is waiting for a key to be pressed. As soon as a key stroke is detected, the mouse cursor is removed from the screen. This procedure has two functions. 1 - It sets the status of the mouse to 'visible' so it will be displayed during the next call to S_GetKey. 2 - The mouse cursor is moved to the row and column coordinates specified by S_MsRow and S_MsCol. See S_HideMouse for details on how to set the mouse status to 'invisible. Defined for Turbo C as: void S_ShowMouse(void) Defined for Turbo Pascal as: Procedure S_ShowMouse; Parameter description: