Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / EDITORES / TSCREDD2.ZIP / SCRDISK3.EXE / MANUAL.PT1 next >

Wrap

Text File | 1990-04-29 | 210.0 KB | 4,781 lines

Page I-1 Turbo ScrEdit procedures reference guide <C>opyright 1989 by iHn Systems ----------------------------------------------------------------- Disclaimer.................................................. 1 CONFIG.SYS requirments...................................... 2 If Turbo ScrEdit does not work.............................. 2 Preparing Turbo ScrEdit Interface for use in a program: Setting the compiler directives before compiling..... 2 COLORCHANGE...................................... 3 MOUSE............................................ 3 VALIDATE......................................... 4 Creating the Turbo Pascal Unit....................... 4 Creating the Turbo C Libraries....................... 5 How to include Turbo Scredit in your program: Turbo Pascal......................................... 6 Turbo C.............................................. 6 Using Turbo ScrEdit from within your program................ 7 An example of the smallest possible working program to use a Turbo ScrEdit screen........................ 7 Initialization: Initializing Turbo ScrEdit interface: S_Init....................................... 8 Initializing screens............................. 8 Opening a screen file for use: S_OpenScreenFile................................. 10 Loading a screen and displaying it: S_DelayScreen.................................... 10 S_LoadScreen..................................... 10 Closing a screen file: S_CloseScreen.................................... 11 Activating/Deactivating special fetures: The INSERT,CAPS,NUM LOCK,SCROLL LOCK status line S_ShowStatus................................. 13 Changing Status Line Colors: S_StBg................................... 13 S_StFg................................... 13 S_StLabelBg.............................. 13 S_StLabelFg.............................. 13 Continuous field help messages: S_AutoHelp................................... 14 Instant field value validation: S_AutoValidate............................... 15 Message line sound: S_UserSound.................................. 16 S_ErrorSound................................. 16 S_HelpSound.................................. 16 Turning the system cursor on and off: S_SetCursor............................... 16 Selecting Turbo ScrEdits cursor type: S_Cursor..................................... 18 Turbo ScrEdits regular inverted cursor....... 18 S_Off..................................... 18 Page I-2 Blinking system cursor....................... 18 S_Normal.................................. 18 Blinking block cursor........................ 18 S_Bold.................................... 18 Changing how the ENTER key is used: S_EnterAsTab................................. 19 Displaying data on the screen........................ 21 Displaying values in screen fields............... 21 Using The Message Line: Displaying messages. S_AutoHelpMsg............................ 22 S_ErrorMsg............................... 22 S_UserMsg................................ 22 Message sounds: S_HelpSound.............................. 23 S_HelpFreq............................... 23 S_HelpDur................................ 23 S_ErrorSound............................. 23 S_ErrorFreq.............................. 23 S_ErrorDur............................... 23 S_UserSound.............................. 23 S_UserFreq............................... 23 S_UserDur................................ 23 Messages colors: S_ErrorBg................................ 24 S_ErrorFg................................ 24 S_HelpBg................................. 24 S_HelpFg................................. 24 S_UserBg................................. 24 S_UserFg................................. 24 Clearing the screen form: S_ClearScreen.................................... 25 Refreshing or re-displaying a screen form: S_RefreshScreen.................................. 26 Editing and accepting data in screen fields: Reading an entire screen: S_ReadScreen................................. 27 Reading a single field: S_ReadField.................................. 29 Reading a single keystroke: S_ReadKey.................................... 31 S_NextKey.................................... 32 Field editing features........................... 33 Enter key S_EnterAsTab............................. 19 TAB key: Move to Next field (TAB)................. 33 Move to Previous field (SHIFT TAB)....... 34 DELETE key: Deleting single characters.(DEL)......... 34 Deleting right of cursor (SHIFT DEL)..... 34 INSERT key................................... 34 BACK SPACE key............................... 35 LEFT ARROW key............................... 35 RIGHT ARROW key.............................. 35 Page I-3 Detecting Special keys: Special Considerations: For S_ReadScreen and S_ReadField............. 36 For S_ReadKey and S_NextKey............... 36 Function keys (F1 though F12).................... 37 S_F1......................................... 37 S_F2......................................... 37 S_F3......................................... 37 S_F4......................................... 37 S_F5......................................... 37 S_F6......................................... 37 S_F7......................................... 37 S_F8......................................... 37 S_F9......................................... 37 S_F10........................................ 37 S_F11........................................ 37 S_F12........................................ 37 Curosr control keys (key pad).................... 37 S_Home....................................... 37 S_End........................................ 38 S_PgUp....................................... 38 S_PgDn....................................... 38 S_Up......................................... 38 S_Down....................................... 38 S_Left....................................... 38 S_Right...................................... 38 S_Ins........................................ 38 S_Del........................................ 38 Alt and Ctrl key combinations: S_Alt........................................ 38 S_Ctrl....................................... 38 S_Ch......................................... 38 Shift Keys: S_Shift...................................... 40 S_LeftShift.................................. 40 S_RightShift................................. 40 Other Keys: S_Enter...................................... 40 S_Esc........................................ 40 S_Tab........................................ 40 S_BkSp....................................... 40 Toggle key status indicators: S_Caps....................................... 41 S_InsertMode................................. 41 S_NumLock.................................... 41 S_ScrollLock................................. 41 Resetting the key indicators: S_ResetKeyFlags.............................. 42 Duplicating fields or repeating fields: Testing a fields dupe status. S_IsDupe..................................... 43 Defining a dupe field: S_SetDupe.................................... 44 Resetting a dupe field back to its original status. S_ResetDupe................................... 46 Clearing all dupe fields: S_ClearDupes................................. 47 Page I-4 Validating field values: Validating the entire screens contents: S_ValidateScreen............................. 48 S_ScreenValid................................ 48 Validating a single fields contents: S_ValidateField.............................. 49 S_ScreenValid................................ 49 Changing DISPLAY only fields to DATA ENTRY Fields: S_SetDisplayOff.................................. 51 Changing DATA ENTRY fields to DISPLAY only fields: S_SetDisplayOn................................... 52 Customizing Turbo ScrEdit Screens programmaticly: Changing the colors of a screen: S_ChangeScreenColor.......................... 53 Changing field colors: S_ChangeFieldColor........................... 55 Displaying the color changes: S_RefreshScreen.............................. 59 Makeing color changes permanent: S_StoreColorChanges.......................... 60 Page I-5 Alphabetical list of user global variables: S_Alt.................................................... 38 S_AutoHelp............................................... 14 S_AutoHelpMsg............................................ 22 S_AutoValidate........................................... 15 S_BkSp................................................... 41 S_Caps................................................... 42 S_Ch..................................................... 38 S_Cursor................................................. 18 S_Ctrl................................................... 38 S_Del.................................................... 38 S_DelayScreen............................................ 10 S_Down................................................... 38 S_End.................................................... 38 S_Enter.................................................. 19 S_EnterAsTab............................................. 19 S_ErrorBg................................................ 24 S_ErrorDur............................................... 23 S_ErrorFg................................................ 24 S_ErrorFreq.............................................. 23 S_ErrorMsg............................................... 22 S_ErrorSound............................................. 23 S_Esc.................................................... 41 S_HelpBg................................................. 24 S_HelpDur................................................ 23 S_HelpFg................................................. 25 S_HelpFreq............................................... 23 S_HelpSound.............................................. 23 S_Home................................................... 38 S_InsertMode............................................. 42 S_Ins.................................................... 38 S_Left................................................... 38 S_F1..................................................... 37 S_F2..................................................... 37 S_F3..................................................... 37 S_F4..................................................... 37 S_F5..................................................... 37 S_F6..................................................... 37 S_F7..................................................... 37 S_F8..................................................... 37 S_F9..................................................... 37 S_F10.................................................... 37 S_F11.................................................... 37 S_F12.................................................... 37 S_NumLock................................................ 42 S_PgUp................................................... 38 S_PgDn................................................... 38 S_Point.................................................. 27,29,31,32 S_Right.................................................. 38 S_ScreenValid............................................ 48,49 S_ScrollLock............................................. 42 S_FirstField............................................. 27,29 S_Shift.................................................. 40 S_ShiftLeft.............................................. 40 S_ShiftRight............................................. 340 S_ShowStatus............................................. 13 S_StBg................................................... 13 S_StFb................................................... 13 Page I-6 S_StLabelBg.............................................. 13 S_StLabelFg.............................................. 13 S_Tab.................................................... 41 S_Up..................................................... 38 S_UserBg................................................. 24 S_UserDur................................................ 23 S_UserFg................................................. 24 S_UserFreq............................................... 23 S_UserMsg................................................ 22 S_UserSound.............................................. 23 S_ValidateField.......................................... 49 Alphabetical list of user procedures: S_ChangeFieldColor....................................... 56 S_ChangeScreenColor...................................... 53 S_ClearDupes............................................. 47 S_ClearScreen............................................ 25 S_CloseScreenFile........................................ 11 S_LoadScreen............................................. 10 S_Init.(Turbo C only).................................... 8 S_IsDupe................................................. 43 S_NextKey................................................ 32 S_OpenScreenFile......................................... 9 S_ReadField.............................................. 29 S_ReadKey................................................ 31 S_ReadScreen............................................. 27 S_RefreshScreen.......................................... 58 S_ResetKeyFlags.......................................... 42 S_ResetDupe.............................................. 46 S_SetCursor.............................................. 17 S_SetDisplayOn........................................... 52 S_SetDisplayOff.......................................... 51 S_SetDupe................................................ 44 S_StoreColorChanges...................................... 60 S_ValidateScreen......................................... 48 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 I-8 POP UP WINDOW SUPPORT (registered version only).......(Section W) Introduction to Turbo ScrEdit Windows (TSW).............. W-1 Including Turbo ScrEdit Windows in your porgrams......... W-1 Intializing Turbo ScrEdit Windows........................ W-3 Memory usage and fragmentation considerations............ W-4 How many windows can you use............................. M-4 How the screen memory is used............................ M-4 Terms used in this document.............................. M-5 Access a window by name or number........................ M-5 MAXWINDOWS............................................... W-6 USERWINDOW............................................... W-6 ChangeWindow............................................. W-7 ChgWindowBackGround...................................... W-9 ClearWindow.............................................. W-11 DefineWindow............................................. W-12 EraseWindow.............................................. W-15 MoveWindow............................................... W-15 OpenWindow............................................... W-17 PopWindow................................................ W-17 PauseWindowUpdates....................................... W-19 PushWindow............................................... W-18 ReadWindowField.......................................... W-21 ReadWindowLine........................................... W-24 SaveWindow............................................... W-25 ShutWindow............................................... W-26 WindowsEnd............................................... W-27 WindowsInit.............................................. W-28 WriteWindowField......................................... W-29 WriteWindowLine.......................................... W-32 Page I-9 TURBO SCREDIT TUTOR PART I..(The Screen Editor).....(Section T-1) Introduction to Turbo ScrEdit Tutor....................T-1.1 Getting Started........................................T-1.1 Using the on-line user manual (help system).(F7).......T-1.2 Scrolling up and down in the on-line index.........T-1.2 Selecting topics fro the index screen..............T-1.3 Using the string search............................T-1.3 Printing all or part of the manual.................T-1.4 Using the manual index listing.....................T-1.4 Exiting the on-line help system....................T-1.5 Exiting the Turbo ScrEdit environment.(ESC)............T-1.5 Viewing disk directories.(F5)..........................T-1.5 Description of a screen file...........................T-1.6 Selecting a screen file to create or edit.(F1).........T-1.6 Field editing features.............................T-1.6 Working with screen files..............................T-1.8 Adding screen to a screen file.(INS)...............T-1.8 Renaming a screen.(TAB)............................T-1.9 Scrolling screen names (HOME) (END)................T-1.9 Deleting screens from the screen file.(DEL)........T-1.10 Automatic screen file backups......................T-1.10 Editing a screen record................................T-1.11 Starting the screen editor.(F2)....................T-1.11 The editor status line.............................T-1.11 Cursor movement....................................T-1.11 Changing the direction that the cursor travels.....T-1.11.2 Insert and overtype mode...........................T-1.12 Keyboard Graphics character mode...................T-1.12 The Quick reference editor help screen.............T-1.12 Switching between graphics and character mode......T-1.13 Changing character colors..........................T-1.13 Inserting blank lines..............................T-1.14 Deleting screen lines..............................T-1.14 Saving and Undoing screen changes..................T-1.14 Cutting and pasting screen text....................T-1.15 Copying a block of text........................T-1.15 Copying a line of text.........................T-1.17 Moving a block of text.........................T-1.18 Drawing lines and boxes............................T-1.18 Typing any ASCII...................................T-1.20 Compiling the screen.(F4)..............................T-1.22 Selecting the compiler you are using...............T-1.23 Setting the default field data type................T-1.23 Defining field types and processing specs..........T-1.24 Testing a screen.(F10).................................T-1.27 Changing a screens field order.(F6)....................T-1.28 Changing the field attribute colors.(F8)...............T-1.28 Printing a screen listing.(F5).........................T-1.30 Copying text from other screens.(F3)...................T-1.30 Generating source code (G).............................T-1.32 Selecting the compiler language for source code.....T-1.32 Suppressing skeleton file comments..................T-1.32 Options for using screen buffers....................T-1.32 Controlling character case in the new source file...T-1.33 Specifying the skeleton file location...............T-1.33 Selecting the screens to be included in generation..T-1.33 Page I-10 TURBO SCREDIT TUTOR PART II.(Field Processing stmts).(Section T-2) Introduction to Turbo ScrEdit Tutor Part II.....T-2.1 Using the processing specifications editor......T-2.2 SET.............................................T-2.5 REQUIRED........................................T-2.5,6,11,14 HELP............................................T-2.6 REM.............................................T-2.7 IN..............................................T-2.7,8,11,12,14 UP SHIFT ON/OFF.................................T-2.7,9,11 IF [AND,OR] THEN/ENDIF..........................T-2.8,9,10,11,12, 13, ERROR...........................................T-2.10 SKIP............................................T-2.8 SKIP IF BLANK...................................T-2.10 EDIT............................................T-2.14 Page I-11 TURBO SCREDIT TUTOR PART III - Programming with Turbo ScrEdit. Introduction to Turbo ScrEdit Tutor Part III.........T-3.1 What you need before you get started.................T-3.1 A MINIMUM coding example.............................T-3.3 Programs generated by Turbo ScrEdit (G Menu Option)..T-3.5 Generating a source code file.....................T-3.6 Understanding the source code generated...........T-3.7 Compiling and running the generated programs......T-3.14 A look at ScrDemo.Exe................................T-3.15 Option 1 - A data entry example...................T-3.20 S_ClearScreen and the SET command.............T-3.21 S_EnterAsTab..................................T-3.24 S_IsDupe, S_SetDupe, S_ClearDupes.............T-3.25 Changing the value of a DUPE field............T-3.26 Sound ON/OFF..................................T-3.27 Auto Help ON/OFF..............................T-3.28 Auto Validate ON/OFF..........................T-3.28 Changing message line colors..................T-3.29 Option 2 - Demo of MOUSE functions................T-3.30 S_MouseInstalled..............................T-3.30 S_ActivateMouse...............................T-3.30 S_SetMouseEvent...............................T-3.30 S_SetMouseRange...............................T-3.31 S_MsRow & S_MsCol.............................T-3.31 S_ShowMouse...................................T-3.31 S_ResetMouseFlags.............................T-3.32 S_MouseEvent (S_Ms->MouseEvent for C).........T-3.32 S_AnalizeMouse................................T-3.32 S_HideMouse...................................T-3.38 S_DisableMouse................................T-3.38 Option 3 - Customizing screen colors..............T-3.38 S_ChangeScreenColors..........................T-3.39 S_ChangeFieldColors...........................T-3.40 S_StoreColorChanges...........................T-3.41 Options 4 through 9...............................T-3.42 Page 1 ----------------------------------------------------------------- ** DISCLAIMER ** ----------------------------------------------------------------- Turbo ScrEdit diskettes, programs, and documentation are distributed AS IS, with no guarantee it will work correctly in any or all situations. The manual may contain errors and/or omissions. In no event will iHn Systems be liable for any damages or losses of any type. YOU USE Turbo ScrEdit and Turbo ScrEdit Windows AT YOUR OWN RISK. Further, all offers for technical support, notification of updated versions, including the stated fees for updated versions, are subject to withdrawal or increase without prior notice. IF YOU USE THIS SOFTWARE, YOU ARE ACCEPTING ALL CONDITIONS AS STATED ABOVE AND AGREE TO COMPLY WITH THE LEGAL TERMS AND CONDITIONS AS STATED IN THE NOTES TO USERS SECTIONS of the field PRINTME.1ST. If you do not accept these conditions and terms, delete the Turbo ScrEdit files from your system! No refunds will be granted under any conditions. The evaluation version is provided to allow potential customers to determine the suitability of the software for thier needs before you purchasing a license. ----------------------------------------------------------------- ** DISCLAIMER ** ----------------------------------------------------------------- Page 2 CONFIG.SYS requirements: ----------------------------------------------------------------- Before using Turbo ScrEdit to create screens you should place the following lines in your CONFIG.SYS file on the root directory of the disk that you will use to boot your system. Required lines: FILES=20 BUFFERS=20 If Turbo ScrEdit does not work: ----------------------------------------------------------------- We have had only two users call that were having problems using Turbo ScrEdit. In this section I will describe the problem that was reported and the solutions that were worked out over the phone. Problem: Using Turbo C, ScrDemo.C would compile correctly, but when the .exe file was executed the system would hang. Solution: We found that the compilers OPTIONS/LINKER/DEFAULT LIBRARIES switch was set to OFF and had to be set to ON. Problem: The user had used Turbo ScrEdit to create a screen in a screen file. When he selected the "G" option from the main menu to generated the skeleton file for his screen, Turbo ScrEdit "bombed" issuing a RUN TIME ERROR 4. Solution: We had to add a CONFIG.SYS file to his boot root directory with the lines FILES=20 and BUFFERS=20 in it. See CONFIG.SYS requirements in this manual. Preparing Turbo ScrEdit Interface for use in programs. ----------------------------------------------------------------- Setting the compiler directives before compiling the interface source code. The following compiler directives can be found in the first few lines of the interface source code listings "ScrEdit.Pas" and C include file "#defines.C". MOUSE VALIDATE COLORCHANGE These compiler directives have been supplied to allow you to control the size of the object code that is linked into your program. IF YOU ARE NOT CONCERNED ABOUT THE SIZE OF YOUR PROGRAM AND YOU WISH TO HAVE ALL TURBO SCREDIT PROCEDURES AVAILABLE TO YOU AT ALL TIMES, do not change these compiler Page 3 directives. By default these directives are defined and will compile all procedures into the units and library files. If either of the compiler directives MOUSE or VALIDATE are defined when the source code is compiled, the object code is generated to perform the various validation and mouse control functions. Because of the way that the mouse and validation procedures are used by the Turbo ScrEdit interface module, the smart linker will not be able to exclude any of these procedures when it is linking the program. COLORCHANGE - (Default is Defined) Turbo ScrEdit has a set of procedures that can dynamically change the color attributes of any portion of a Turbo ScrEdit screen or it's fields. When COLORCHANGE is defined the procedures for making color changes will be compiled into the object module and stored in the resulting ".TPU" or "Library" file. When COLORCHANGE is not defined the color change procedures are excluded during the compile. The procedures for making color changes WILL BE EXCLUDED from your executable programs by the smart linker if they are not referenced by your program. MOUSE - (Default is Defined) This directive determines if the procedures for detecting and controlling mouse activities will be available to your program. When MOUSE (is) defined during compile: Pascal: With the MOUSE directive defined when ScrEdit.Pas is compiled two units will be created, (ScrMouse.Tpu, and ScrEdit.Tpu). To use Turbo ScrEdit and mouse in your programs you will have to include a uses statement like: Uses ScrMouse,ScrEdit; C: The C version is a little different than the pascal version. The mouse procedures source code file "ScrMouse.C" is included with the "ScrEdit.C" source code when it is compiled. The library files created will include all of the mouse procedures. The mouse procedures are prototyped in ScrEdit.H. See the section "How to include Turbo ScrEdit in you program" for more information on using mouse procedures. When MOUSE (is not) defined during compile: With this compiler directive disabled, you will not be able to access or use mouse procedures in your programs. Page 4 VALIDATE - (Default is Defined) This directive determines if the procedures that are used for processing field validation statements are to be included in the resulting ".TPU" or "library" file. When VALIDATE (IS) defined during compile: With the VALIDATE directive defined when ScrEdit.Pas or ScrEdit.C is compiled, the validation procedures will be generated into the unit and library files created. The smart linker will not be able to link out any of the procedures. When VALIDATE (IS NOT) defined during compile: No validation procedures are generated, and any validation statements that have been defined for the fields on a screen will be ignored. IMPORTANT NOTE - If the fields of your screens are using HELP statements, EDIT MASKS, or SET statements, they will still be recognized and will have the desired effect whether or not validation procedures are generated. Creating the Turbo Pascal Unit file: ----------------------------------------------------------------- There are two ways to create the Turbo Pascal unit files "ScrMouse.Tpu" and "ScrEdit.Tpu", and "Windows.Tpu": Before you begin make sure that the pascal source code files "ScrMouse.Pas", "Validate.Pas", and "ScrEdit.Pas" are in the current directory or diskette. If you installing the registered version also copy "Windows.Pas" into the same directory or diskette. Method 1 - Using TPUBUILD.BAT -------------------------------------------------------------- TpuBuild.Bat will accept 3 parameters in the format of: C:>TpuBuild A [B] [C] Where: A : can be 4 for Turbo Pascal 4.0 5 for Turbo Pascal 5.0 or 5.5 B : Is the drive and directory where the command line compiler TPC.EXE is located. C : Is the drive and directory where you wish the unit files to be stored as they are created. Example: TpuBuild 5 C:\Tp C:\Tp\Units Page 4.5 The above example will use the 5.0 5.5 command line compiler format. It will expect to find the command line compiler TPC.EXE in the directory "C:\Tp". The unit files will be created and stored in the directory "C:\Tp\Units". If you are working on a dual floppy system you would put a system disk in drive A: with a copy of the Turbo Compiler on it. In drive B: you have the diskette that contains the above listed files. You would make drive B: the current drive and type: TpuBuild 5 A: This format would use the 5.0/5.5 command line compiler format. It will execute TPC.EXE from drive A:. It will place the unit or ".TPU" files on drive B:. After you have created the unit files make sure that the directory where you have stored them is included in the list of directories in the OPTION/DIRECTORY/UNITS menu option of you pascal programming environment. Method 2 - Using your programming editor environment. -------------------------------------------------------------- - Load the Turbo Pascal programming environment. - Set the OPTION/COMPILER/LOCAL SYMBOLS to OFF (Alt O C L) - Set the OPTION/COMPILER/DEBUG INFORMATION to OFF (Alt O C D) - Set the OPTION/DIRECTORIES/EXE & TPU line to specify the same directory path that you have listed on the OPTION/DIRECTORY/UNIT line. (Alt O D E type in your unit directory) - Set the COMPILE/DESTINATION switch to DISK. (Alt C D Memory) - Set the OPTION/LINKER/LINK BUFFER switch to DISK. (Alt O L L) - Set the COMPILE/PRIMARY FILE switch to "ScrEdit.Pas" (Alt C P ScrEdit.Pas) - Select COMPILE/COMPILE to compile the source code and create the unit files. (Alt C C) - Reset OPTION/DIRECTORIES/EXE & TPU back to what it was before. (Alt O D E Delete all characters) Page 5 After following the above steps Turbo ScrEdit and the mouse features are ready to be used in your programs. See the "How to include Turbo ScrEdit in your program" section of this manual for more information on how to use Turbo ScrEdit in your program. You may now delete "Validate.Pas", "ScrMouse.Pas", and "ScrEdit.Pas" from your system. Only the ".Tpu" files are required for using Turbo ScrEdit in your programs. Creating the Turbo C library files: ----------------------------------------------------------------- The batch file LIBBUILD.BAT is used to create Turbo Scredit library files for MEDIUM, COMPACT, LARGE, and HUGE memory models. To use this batch file, load it into your Turbo Programming environment and change the INCLUDE and LIBRARY directories for your systems. One of the four compile lines looks like this now: tcc -mm -v- -c -d -oScrEdit.ObJ -IC:\B\TC20\INCLUDE -LC:\B\TC20\LIB Scredit.c ^^^^^^^^^^^^^^^ ^^^^^^^^^^^ You might change it to look like this: tcc -mm -v- -c -d -oScrEdit.ObJ -IC:\TC\INCLUDE -LC:\TC\LIB Scredit.c ^^^^^^^^^^^^^ ^^^^^^^^^ Make these changes on all four of the lines that execute the Turbo C Command line compiler "TCC". Notice that the above line was changed to use the default directories established by the Turbo C installation program. Next - Make sure that the Turbo C Command line compiler (TCC) and the Turbo Librarian utility (TLIB) are either in the current directory where you are going to initiate LIBBUILD.BAT or that there is a system PATH statement defined that includes the directory where these files reside. Next - Make sure that you have copied "Validate.C", "ScrMouse.C", and "ScrEdit.C" source code files into the current directory. Before launching LIBBUILD.BAT you need to decide which memory model libraries you will want to use. If you have adequate disk space you may just want to use the ALL option. Next - Type: LIBBUILD Option Options: M = generate the MEDIUM memory model library. C = generate the COMPACT memory model library. L = generate the LARGE memory model library. H = generate the HUGE memory model library. ALL = generate the All Four memory model libraries. Page 6 When LIBBUILD.BAT finishes you will have at least one of the following library files created: ScrEditM.Lib (for MEDIUM memory model programming) ScrEditC.Lib (for COMPACT memory model programming) ScrEditL.Lib (for LARGE memory model programming) ScrEditH.Lib (for HUGE memory model programming) Copy the library files to your library directory. You may now delete "LibBuild.Bat", "Validate.C", "ScrMouse.C", and "ScrEdit.C". You are now ready to use Turbo ScrEdit procedures in your Turbo C programs. For more details on using the Turbo C libraries, see the Turbo C instructions that follow in the "How to include Turbo ScrEdit in your program" section of this manual. How to include Turbo Scredit in your program. ----------------------------------------------------------------- Pascal: To make Turbo Scredit procedures available to your programs you must include a reference to "ScrEdit.TPU" and "ScrMouse.Tpu" in your programs "USES" statement. Example: Uses Crt,Dos,Printer,ScrMouse,ScrEdit. ^^^^^^^^ ^^^^^^^ Be sure that the unit files "ScrEdit.Tpu" and "ScrMouse.Tpu" reside in one of the directory paths referenced in the OPTION/DIRECTORIES/UNIT line of the Turbo Pascal programming environment, or that they are copied to the current directory that you are going to be compiling in. C: Step 1: Turbo ScrEdit supports MEDIUM, COMPACT, LARGE, and HUGE memory models. Set your programming environment OPTIONS/COMPILER/MODEL switch to the memory model that you wish to work with. Step 2: Include Turbo ScrEdit's header file (ScrEdit.H) in your programs list of #include statements. Example: #include <stdlib.h> #include <math.h> #include <conio.h> #include "scredit.h" <== this include statement Page 7 Step 3: Prepare a project file for the program you are working with. The first line of the project file should contain your program name, the second line should contain the drive, path and library file name that agrees with the memory model selected in Step 1. Example Project file for MEDIUM memory model: YourProg C:\TC\LIB\ScrEditM.Lib If the above lines were stored in a file named "YourProg.Prj", you would set the PROJECT/PROJECT NAME line of the Turbo C programming environment to read "YOURPROG.PRJ". Now each time you RUN, BUILD, or MAKE YourProg.C, Turbo C will link in the object code of the Turbo Scredit library file. Using Turbo ScrEdit from within your program. ----------------------------------------------------------------- Turbo ScrEdit can seem a little intimidating when you first begin using it, but, it is really quite simple to use. You can use Turbo ScrEdit's "G" menu option to generate a complete, ready to compile and run, skeleton program that can use one or more screens in a screen file. You can then use the skeleton file as a starting point for creating your custom application. Or, if you prefer, you can easily write your own programs from "scratch." Below is a listing of the MINIMUM coding required to open a screen file, display a screen, and begin doing data entry in the screen form. An example of the smallest possible working program to use a Turbo ScrEdit screen. -------------------------------------------------------------- Pascal C ----------------------------- --------------------------- Uses ScrEdit; #include "ScrEdit.H" ==1> {$I YourFile.001} #include "YourFile.001" void main() { Begin S_Init(); ==2> S_OpenScreenFile('YourFile'); S_OpenScreenFile("YourFile"); ==3> Initialize_YourScreen_Buf; Initialize_YourScreen_buf; ==4> S_LoadScreen('YourScreen'); S_LoadScreen("YourScreen"); Repeat do{ S_ReadScreen; S_ReadScreen(); If S_Enter Then if (S_Enter) S_UserMsg := strcpy(S_UserMsg, ' PROCESS SCREEN '; " PROCESS SCREEN "); Until S_Esc; } while (!S_Esc); S_CloseScreenFile; S_CloseScreenFile(); End. } ------------------------------ --------------------------- Page 8 As you can see, it does not take much to get started. Either of the above programs can be keyed into a file, compiled, and ran. To use a screen that you have created, make the following changes to the lines with that are marked: ==1> Change "YourFile" to the name of the screen file that have creatd. You can use drive:\path\fileName.SCR format. Also change the ".001" to reference the the screen record definitions file genreated by Turbo ScrEdit when you compiled your screen. The screen listing generated by the main menu option "F5" lists the screen definitions file name. ==2> Change "YourFile" to the name of the screen file that you have created. ==3> ==4> On these lines change "YourScreen" to the name of the screen that you created. From this point forward you would add your logic to make a menu that can call other programs, or perhaps a data entry program to add, delete, change, inquire, and otherwise manipulate the records in a file or files. The files "Smallest.Pas" and "Smallest.C" have been included in your Turbo ScrEdit package, and contain the above example programs. See ScrEdit.Tut for an explanation of how to compile and run the examples. Initializing the interface unit. ----------------------------------------------------------------- Pascal: Initialization is automatic. C: Before calling any of the Turbo ScrEdit procedures call S_Init(). Example: #include "ScrEdit.H" #include "YourFile.001" . . void main() { ===> S_Init(); S_OpenScreenFile("YourFile"); . . } Page 9 Initializing Screens. ----------------------------------------------------------------- When Turbo ScrEdit compiles the screen (using main menu option F4), it creates a file that contains the source code that defines the screen fields as data elements of a record. The same file contains the routine that initializes the screen record. If you use the source code generation facility of Turbo ScrEdit (the 'G' option on the main menu), Turbo ScrEdit will include all the necessary screen records in the skeleton file. It will also create calls to the initialization routines. If you decide to code your own programs from "scratch", you must be sure to include the screen record definitions generated by Turbo ScrEdit into your program. You must also code a call to each of the screens initialization routines. ** IMPORTANT NOTE ** - The screen initialization routine (Initialize_YourScreen_buf) must be called AFTER the screen file is opened. - If you use more than one SCREEN FILE you must reinitialize the screens of the files each time the SCREEN FILES are opened. Turbo ScrEdit names the screen definition record by using the screen file name and appending a dot (".") to it followed by a three digit number generated according to the screens postion in the screen file index. Thus, "YourScr.001" would be the screen record definitions for the first screen in the screen file "YourScr.Scr". If you are not sure what a screens number is you can find it on the top of the screen listing gererated by the main menu F5 option. It is important that the records be properly included and initialized before you attempt to use them. Failure to do so will cause unpredictable results. Example: Pascal C ----------------------------- --------------------------- Uses ScrEdit; #include "ScrEdit.H" ===> {$I Yourfile.001} #include "YourFile.001" void main() { Begin S_Init(); S_OpenScreenFile('YourFile'); S_OpenScreenFile("YourFile"); ===> Initialize_YourScreen_Buf; Initialize_YourScreen_buf; . . . . ------------------------------ --------------------------- In the above examples the first pointer is pointing to the include statement that includes the record definitions for screen 1 of YourFile.Scr. The second pointer points out the call to the initialization routine for the screen record. Page 10 Opening a screen file for use. ----------------------------------------------------------------- Procedure: S_OpenScreenFile(FileName) Function: Opens a screen file and prepares it to be accessed. Remarks: If the screen file specified by FileName does not exist, or does not contain any records, an error message is displayed on the bottom line of the screen and the program halts. Defined in C: void S_OpenScreenFile(char * ScrFileName) Defined in Pascal: Procedure S_OpenScreenFile(ScrFileName:S_Str80); Example: Pascal C ----------------------------- --------------------------- Uses ScrEdit; #include "ScrEdit.H" {$I Yourfile.001} #include "YourFile.001" void main() { Begin S_Init(); ===> S_OpenScreenFile('YourFile'); S_OpenScreenFile("YourFile"); Initialize_YourScreen_Buf; Initialize_YourScreen_buf; . . . . ------------------------------ --------------------------- Parameters: FileName = The name of a Turbo ScrEdit screen file. The name may include drive, path, and extension of ".SCR". - If drive and path are omitted, only the current directory is searched. - If extension is omitted ".SCR" is assumed. Loading a screen and displaying it. ----------------------------------------------------------------- Procedure: S_LoadScreen(ScreenName) Function: This procedure searches the screen file directory for the specified screen name. If the screen is found it is loaded into memory, prepared for use, and displayed on the crt screen. Variable: S_DelayScreen (Type:Boolean, Default:False) Function: When S_DelayScreen is set to FALSE (default setting) the screen loaded by S_LoadScreen is immediately displayed on the video. When S_DelayScreen is set to TRUE the screen loaded by S_LoadScreen is not displayed on the video. This switch is used to allow the screens color assignments to be changed before it is displayed. See the section "Customizing Turbo ScrEdit Screens Programmatically". Page 11 When the screen is delayed, it will automatically be displayed by the next call to S_ReadScreen, S_ReadField, S_ReadKey, Or it can be displayed by a call to S_RefreshScreen. Remarks: This procedure will issue a error message and halt your program if: 1 - The screen requested is not found in the screen file index. 2 - The screen record has not been initialized. 3 - The screen in the screen file has not been' compiled using the main menu option 4. Defined in C: void S_LoadScreen(char * ScrName) Defined in Pascal: Procedure S_LoadScreen(ScrName:S_Str80); Example: Pascal C ----------------------------- --------------------------- Uses ScrEdit; #include "ScrEdit.H" {$I Yourfile.001} #include "YourFile.001" void main() { Begin S_Init(); S_OpenScreenFile('YourFile'); S_OpenScreenFile("YourFile"); Initialize_YourScreen_Buf; Initialize_YourScreen_buf; ===> S_LoadScreen('YourScreen'); S_LoadScreen("YourScreen"); . . ------------------------------ --------------------------- Parameters: ScrName - The name of a screen stored in the screen file. Closing a screen file. ----------------------------------------------------------------- Procedure: S_CloseScreenFile Function: Closes the current screen file and restores the system cursor to it`s original status at the time that the screen was opened. Remarks: None. Defined in C: void S_CloseScreenFile() Defined in Pascal: Procedure S_CloseScreenFile; Example: (see next page) Page 12 Example: Pascal C ----------------------------- --------------------------- Uses ScrEdit; #include "ScrEdit.H" {$I Yourfile.001} #include "YourFile.001" void main() { Begin S_Init(); S_OpenScreenFile('YourFile'); S_OpenScreenFile("YourFile"); Initialize_YourScreen_Buf; Initialize_YourScreen_buf; S_LoadScreen('YourScreen'); S_LoadScreen("YourScreen"); . . . . ===> S_CloseScreen; S_CloseScreen(); End. } ------------------------------ --------------------------- Parameters: None Page 13 Activating and Deactivating special features. ----------------------------------------------------------------- Turbo ScrEdit has a number of special features and functions that may be activated or deactivated in your program by setting boolean switches to TRUE or FALSE (1 or 0 in 'C'.) The "[INSERT] [CAPS] [NUM LOCK] [SCROLL LOCK]" Status line. -------------------------------------------------------------- S_ShowStatus...(type: boolean, default:TRUE) Turbo ScrEdit monitors the BIOS to determine the status of the system toggle keys. The value of S_ShowStatus determines if the toggle switch status line will be displayed on the bottom line of the screen when there is no help, error, or user messages to be displayed. TRUE = Causes the toggle key status line to be displayed. The status of the insert, caps lock, scroll lock, and num lock keys are displayed in inverse when active and normal text color when inactive. FALSE = Suppresses the toggle key status line. Changing the status lines colors. -------------------------------------------------------------- The status lines colors can be changed programmatically by assigning new color codes to the following variables: Defined in Pascal as: Var S_StBg : Byte; S_StFg : Byte; S_StLabelBg : Byte; S_StLabelFg : Byte; Defined in C as : unsigned char S_StBg; unsigned char S_StFg; unsigned char S_StLabelBg; unsigned char S_StLabelFg; In the above list of variables, S_StBg and S_StFg specify the color codes used for the text portion of the status line and the color that the toggle key labels will be displayed in when they are set to an OFF state. The variables S_StLabelBg and S_StLabelFg specify the color that the text portion of the toggle key labels will be highlighted with when the toggle key status is set to ON. See example on next page. Page 14 Example of Usage: Pascal C -------------------------------- ---------------------------- . . S_OpenScreenFile('YourFile'); S_OpenScreenFile("YourFile"); S_LoadScreen('YourScreen'); S_LoadScreen("YourScreen"); => S_StBg := Black; S_StBg = BLACK; => S_StFg := Green; S_StFg = GREEN; => S_StLabelBg := White; S_StLabelBg = WHITE; => S_StLabelFG := Black; S_StLabelFg = BLACK; While Not S_Esc do while (!S_Esc) Begin { S_ReadScreen; S_ReadScreen(); . . -------------------------------- ---------------------------- In the above code segment we see a screen file has been opened and a screen loaded. Next we see the status line's color control variables are being assigned new values. With the new values the status line will be displayed as green characters on a black background, and the active toggle key labels will be displayed as black characters on a white background. Continuous field help messages. -------------------------------------------------------------- S_AutoHelp.....(type: boolean, default:FALSE) Turbo ScrEdit allows each data entry field on a screen to have a HELP message assigned to it. Normally the help messages are displayed by keying a question mark in the first character of the field. Using this switch you can have field HELP messages displayed automatically as the cursor moves from field to field. TRUE = Field help messages are to be displayed automaticaly when the cursor moves from field to field. S_AutoHelp has no effect for fields that have no HELP message defined. FALSE = HELP messages are only displayed when a question mark is keyed as the first character of the field. See the manual sections "Changing Message Line Colors" and "Changing Message Line Sounds" for more information on customizing and useing the auto help feature. Page 15 Instant field value validation. -------------------------------------------------------------- S_AutoValidate....(type: boolean, default:FALSE) Automatic validation is designed to be used in conjunction with S_ReadScreen only. Turbo ScrEdit allows each data entry field to have up to 50 lines of validation statements assigned to it. Using this option you can control when the field validation statements are used to check the data entered into a field. TRUE = When this switch is set to TRUE, Turbo ScrEdit will process the current fields contents just before the cursor exits the field. - If the value keyed into the field fails to pass the edit test, the assigned error message is displayed and the cursor will remain in the field. - If the value keyed passes the validation test, the cursor advances to the next data entry field. FALSE = By default this switch is set to FALSE, meaning Turbo ScrEdit accepts data entry into all screen fields until the ENTER key is pressed. When the ENTER key is pressed, Turbo ScrEdit begins with the first screen field and compares each fields values against any validation statements that have been assigned. If an error is detected the error message is displayed and the cursor is positioned on the offending field. See the manual sections "Message line sound", "Changing Message Line Colors" and "Changing Message Line Sounds" for more information on customizing and using screen validation messages. Page 16 Message line sound. ------------------------------------------------------------- S_ErrorSound......(type: boolean, default:TRUE) S_HelpSound.......(type: boolean, default:TRUE) S_UserSound.......(type: boolean, default:TRUE) Turbo ScrEdit allows you to use sound to alert the user of your program that a message has been issued that needs his attention. There are three different types of messages that can be issued to your user and each type can have its sound function turned on or off. S_ErrorSound: TRUE = The audio alert is sounded each time an ERROR message is displayed on the bottom line of the screen. FALSE = No sound for ERROR messages. S_HelpSound: TRUE = The audio alert is sounded when a HELP message is displayed on the bottom line of the screen. FALSE = No sound for HELP messages. S_UserSound: TRUE = The audio alert is sounded when a USER (programmers) message is displayed on the bottom line of the screen. FALSE = No sound for USER messages. For a more detailed discussion on using the message line see the manual sections "Displaying Messages", "The message line sounds", and "The message line colors". Turning the system cursor on and off. ------------------------------------------------------------- Procedure: S_SetCursor(Cursor) Function: To turn the system cursor on and off, and to select the type of cursor that is used when the user is keying data into a screen field. Remarks: This procedure is intended to be used when the programmer is going to suspend using the Turbo ScrEdit procedures and wishes to resort to using the standard I/O functions of his language (such as gotoxy, readln or scanf, writeln or printf). Normally Turbo ScrEdit will handle the cursor for you. See the next manual section "Selecting Turbo ScrEdit cursor types." Continued on next page. Page 17 Defined in C: enum S_Cursors {S_OFF,S_BOLD,S_NORMAL,S_INVERTEDBOLD,S_INVERTEDNORMAL} void S_SetCursor(char); Example: /* Set system cursor off */ S_SetCursor(S_OFF); /* Set system cursor back to normal */ S_SetCursor(S_NORMAL); /* Set system cursor to a bold blinking block */ S_SetCursor(S_BLOCK); Defined in Pascal: S_Cursors = (S_Off,S_Bold,S_Normal, S_InvertedBold,S_InvertedNormal); Procedure S_SetCursor(Switch:S_Cursors); Example: {* Set system cursor off *} S_SetCursor(S_Off); {* Set system cursor back to normal *} S_SetCursor(S_Normal); {* Set system cursor to a bold blinking block *} S_SetCursor(S_Block); Parameters: Cursor.... An integer value 0 thru 4. Turbo ScrEdit recognizes the values as: 0 = S_OFF (system cursor is off) 1 = S_NORMAL (restore original system cursor) 2 = S_BOLD (blinking block system cursor) The cursor types 3 (S_INVERTEDBOLD) and 4 (S_INVERTEDNORMAL) will be considered the same as S_NORMAL and S_BOLD when using you programming language's I/O statements. Page 18 Selecting Turbo ScrEdits data entry cursor type. -------------------------------------------------------------- S_Cursor.......(type: Enumerated) For Pascal - S_Off, S_Normal, S_Bold, S_InvertedBold, S_InvertedNormal. For C - S_OFF, S_NORMAL, S_BOLD, S_INVERTEDBOLD, S_INVERTEDNORMAL. When Turbo ScrEdit is initialized the system cursor is read and the current value is stored by Turbo ScrEdit. The system cursor is then turned off and S_Cursor is assigned a value of S_Off. Each time a field is edited by Turbo ScrEdit, the system cursor is set ON depending on the value of S_Cursor. When the cursor leaves the data entry field the system cursor is reset to OFF. You can assign S_Cursor any one of the five possible cursors switch values to select the type of cursor to be used when data is being keyed into a field. In the descriptions of cursors that follows, the term "inverted" means that the character postion where the next character will be keyed will be inverted in regards to the current background color of the current feild: - If the current data entry field is defined as having a black background, then the inverted cursor will have a white (color code 7) background. - If the the field has been defined as having a non-black background, then the inverse cursor background color will be black (color code 0.) The five cursor types are: 1 - (S_OFF) An inverted non-blinking block cursor. 2 - (S_BOLD) The blinking system cursor set to a transparent full character sized block. 3 - (S_NORMAL) The system cursor that was defined when the application was started from the DOS prompt (usually an underscore character.) 4 - (S_INVERSEBOLD) An inverted non-blinking block cursor, the same as option 1, with a full character size transparent blinking system cursor, the same as option 2. 5 - (S_INVERSENORMAL) An inverted non-blinking block cursor, the same as option 1, with the systems normal blinking cursor (usually a underscore) inside the inverted block cursor. In the examples that follow, the inverse normal cursor will be used when keying data into fields on the screen. Page 19 Pascal C ------------------------------ --------------------------- Uses ScrEdit; #include "ScrEdit.H" {$I YourFile.001} #include "YourFile.001" void main() { Begin S_Init(); S_OpenScreenFile('YourFile'); S_OpenScreenFile("YourFile"); Initialize_YourScreen_Buf; Initialize_YourScreen_buf; S_LoadScreen('YourScreen'); S_LoadScreen("YourScreen"); ===> S_Cursor := S_INVERSENORMAL; S_Cursor = S_INVERSENORMAL; Repeat do{ S_ReadScreen; S_ReadScreen(); If S_Enter Then if (S_Enter) S_ProcessScreen; S_ProcessScreen(); Until S_Esc; } while (!S_Esc); S_CloseScreenFile; S_CloseScreenFile(); End. } ------------------------------ --------------------------- If you were to key in one of the above programs, substituting one of your screen file names, and the name of one of the screens stored in your screen file, you could compile and run the program and see that the data entry cursor is the inversed block with the systems normal cursor blinking in it. Changing how the ENTER key is used. -------------------------------------------------------------- S_EnterAsTab......(type: boolean, default:FALSE) This switch is designed primarily to be used in conjunction with S_ReadScreen. By DEFAULT, Turbo ScrEdit uses the TAB key to move the cursor left to the next field on the screen, and SHIFT TAB to move the cursor right to the previous field on the screen. Data entry continues on a screen until the user presses the ENTER key. When the ENTER key is pressed Turbo ScrEdit performs field validation according to any validation statements that have been defined for the screen and, if no errors are detected, the screens contents are returned to your program in the screen record. Using the S_EnterAsTab switch you can instruct Turbo ScrEdit to translate the ENTER key into a tab key. TRUE = When S_EnterAsTab is set to TRUE, the enter key will act exactly the same as the TAB key. Pressing the ENTER key will cause the cursor to move to the Page 20 next field, pressing a SHIFT key and the ENTER key will cause the cursor to move to the previous field. Data entry will continue until one of the function keys or one of the keypad keys is presed, or until the ALT or CTRL key is pressed in conjunction with another keyboard character. FALSE = When S_EnterAsTab is set to FALSE, pressing the ENTER key causes field validation to occur and the screen's contents are returned to your program. Special considerations for using S_EnterAsTab. ---------------------------------------------------------- The most important consideration when you are using S_EnterAsTab set to TRUE is that FIELD VALIDATION WILL NOT AUTOMATICALLY OCCUR WHEN THE ENTER KEY IS PRESSED. You will have to code a call to S_ValidateScreen to ensure that the field validation procedures are used. In the example that follows, S_EnterAsTab is set to TRUE and the programmer has defined the F10 key as the key the user will press to signal that he/she is finished entering data and wants the screen processed. Pascal C ---------------------------- ---------------------------- . . . . ===> S_EnterAsTab := True; S_EnterAsTab = 1; While Not S_Esc Do while (!S_Esc) Begin { S_ReadScreen; S_ReadScreen(); If S_F10 Then if (S_F10) Begin { ===> S_ValidateScreen; S_ValidateScreen(); If S_ScreenValid Then if (S_ScreenValid) Process_Screen_Data Process_Screen_Data(); End; } End; } . . . . ----------------------------- --------------------------- In the above code segments, the ENTER key will be used as the TAB key. When any of the other special keys are pressed, Turbo ScrEdit interrupts what it is doing and control returns to the IF statement after the call to S_ReadScreen. If the special key that was pressed is the F10 key, the validation procedure is called. - If the screen contents are not valid S_Point will be pointing to the field with the bad data in it. When S_ReadScreen is called again the cursor will be placed in the offending field and the error message displayed. - If the data is valid then S_ScreenValid will test TRUE and the program can process the screens contents. Page 21 For more information on using the S_ValidateScreen procedure read the detailed section of the manual on using S_ValidateScreen. Displaying data on the screen. ----------------------------------------------------------------- There is basically two ways to display data to the user of your program. The first is to move values to screen fields, and the second is to display messages on the message line. First we will examine how to display data using screen fields. Displaying values in screen fields. -------------------------------------------------------------- When your screens are compiled using the F4 option from the Turbo ScrEdit main menu, a file is created that contains the source code statements that define a record to accommodate the fields on the screen. The record may look something like: Pascal C ----------------------------- ------------------------------- Type ScreenRecord = Record typedef struct { Name : String[30]; char name[31]; Address : String[30]; char address[31]; City : String[20]; char city[31]; State : String[2]; char state[2]; Zip : Real; double zip; End; } screenrecord; Var S_Rec : ScreenRecord; screenrecord s_rec; ----------------------------- ------------------------------- Turbo ScrEdit knows the length and type of each field in the record. When you call the screen record initialization procedures at the beginning of your program, Turbo ScrEdit stores the memory address of the record. With this information Turbo ScrEdit knows where to find the values that it must move to the screen to be edited, and where to store the values keyed in by the user of your program. Thus, to display data on the screen you move values to the record fields just as you would any other record in your language. Pascal C -------------------------------- ------------------------------- With S_Rec Do Begin Name := 'Mr. Dave'; strcpy(s_rec.name,"Mr. Dave"); Addr := '111 Alpine'; strcpy(s_rec.addr,"111 Alpine"; City := 'TinBuckTwo'; strcpy(s_rec.city,"TinBuckTwo"); State := 'CA'; strcpy(s_rec.state,"CA"); Zip := 93221.0; zip = 93221; End; -------------------------------- ------------------------------- When you call S_ReadField, S_ReadScreen, or S_ReadKey, Turbo ScrEdit will display the contents of the screen record on the screen. Page 22 Using the Message line. -------------------------------------------------------------- Turbo ScrEdit reserves the bottom (25th) line of the display as the message line. From time to time you will want to display a message of some sort from your program to the user. Turbo ScrEdit allows you to accomplish this by assigning a string of up to 78 characters to one or more of three possible global variables. You can also select the color that the message will be displayed in as well as the tone and duration of an audio alarm to draw the users attention to the message. Displaying messages. -------------------------------------------------------------- Each time your program calls one of the procedures: S_ReadScreen, S_ReadField, or S_ReadKey, Turbo ScrEdit examines the message fields and issues the message that they may contain. The message fields are defined as: Pascal: Var S_UserMsg : S_Str80; S_ErrorMsg : S_Str80; S_AutoHelpMsg : S_Str80; C : unsigned char S_UserMsg[81]; unsigned char S_ErrorMsg[81]; unsigned char S_AutoHelpMsg[81]; The name of the field indicates how it is used by Turbo ScrEdit. S_UserMsg - is reserved for the programmer to use to send messages to the user of the program. S_ErrorMsg - is used by Turbo ScrEdit to issue error messages generated when various errors are detected. Usually this field will be used by the field validation part of Turbo ScrEdit to issue error message for fields that have not passed the validation process. S_AutoHelpMsg - is used by Turbo ScrEdit for issuing help messages to the user. You may use any of these fields at your discretion. However, it is recommend that you use only S_UserMsg to send messages to your user. This will insure that no system generated messages will be lost. If more that one message is sent to the user at a time, there is a hierarchy that is used by Turbo ScrEdit for determining which message to display first. 1st priority - S_ErrorMsg 2nd priority - S_UserMsg 3rd priority - S_AutoHelpMsg ONCE A MESSAGE IS DISPLAYED, TURBO SCREDIT ERASES THE MESSAGE FROM THE MESSAGE FIELD. Page 23 If all three message areas contained messages: - First S_ErrorMsg would be displayed on the message line and erased from S_ErrorMsg. When a key is pressed, the error message will disappear. - Second the S_UserMsg will be displayed on the message line and erased from S_UserMsg. Again when a key is pressed the user message will disappear. - Third the S_AutoHelpMsg will be displayed on the message line and erased from S_AutoHelpMsg. Again when another key is pressed the auto help message will disappear. - Fourth, if S_ShowStatus is set to TRUE, the toggle key status line will be displayed. Message line sound. -------------------------------------------------------------- Each of the three message types can be assigned a unique sound that is issued when the message is displayed. Turbo ScrEdit defines three sound control variables for each message area: Defined in Pascal as: Var S_ErrorSound : Boolean; S_ErrorFreq : Integer; S_ErrorDur : Integer; S_UserSound : Boolean; S_UserFreq : Integer; S_UserDur : Integer; S_HelpSound : Boolean; S_HelpFreq : Integer; S_HelpDur : Integer; Defined in C as : unsigned char S_ErrorSound; int S_ErrorFreq; int S_ErrorDur; unsigned char S_UserSound; int S_UserFreq; int S_UserDur; unsigned char S_HelpSound; int S_HelpFreq; int S_HelpDur; You will notice in the above listing of variables, that each of the three message areas has a corresponding boolean sound switch (S_xxSound), and two integer variables that control the frequency (S_xxFreq) and duration (S_xxDur) of the sound. In the coding examples that follow we will issue a "user" message and a short high pitched beep. Pascal C -------------------------------- ---------------------------- . . S_UserMsg := 'Beep'; strcpy(S_UserMsg,"Beep"); S_UserSound := True; S_UserSound = 1; S_UserFreq := 150; S_UserFreq = 150; S_UserDur := 100; S_UserDur = 100; S_ReadKey; S_ReadKey(); . . -------------------------------- ---------------------------- Page 24 The message sound variables need only be set once in a program. They will not change until new values are assigned to them. Message line Colors. -------------------------------------------------------------- Turbo ScrEdit allows the programmer to assign unique colors to to the different types of message lines to make it easier for the user of the program to determine the type and severity of the message that is being issued to him. Turbo ScrEdit defines two color variables for each of the message areas. Defined in Pascal as: Var S_ErrorFg : Byte; S_ErrorBg : Byte; S_UserFg : Byte; S_UserBg : Byte; S_HelpFg : Byte; S_HelpBg : Byte; Defined in C as : unsigned char S_ErrorFg; unsigned char S_ErrorBg; unsigned char S_UserFg; unsigned char S_UserBg; unsigned char S_HelpFg; unsigned char S_HelpBg; You will notice in the above listing of variables, that each of the three message areas has two corresponding integer variables that control the foreground (S_xxxxxFg) and background (S_xxxxxBg) color assignments. In the coding examples that follow we will issue a "user message" that reads "BEEP" and is displayed with a RED background and a bright yellow foreground color. Pascal C -------------------------------- ---------------------------- . . . . S_UserMsg := 'BEEP'; strcpy(S_UserMsg,"BEEP"); S_UserBg := Red; S_UserFg = RED; S_UserFg := Yellow; S_UserBg = YELLOW; S_ReadKey; S_ReadKey(); . . . . -------------------------------- ---------------------------- The message color variables need only be set once in a program. They will not change until new values are assigned to them. Page 25 Clearing the screen form. ----------------------------------------------------------------- Procedure: S_ClearScreen(Initialize) Function: Clears the fields on a screen form and optionally sets the fields to it's initial values. Remarks: This procedure is used to clear the fields on a screen or to initialize the screen. When called it will do the following: 1 - Fields that are defined as being DUPE or REPEATING fields ARE LEFT UNCHANGED. 2 - All display only and data entry fields are erased or cleared. 3 - If the initialize parameter is set to a value of 1 the screen fields are assigned the initial values specified by SET statements in the field processing statements. (Field processing statements are assigned using Turbo ScrEdit's main menu option F4.) Defined in C: void S_ClearScreen(int Initialize) Defined in Pascal: Procedure S_ClearScreen(Initialize:Integer); Example of Usage: Pascal C ---------------------------- ---------------------------- ===> S_ClearScreen(1); S_ClearScreen(1); While Not S_Esc Do while (!S_Esc) Begin { S_ReadScreen; S_ReadScreen(); If S_Enter Then if (S_Enter) Begin { Process_Screen_Data; Process_Screen_Data(); ===> S_ClearScreen(1); S_ClearScreen(1); End; } End; } ----------------------------- --------------------------- In the above examples a screen is going to be processed until the ESCAPE key is pressed. Before program control drops into the "while" loop, a call is made to S_ClearScreen with an initialize switch setting of 1, meaning that the fields on the screen are to receive any initial values defined by SET statements. Once inside the "while" loop, Turbo ScrEdit will continue processing a screen until the ENTER or ESCAPE key is pressed. When the ESC key is pressed the program will end. When the ENTER key is pressed the procedure "Process_Screen_Data" is called to process the fields on Page 26 the screen and write out a record of some sort. Next, S_ClearScreen is called again to clear the screen and re- initialize the screen fields. Then, because S_Esc was not pressed, Turbo ScrEdit will return to the user for another screen of data. Parameters: Initialize.... 0 = Clear the screen. Do not check for SET statements to assign initial values. 1 = Clear the screen. Apply any SET statement initial values that have been assigned to the screen fields. Refreshing or re-displaying a screen form. ----------------------------------------------------------------- Procedure: S_RefreshScreen Function: Re-displays the current screen and its data. Remarks: This procedure is used to re-paint a screen and to re- display the field values. From time to time you may find it necessary to resort to using your languages video and keyboard i/o commands. Particularly if you wish to use graphics mode to produce bar charts, or display a graphics image of some sort. Once you have finished with your special function you can call S_RefreshScreen to repaint your current screen, and continue right where you left off. Defined in C: void S_RefreshScreen() Defined in Pascal: Procedure S_RefreshScreen; Example of Usage: Pascal C ---------------------------- ---------------------------- . . . . S_ReadScreen; S_ReadScreen(); If S_Home Then if (S_Home) Begin { Display_Bar_Chart; Display_Bar_Chart(); ===> S_RefreshScreen(); S_RefreshScreen(); End; } . . . . ---------------------------- --------------------------- Parameters: None. Page 27 Editing and accepting data into screen fields. ----------------------------------------------------------------- Turbo ScrEdit provides four procedures for accepting data from the user. Two of the procedures accept data entry into screen fields, and two of the procedures accept only keystrokes. Reading an entire screen. ------------------------------------------------------------- Procedure: S_ReadScreen Function: Displays the contents of a screen record in the screen form and allows the field values to be edited or new data entered. Variable: S_Point (type:integer) Function: Before calling S_ReadScreen: S_Point can be set to the number of the screen field that is to be the first field edit by S_ReadScreen. If the field pointed to by S_Point is a display only field, or a dupe field, Turbo ScrEdit will advance forward through the field list until it finds the next data entry field. Returning from S_ReadScreen: S_Point will point to the last field that was being edited when data entry was interrupted by pressing one of the special keys. Variable: S_FirstField (type:integer) Function: This field contains the field number of the field that has been defined as the first logical field on the screen. One of Turbo ScrEdits important features is that you can redefine the order that screen fields are edited in. So the first field on the screen may not be the field that is physically the top left field on the screen. Remarks: With Screens that have no fields: -------------------------------------------------- When S_ReadScreen is called after a help screen or menu screen has been displayed that has no data entry or display only fields: - User messages will be displayed on the bottom line of the screen. - The next key pressed is returned to your program. With Screens that contain only display only fields: -------------------------------------------------- When S_ReadScreen is called after a screen is displayed that contains all display only fields and no data entry fields: - The data in the screen record is displayed in the screen form. - User messages will be displayed on the bottom line of the screen. - The next key pressed is returned to your program. Page 28 With Screens that have data entry fields: -------------------------------------------------- When S_ReadScreen is called after a screen is displayed that contains at least one data entry field: - The data in the screen record is displayed in the screen form. - User messages will be displayed on the bottom line of the screen. - Data is entered and edited in one or more of the screen fields until one of the special keys is pressed. See "Detecting Special keys" for more information on the special keys. - If the ENTER key is pressed to end the data entry session, the contents of the screen fields are tested against any field processing statements that have been defined. If an error is detected, an error message is displayed and data entry is resumed. Defined C: int S_Point; int S_FirstField; void S_ReadScreen() Defined in Pascal: Var S_Point : Integer; S_FirstField : Integer; Procedure S_ReadScreen; Example of Usage: Pascal C ---------------------------- ---------------------------- Var Point_Hold : Integer; int Point_Hold; . . . . S_LoadScreen('Data_Entry'); S_LoadScreen("Data_Entry"); ===> S_Point := S_FirstField; S_Point = S_FirstField; While Not S_Esc Do while (!S_Esc) Begin { ===> S_ReadScreen; S_ReadScreen(); If S_Enter Then if (S_Enter) Begin { Process_Screen_Data; Process_Screen_Data(); S_ClearScreen(1); S_ClearScreen(1); S_Point := FirstField; S_Point = S_FirstField; End; } If S_F1 Then if (S_F1) Begin { ===> PointHold := S_Point; Point_Hold = S_Point; S_LoadScreen('Help_01'); S_LoadScreen("Help_01"); ===> S_ReadScreen; S_ReadScreen(); S_LoadScreen('Data_Entry'); S_LoadScreen("Data_Entry"); ===> S_Point := Point_Hold; S_Point = Point_Hold; End; } End; } . . . . ----------------------------- --------------------------- Page 29 In the above example we see a screen named "Data_Entry" loaded and displayed. S_Point is set to the first logical field on the screen. We see that Turbo ScrEdit will now process the screen until the ESCAPE key is pressed. If the ENTER key is pressed the contents of the screen record is processed and perhaps a record is generated. The screen is then cleared and S_Point is reset to the first logical field on the screen. If the F1 key has been pressed we see that Turbo ScrEdit stores the current field number that is being edited, loads a screen named "Help_01", and calls S_ReadScreen again. When any key is pressed, the "Data_Entry" screen is reloaded, S_Point is pointed back to the last field that was being edited, and data entry is resumed at the same field that was being edited when the F1 key was pressed. Parameters: None. Reading a single field. ------------------------------------------------------------- Procedure: S_ReadField Function: Displays the contents of a screen record in the screen form and allows a single field to be edited or new data entered. Variable: S_Point Function: Before calling S_ReadField: S_Point can be set to the number of the screen field to be edited by S_ReadField. If the field pointed to by S_Point does not exist, or is a display only field, or a dupe field, Turbo ScrEdit will issue an error message and return to your program when the next key is pressed. Returning from S_ReadField: S_Point will point to the last field that was being edited when data entry was interrupted by pressing one of the special keys. Remarks: When S_ReadField is called and S_Point is pointing to a valid data entry field: - The data in the screen record is displayed in the screen form. - User messages will be displayed on the bottom line of the screen. - Data is entered and edited in ONLY ONE of the screen fields until the cursor is moved out of the field by one of the TAB key, SHIFT TAB keys, LEFT ARROW key, RIGHT ARROW key, or when a character is typed in the last position of Page 30 the field, or when one of the other special keys are pressed. See "Detecting Special keys" for more information on the special keys. - If the ENTER key, TAB key, SHIFT TAB key, is pressed to end the data entry session, or if the field is typed full of characters, or if the LEFT ARROW key or RIGHT ARROW key is used to move the cursor out of the field, the contents of the field are tested against any field processing statements that have been defined for it. If an error is detected, an error message is displayed and data entry is resumed for the field. Defined C: int S_Point; void S_ReadField() Defined in Pascal: Var S_Point : Integer; Procedure S_ReadField; Example of Usage: Pascal C ---------------------------- ---------------------------- Var Point_Hold : Integer; int Point_Hold; . . . . S_LoadScreen('Data_Entry'); S_LoadScreen("Data_Entry"); S_Point := 0; S_Point = -1; S_Tab := True; S_Tab = 1; While Not S_Esc Do while (!S_Esc) Begin { If S_Tab Then if (S_Tab) If S_Shift Then switch (S_Point) Begin { Case S_Point Of case 2 : { 3 : S_Point := 2; S_Point = (S_Shift)? 1:0; 2 : S_Point := 1; break;} Else case 1 : { S_Point := 3; S_Point = (S_Shift)? 0:2; End; break;} Else default : { Case S_Point of S_Point = (S_Shift)? 1:2; 1 : S_Point := 2; break;} 2 : S_Point := 3; } Else S_Point := 1; End; ===> S_ReadField; S_ReadField(); If S_Enter Then if (S_Enter) Begin { Process_Screen_Data; Process_Screen_Data(); S_ClearScreen; S_ClearScreen(); S_Point := 0; S_Point = -1; End; } Page 31 If S_F1 Then if (S_F1) Begin { PointHold := S_Point; Point_Hold = S_Point; S_LoadScreen('Help_01'); S_LoadScreen("Help_01"); S_ReadKey; S_ReadKey(); S_LoadScreen('Data_Entry'); S_LoadScreen("Data_Entry"); S_Tab := False; S_Tab = 0; S_Point := Point_Hold; S_Point = Point_Hold; End; } End; } . . . . ----------------------------- --------------------------- In the above example we see a screen named "Data_Entry" loaded and displayed. S_Point is set to a value that will force it to go to field number one. We see that current screen is to be processed until the ESCAPE key is pressed. Next we see a case or switch statement that has been coded to control how the cursor will move from field to field. If the TAB key only is pressed the cursor will advance to the next screen field. If the SHIFT and TAB key is pressed, the cursor will advance to the previous field. If the ENTER key is pressed the contents of the screen record is processed and perhaps a data base record is generated. The screen is then cleared and S_Point is reset to force the cursor to the first field on the screen. If the F1 key has been pressed we see that the program loads a screen named "Help_01" and calls S_Readkey to allow the user to respond before continuing. When any key is pressed, the "Data_Entry" screen is reloaded, and data entry is resumed at the same field that was being edited when the F1 key was pressed. Parameters: None. Reading a single keystroke. ------------------------------------------------------------- Turbo ScrEdit has two procedures that can be used when no data entry is needed, but but rather the program is to be interrupted for some kind of response from the user. --------------------------------------------------------- Procedure: S_ReadKey Function: To display a screen and messages to the user of a program, and accept a keystroke response. Remarks: - When this procedure is called, if the screen has any data entry or display only fields on it, the contents of the screen record are displayed in the screen form. Page 32 - If a user message has been defined, it is displayed on the bottom line of the screen. - Turbo ScrEdit scans the keyboard until a key is pressed. If the key is a regular keyboard character, it is returned in the field S_Ch. See "Detecting Special keys" for more information on the special keys that can be tested for. Defined in C: void S_ReadKey(); Defined in Pascal; Procedure S_ReadKey(); Example of Usage: Pascal C -------------------------- -------------------------- . . . . If S_F1 Then if (S_F1) Begin { S_LoadScreen('Help_01'); S_LoadScreen("Help_01"); S_UserMsg := strcpy(S_UserMsg, 'Any Key to Continue'; "Any Key to Continue"); ===> S_ReadKey; S_ReadKey(); End; } . . . . --------------------------- -------------------------- In the code segment example above, the screen "Help_01" is displayed and the message "Any Key to Continue" is displayed on the bottom line of the screen. Turbo ScrEdit waits until a key is pressed and then returns the key to the program. Parameters: None. --------------------------------------------------------- Procedure: S_NextKey Function: Accepts a key stroke response. Remarks: - When this procedure is called, NO MESSAGES OR SCREEN DATA ARE DISPLAYED on the screen. If a user message has been defined it is discarded. - Turbo ScrEdit scans the keyboard until a key is pressed. If the key is a regular keyboard character, it is returned in the field S_Ch. See "Detecting Special keys" for more information on the special keys that can be tested for. Page 33 Defined in C: void S_NextKey(); Defined in Pascal; Procedure S_NextKey(); Example of Usage: Pascal C -------------------------- ------------------------- . . . . If S_F1 Then if (S_F1) Begin { S_LoadScreen('Help_01'); S_LoadScreen("Help_01"); ===> S_NextKey; S_NextKey(); End; } . . . . --------------------------- ------------------------- In the code segment example above, the screen "Help_01" is displayed and Turbo ScrEdit waits until a key is pressed. The value of the key pressed is then returned to your program. Parameters: None. Field editing features. ------------------------------------------------------------- Turbo ScrEdit reserves the use of several keys for editing data keyed into fields. TAB key. --------------------------------------------------------- For S_ReadScreen: Moves the data entry cursor from one field to the next. If the TAB key is pressed on the last field of the screen, the cursor will wrap around to the first field on the screen. When edit masks are used, TAB will move the cursor to the next section of the edit mask. For S_ReadField Returns to the calling procedure with the S_TAB key field set to test TRUE. When edit masks are used, TAB will move the cursor to the next section of the edit mask. For S_ReadKey, and S_NextKey: Returns to the calling procedure with the S_TAB key field set to test TRUE. Page 34 SHIFT TAB key. --------------------------------------------------------- For S_ReadScreen: Moves the data entry cursor from one field to the previous field on the screen. If the SHIFT TAB key is pressed on the first field of the screen, the cursor will wrap around to the last field on the screen. When edit masks are used, SHIFT TAB will move the cursor to the previous section of the edit mask. For S_ReadField Returns to the calling procedure with the S_SHIFT and S_TAB key indicators set to test TRUE. When edit masks are used, SHIFT TAB will move the cursor to the previous section of the edit mask. For S_ReadKey, and S_NextKey: Returns to the calling procedure with the S_SHIFT and S_TAB key indicators set to test TRUE. DELETE key. --------------------------------------------------------- For S_ReadScreen and S_ReadField Deletes the character from the field that the cursor is on. For S_ReadKey, and S_NextKey: Return S_DEL key indicator set to test TRUE. SHIFT DELETE key. --------------------------------------------------------- For S_ReadScreen and S_ReadField Deletes the character that the cursor is on and all the characters in the field to the right of the cursor. For S_ReadKey, and S_NextKey: Returns to the calling procedure with the S_SHIFT and S_Del key indicators set to test TRUE. INSERT key. --------------------------------------------------------- For S_ReadScreen and S_ReadField Swaps the system BIOS insert toggle key bit between ON and OFF states. Turbo ScrEdit determines if character insert mode is ON or OFF by monitoring the BIOS shift key byte. When Insert mode is ON, all characters are inserted into the line at the cursor. The cursor pushes the characters to the right and moves to the next field character position. For S_ReadKey, and S_NextKey: Swaps the system BIOS insert toggle key bit between Page 35 ON and OFF states. Turbo ScrEdit determines if character insert mode is ON or OFF by monitoring the BIOS shift key byte. Returns to the calling procedure with the S_INS key field set to test TRUE. BACK SPACE key. --------------------------------------------------------- For S_ReadScreen and S_ReadField; Erases the character to the left of the cursor and drags the character at the cursor and all the characters to the right of the cursor one character position to the left. For S_ReadKey, and S_NextKey: Returns to the calling procedure with the S_BkSp key field set to test TRUE. LEFT ARROW key. --------------------------------------------------------- For S_ReadScreen Moves the cursor one character position to the left in the current data entry field. If the cursor is on the first character position of the field, the cursor will move to the next empty character position in the previous data entry field. If the LEFT ARROW key is pressed on the first character of the first field of the screen, the cursor will wrap around to the right of the last character in the last field of the screen. For S_ReadField Moves the cursor one character position to the left in the current data entry field. If the cursor is on the first character position of the field, data entry is terminated for the field and S_SHIFT and S_TAB are set to test true. Control then returns to your program. For S_ReadKey, and S_NextKey: Returns to the calling procedure with the S_LEFT key field set to test TRUE. RIGHT ARROW key. --------------------------------------------------------- For S_ReadScreen Moves the cursor one character position to the right in the current data entry field. If the cursor is on the last character position of the field, the cursor will move to the first character position in the next data entry field on the screen. If the RIGHT ARROW key is pressed on the last character of the last field of the screen, the cursor will wrap around to the first character in the first data entry screen field of the screen. Page 36 For S_ReadField Moves the cursor one character position to the right in the current data entry field. If the cursor is on the last character position of the field, data entry is terminated for the field, S_TAB set to test TRUE, and control then returns to your program. For S_ReadKey, and S_NextKey: Returns to the calling procedure with the S_RIGHT key field set to test TRUE. Detecting Special Keys. ------------------------------------------------------------- This part of the manual tells you how to detect when the user of your program has pressed one of the special system keys other than the standard alphabetical, numerical, and punctuation keys. Any time the user of your program presses one of the keyboard "Function Keys" or one of the "Key Pad Cursor Control Keys" or holds down one of the "ALT" or "CTRL" keys and presses any other keyboard key, Turbo ScrEdit interrupts what it is doing and returns control to your program. Turbo ScrEdit has a number of predefined boolean variables that are set according to the last key or key combination that was pressed. Special considerations: --------------------------------------------------------- For S_ReadScreen and S_ReadField. ---------------------------------------------------- There are several keys that Turbo ScrEdit has reserved for use in editing the contents of screen field: Backspace............. (S_BkSp) Left Arrow............ (S_Left) Right Arrow........... (S_Right) Insert Key............ (S_Ins) Delete key............ (S_Del) Shift and delete...... (S_Shift, S_Del) In S_ReadScreen ONLY: Tab................... (S_Tab) Shift and Tab......... (S_Shift, S_Tab) When S_EnterAsTab is set to TRUE Enter key.......... (S_Enter) Shift and Enter.... (S_Shift, S_Enter) In the discussion that follows keep in mind that the above listed keys are not returned to your program when they are pressed, instead they are captured and used by Turbo ScrEdit. Page 37 For S_ReadKey and S_NextKey. ---------------------------------------------------- Because these routines are not used for editing screen fields, they will return all of the special keys discussed in this section. Function keys (F1 through F12) --------------------------------------------------------- Defined As: Pascal C ---------------------------- ----------------------- Var S_F1 : Boolean; unsigned char S_F1; S_F2 : Boolean; unsigned char S_F2; S_F3 : Boolean; unsigned char S_F3; S_F4 : Boolean; unsigned char S_F4; S_F5 : Boolean; unsigned char S_F5; S_F6 : Boolean; unsigned char S_F6; S_F7 : Boolean; unsigned char S_F7; S_F8 : Boolean; unsigned char S_F8; S_F9 : Boolean; unsigned char S_F9; S_F10 : Boolean; unsigned char S_F10; S_F11 : Boolean; unsigned char S_F11; S_F12 : Boolean; unsigned char S_F12; ---------------------------- ----------------------- Example of Usage: Pascal C ---------------------------- ---------------------- . . . . S_ReadScreen; S_ReadScreen(); If S_F1 Then if (S_F1) S_ClearScreen; S_ClearScreen(); If S_F2 Then if (S_F2) DeleteRecord; DeleteRecord(); If S_F9 Then if (S_F9) ScrollNextRecord; ScrollNextRecord(); If S_F10 Then if (S_F10) ScrollNextRecord; ScrollPrevRecord(); . . . . ---------------------------- ----------------------- The above code segment shows some ways you might use the function keys to trigger special processing in a program. Cursor control keys (key pad). --------------------------------------------------------- Read the manual section "Special Considerations" of "Detecting Special Keys". Some of the keys described here will work differently when you are using S_ReadScreen or S_ReadField than they will when you are using S_ReadKey or S_NextKey. Page 38 Defined As: Pascal C ---------------------------- ----------------------- Var S_Home : Boolean; unsigned char S_Home; S_End : Boolean; unsigned char S_End; S_PgUp : Boolean; unsigned char S_PgUp; S_PgDn : Boolean; unsigned char S_PgDn; S_Up : Boolean; unsigned char S_Up; S_Down : Boolean; unsigned char S_Down; S_Left : Boolean; unsigned char S_Left; S_Right : Boolean; unsigned char S_Right; S_Ins : Boolean; unsigned char S_Ins; S_Del : Boolean; unsigned char S_Del; ---------------------------- ----------------------- Example of Usage: Pascal C ---------------------------- --------------------- . . . . S_ReadScreen; S_ReadScreen(); If S_End Then if (S_End) S_ClearScreen; S_ClearScreen(); If S_Del Then if (S_Del) DeleteRecord; DeleteRecord(); If S_PgUp Then if (S_PgUp) ScrollNextRecord; ScrollNextRecord(); If S_PgDn Then if (S_PgDn) ScrollNextRecord; ScrollPrevRecord(); . . . . ---------------------------- ---------------------- The above code segment shows some ways you might use the cursor control keys to trigger special processing in a program. Alt and Ctrl key combinations. --------------------------------------------------------- Defined As: Pascal C ---------------------------- ----------------------- Var S_Alt : Boolean; unsigned char S_Alt; S_Ctrl : Boolean; unsigned char S_Ctrl; S_Ch : Char; unsigned char S_Ch; ---------------------------- ----------------------- Page 39 Example of Usage: Pascal C -------------------------- ---------------------- . . . . S_ReadScreen; S_ReadScreen(); ===> If S_Ctrl Then If (S_Ctrl) Begin { ===> If S_Ch = 'C' Then if (S_Ch == 'C') S_ClearScreen; S_ClearScreen(); If S_Ch = 'D' Then if (S_Ch == 'D') DeleteRecord; DeleteRecord(); If S_Ch = 'N' Then if (S_Ch == 'N') ScrollNextRecord; ScrollNextRecord(); If S_Ch = 'P' Then if (S_Ch == 'P') ScrollPrevRecord; ScrollPrevRecord(); End; } . . . . --------------------------- ------------------------ The above code segment shows some ways you might use the control key in conjunction with regular keyboard characters to trigger special processing in a program. Page 40 Shift Keys. --------------------------------------------------------- Defined As: Pascal C ---------------------------- --------------------------- Var S_Shift : Boolean; unsigned char S_Shift; S_LeftShift : Boolean; unsigned char S_LeftShift; S_RightShift : Boolean; unsigned char S_RightShift; ---------------------------- --------------------------- Example of Usage: Pascal C ---------------------------- ------------------------ . . . . S_Point := 0; S_Point = -1; While Not S_Esc Do while (!S_Esc) Begin { If S_Tab Then if (S_Tab) ===> If S_Shift Then switch (S_Point) Begin { Case S_Point Of case 2 : { 3 : S_Point := 2; S_Point = (S_Shift)? 1:0; 2 : S_Point := 1; break;} Else case 1 : { S_Point := 3; S_Point = (S_Shift)? 0:2; End; break;} Else default : { Case S_Point of S_Point = (S_Shift)? 1:2; 1 : S_Point := 2; break;} 2 : S_Point := 3; } Else S_Point := 1; End; S_ReadField; S_ReadField(); If S_Enter Then if (S_Enter) Process_Screen_Data; Process_Screen_Data(); End; } End; } . . . . ---------------------------- --------------------------- The above code segment shows a way that you can monitor the shift key to determine when to advance to the next or previous field on the screen. Other Keys. --------------------------------------------------------- Read the manual section "Special Considerations" of "Detecting Special Keys". Some of the keys described here will work differently when you are using S_ReadScreen or S_ReadField than they will when you are using S_ReadKey or S_NextKey. Page 41 Defined As: Pascal C ---------------------------- ---------------------------- Var S_Enter : Boolean; unsigned char S_Enter; S_Esc : Boolean; unsigned char S_Esc; S_Tab : Boolean; unsigned char S_Tab; S_BkSp : Boolean; unsigned char S_BkSp; ---------------------------- ---------------------------- Example of Usage (S_ReadScreen or S_ReadField): Pascal C ---------------------------- ---------------------------- . . . . While Not S_Esc Do while (!S_Esc) Begin { ===> S_ReadScreen; S_ReadScreen(); If S_Enter Then if (S_Enter) S_ClearScreen; S_ClearScreen(); End; } . . . . ----------------------------- --------------------------- Example of Usage (S_ReadKey or S_NextKey): Pascal C ---------------------------- ---------------------------- . . . . While Not S_Esc Do while (!S_Esc) Begin { ===> S_ReadKey; S_ReadKey(); If S_Enter Then if (S_Enter) ResumeProgram; ResumeProgram; If S_Tab Then if (S_Tab) LoadNextHelpScreen; LoadNextHelpScreen(); If S_BkSp Then if (S_BkSp) LoadPrevHelpScreen; LoadPrevHelpScreen(); End; } . . . . ----------------------------- --------------------------- Toggle key status indicators. --------------------------------------------------------- Turbo ScrEdit allows you to monitor the status of the system toggle keys. These switches are continually updated while Turbo ScrEdit is scanning the keyboard. Pressing the CAP key, NUM LOCK key, or the SCROLL LOCK key will not interrupt your program, only the toggle key indicator is set. The INSERT key works differently, when the INSERT key is pressed, your system toggles the system insert status between ON and OFF. Turbo ScrEdit monitors the BIOS Page 42 toggle key status byte, so it sets the S_InsertMode indicator to test TRUE if the system insert mode bit is on and FALSE if the system insert bit is off. Next, because the insert key is one of the keypad keys, Turbo ScrEdit will detect that a key has been pressed and will set S_Ins to test TRUE. If you have made a call to S_ReadScreen or S_ReadField, Turbo ScrEdit will intercept the insert key and continue editing the current field. If you have made a call to S_ReadKey or S_NextKey, Turbo ScrEdit will return control to your program and you may then test for and act on the S_Ins key. Defined As: Pascal C ---------------------------- ---------------------------- Var S_Caps : Boolean; unsigned char S_Caps; S_InsertMode : Boolean; unsigned char S_InsertMode; S_NumLock : Boolean; unsigned char S_NumLock; S_ScrollLock : Boolean; unsigned char S_ScrollLock; ---------------------------- ---------------------------- Resetting the key indicators. --------------------------------------------------------- Procedure: S_ResetKeyFlags Function: To reset all key indicator flags to FALSE. Remarks: Use this procedure when you need to make certain that all key status indicator flags have been reset. Defined in C: void S_ResetKeyFlags(); Defined in Pascal; Procedure S_ResetKeyFlags; Example of Usage: Pascal C -------------------------- ---------------------------- While Not S_Esc Do while (!S_Esc) Begin { S_ReadScreen; S_ReadScreen(); If S_Enter Then if (S_Enter) Begin { TestForValidData; TestForValidData(); If ErrorFound Then if (ErrorFound) ===> S_ResetKeyFlags; S_ResetKeyFlags(); End; } If S_Enter Then if (S_Enter) ProcessScreenData; ProcessScreenData(); End; } --------------------------- --------------------------- Page 43 In the above example when the ENTER key is pressed, the program calls a procedure that will check the contents of the screen record for valid data. If errors are found S_ResetKeyFlags is called to reset the ENTER key status indicator to prevent the next if statement from resulting in a TRUE condition and processing the screen data. Parameters: None. Duplicating fields or repeating fields. ----------------------------------------------------------------- There are occasions during data entry when the user of a program may wish to key a value into a field and have that value remain in the field until he chooses to change it. For example, an user may be keying journal entries into a program. A a number of the entries may have occured on the same day. It would be convient for the user to be able to type the transaction date into the date field and then press a button to tell the program to retain the date between each transaction. As the user keys entries into the journal, each time he enters a transaction, a record is created from the screen data and the screen is reinitialized for the next entry. The entire screen is erased except the date that he told the system to keep. To accomplish this, Turbo ScrEdit provides the facilities that allows your program to change a display only or data entry field into a duplicating field and then return it back to it`s original state. During data entry, as the user TABs from field to field, the cursor will skip over duplicating data entry fields as though they were display only fields. If the user wishes to change the value of a duplicating field he can use the SHIFT and TAB key combinations to move the cursor backwards into the field. He can then enter a new value and resume data entry. The new value in the duplicating field will then remain until it is changed or until the field is changed back to a regular data entry field and the screen cleared. Testing a fields dupe status. ------------------------------------------------------------- Procedure: S_IsDupe(FieldNumber) Function: Test the current status of the field that corresponds to FieldNumber. Remarks: This procedure is a boolean function that returns: TRUE = If the field that corresponds to FieldNumber has already been defined as a dupe field. FALSE = if the field that corresponds to FieldNumber is a normal data entry or display only field. Page 44 Defined C: unsigned char S_IsDupe(int index); Defined in Pascal: Procedure S_SetIs(index:Integer):Boolean; Example of Usage: Pascal C -------------------------------- ---------------------------- . . . . => If S_SetDupe(S_Point) Then if (S_SetDupe(S_Point)) S_UserMsg := strcpy(S_UserMsg, 'Already defined as dupe'; "Already defined as dupe"); . . . . ------------------------------- ------------------------------ In the above example the status of the field that corresponds to S_Point is tested. If the field has already been defined as a dupe field the message is issued. Parameters: FieldNumber.....An integer number of the field that is to be tested. Field numbers are listed on the Screen Listing generated by option F5 on the Turbo ScrEdit main menu. Defining a dupe field. ------------------------------------------------------------- Procedure: S_SetDupe(FieldNumber) Function: Changes the field that corresponds to FieldNumber in to a duplicating field. Remarks: This procedure is a boolean function that returns: TRUE = The field that corresponds to FieldNumber was successfully set to a dupe field. FALSE = There are two possible reasons that this function will return as false: 1 - The field that corresponds to FieldNumber is currently a dupe field. 2 - The field that corresponds to FieldNumber is the last data entry field on the screen. ** NOTE ** At least one field must remain a data entry field on a screen. If you attempt to set the last data entry field on a screen to a dupe field Turbo ScrEdit will return a value of FALSE and issue an error message. Defined C: unsigned char S_SetDupe(int index); Defined in Pascal: Procedure S_SetDupe(index:Integer):Boolean; Page 45 Example of Usage: Pascal C -------------------------------- ---------------------------- . . . . While Not S_Esc Do while (!S_Esc) Begin { S_ReadScreen; S_ReadScreen(); If S_Home Then if (S_Home) Begin { If S_IsDupe(S_Point) Then if (S_IsDupe(S_Point)) S_UserMsg := strcpy(S_UserMsg, ' Dupe Already Set ' " Dupe Already Set"); Else else ===> If S_SetDupe(S_Point) Then if (S_SetDupe(S_Point)) S_UserMsg := strcpy(S_UserMsg, ' Set as dupe. '; " Set as dupe. "); End; } End; } . . . . ------------------------------- --------------------------- In the above example, the user presses the HOME key to set the current data entry field as a dupe field. When the HOME key is pressed, the function S_IsDupe is used to check the status of the field. - If the field is currently defined as a dupe field, the message "Dupe already set" is issued. - If the field is not an active dupe field, S_SetDupe is called to establish dupe status for the field. If the call to S_SetDupe is successful the message "Set as dupe." is issued. If the call to S_SetDupe fails, no action is taken by the programmer, Turbo ScrEdit will issue the appropriate error message explaining why it could not change the status of the field. Parameters: FieldNumber.....An integer number of the field that is to be tested. Field numbers are listed on the Screen Listing generated by option F5 on the Turbo ScrEdit main menu. Page 46 Resetting a dupe field back to its original status. ------------------------------------------------------------ Procedure: S_ResetDupe(FieldNumber) Function: Restore a dupe field back to its original status. Remarks: The field that corresponds with FieldNumber, is restored to its original display only or data entry status. Defined C: unsigned char S_ResetDupe(int index); Defined Pascal: Procedure S_ResetDupe(index:Integer):Boolean; Example of Usage: Pascal C -------------------------------- ---------------------------- . . . . While Not S_Esc Do while (!S_Esc) Begin { S_ReadScreen; S_ReadScreen(); If S_Home Then if (S_Home) Begin { If S_IsDupe(S_Point) Then if (S_IsDupe(S_Point)) Begin { ==> S_ResetDupe(S_Point) S_ResetDupe(S_Point); S_UserMsg := strcpy(S_UserMsg, ' Dupe ReSet '; " Dupe ReSet "); End } Else else If S_SetDupe(S_Point) Then if (S_SetDupe(S_Point)) S_UserMsg := strcpy(S_UserMsg, ' Set as dupe. '; " Set as dupe. "); End; } End; } . . . . -------------------------------- --------------------------- In the above example, the user presses the HOME key to toggle the current data entry field between dupe field status and normal data entry status. Once the HOME key is pressed, the function S_IsDupe is used to check the status of the current data entry field. - If the field pointed to by S_Point is a dupe field already, S_ResetDupe is called to restore the field back to it`s original state. - If the field is a data entry field or a display only field, S_SetDupe is called to change the field into a dupe field. If the call to S_SetDupe is successful the message "Set as dupe." is issued. If the call to S_SetDupe fails, no action is taken by the Page 47 programmer. Turbo ScrEdit will issue the appropriate error message explaining why it could not change the status of the field. Parameters: FieldNumber.....An integer number of the field that is to be tested. Field numbers are listed on the Screen Listing generated by option F5 on the Turbo ScrEdit main menu. Clearing all dupe fields. ------------------------------------------------------------ Procedure: S_ClearDupes Function: Restore all dupe fields on the current data entry screen back to thier original status. Remarks: None. Defined C: unsigned char S_ClearDupes() Defined Pascal: Procedure S_ClearDupes; Example of Usage: Pascal C -------------------------------- ---------------------------- . . . . If S_End Then if (S_End) Begin { ==> S_ClearDupes; S_ClearDupes(); S_ClearScreen(1); S_ClearScreen(1); S_UserMsg := strcpy(S_UserMsg, ' Dupe Fields Cleared '; " Dupe Fields Cleared"); End; } . . . . -------------------------------- --------------------------- In the above example, when the user presses the END key, all the active dupe fields on the screen are reset to thier original status. The screen is then cleared and any initial values assigned in the screens field processing statements are applied to the screen fields. Finally a "user" message confirming that the program has cleared all the dupe fields, is set to be issued by the next call to S_ReadField. Page 48 Validating field values. ---------------------------------------------------------------- Field validation is when Turbo ScrEdit tests the values that have been keyed into the screen fields against the field processing statements defined for the fields of the screen. Normally field validation occurs automatically when the user of your program has completed filling in the screen form and presses the ENTER key. When S_EnterAsTab is set to TRUE, Turbo ScrEdit translates the ENTER key into a TAB key, and SHIFT and ENTER into SHIFT and TAB. Under these conditions Turbo ScrEdit will no longer detect that the ENTER key was pressed, and will not perform field validation automatically. In this case the programmer must code his own calls to Turbo ScrEdit's field validation procedures. Validating the entire screens contents. ------------------------------------------------------------- Procedure: S_ValidateScreen Function: Test the fields on the screen against any field processing statements that have been defined. Variable: S_ScreenValid Function: A boolean variable that will return the results of the call to S_ValidateScreen. Returns: TRUE = All fields passed validation as correct. FALSE = A field did not pass field validation. Variable: S_ErrorMsg Function: Returns NULL string if no errors are found, or returns the error message associated to the field validation statement that the field did not pass. Variable: S_Point Function: Returns a pointer to the last field edited if the screen contains valid data. Returns a pointer to the field that failed to pass the edit test if bad data is detected. Remarks: None. Defined C: void S_ValidateScreen() Defined Pascal: Procedure S_ValidateScreen; Example of Usage: Pascal C -------------------------------- ---------------------------- . . . . S_EnterAsTab := True; S_EnterAsTab = 1; Repeat do{ S_ReadScreen; S_ReadScreen(); If S_F1 Then if (S_F1) ==> S_ValidateScreen; S_ValidateScreen(); ==> Until S_ScreenValid; }while (!S_ScreenValid); ProcessScreenData; ProcessScreenData(); . . . . -------------------------------- ------------------------------ Page 49 In the above example the ENTER key has been set to act as the TAB key and the programmer has specified that the user of the program will press the F1 key to indicate that he has finished entering data into the screen and wants the data processed. When the F1 key is pressed the program calls S_ValidateScreen. - If the screens contents DO NOT pass the validation test, the repeat/until loop or do/while loop is not satisfied and control returns to S_ReadScreen with S_Point pointing to the offending field and S_ErrorMsg containing the error message. - If the screens contents DO pass the validation test, the repeat/until and do/while statements are satisfied and control drops out of the loop and continues with a call to ProcessScreenData. Parameters: None. Validating a single fields contents. ------------------------------------------------------------- Procedure: S_ValidateScreen Function: Test the fields on the screen against any field processing statements that have been defined for the fields on the screen. Variable: S_ValidateField (type:integer) Function: This field is used to specify the field that is to have its value tested against the field processing statements defined for it. Variable: S_ScreenValid (type:boolean) Function: A boolean variable that will return the results of the call to S_ValidateScreen. Returns: TRUE = All fields passed validation as correct. FALSE = A field has been found that did not pass field validation. Variable: S_ErrorMsg (type:S_Str80) Function: Turbo ScrEdit returns the programmers error message that was specified in the field validation statement that the field did not pass. Variable: S_Point (type:integer) Function: If the screens contents were valid S_Point will contain the field number of the field that is being edited before the call to S_ValidateScreen. Remarks: When S_ValidateScreen is called and S_ValidateField has been assigned a field index number, S_ValidateScreen will only validate the contents of the field pointed to by S_ValidateField. Defined C: void S_ValidateScreen() Defined Pascal: Procedure S_ValidateScreen; Page 50 Example of Usage: Pascal C ---------------------------- ---------------------------- . . S_EnterAsTab := True; S_EnterAsTab = 1; S_Point := 0; S_Point = -1; While Not S_Esc Do while (!S_Esc) Begin { If S_Tab Then if (S_Tab) If S_Shift Then switch (S_Point) Begin { Case S_Point Of case 2 : { 3 : S_Point := 2; S_Point = (S_Shift)? 1:0; 2 : S_Point := 1; break;} Else case 1 : { S_Point := 3; S_Point = (S_Shift)? 0:2; End; break;} Else default : { Case S_Point of S_Point = (S_Shift)? 1:2; 1 : S_Point := 2; break;} 2 : S_Point := 3; } Else S_Point := 1; End; Repeat do{ S_ReadField; S_ReadField(); If S_F1 Then if (S_F1) Begin { ===> S_ValidateField := S_Point; S_ValidateField = S_Point; ===> S_ValidateScreen; S_ValidateScreen(); End; } Until (S_Esc) Or }while ((!S_Esc)&& (S_Tab) Or (!S_Tab)&& ===> (S_ScreenValid) (!S_ScreenValid)) If (Not S_Esc) And if ((!S_Esc)&& (Not S_Tab) (!S_Tab)) Process_Screen_Data; Process_Screen_Data(); End; } . . ---------------------------- --------------------------- In the above example the ENTER key has been set to act as the TAB key. The programmer has specified that the user of the program will press the TAB to advance from field to field, the ESCAPE key to end the program, and the F1 key to indicate that he has finished entering data into the screen and wants the data processed. When the F1 key is pressed the field pointer S_ValidateField is assigned the value of the current field and the program calls S_ValidateScreen. - If the fields contents DO NOT pass the validation test, the conditions of the loop is not satisfied and control returns to S_ReadField with S_Point pointing to the offending field and S_ErrorMsg containing the error message. - If the screens contents DO pass the validation test, control drops out of the loop and continues with a call to ProcessScreenData. Page 51 Parameters: None. Changing DISPLAY only fields to DATA ENTRY Fields: ---------------------------------------------------------------- When screens are created, the fields on the screen are defined as display only fields or data entry fields. Display only fields are not normally accessible to the person sitting at the key board. Display only fields are used by the programmer for displaying information on the screen that the user can see, but can not change. Turbo ScrEdit allows the programmer to dynamically change data entry fields on the screen into "protected" fields by changing the field types from data entry to display only. Using this feature allows for such things as security access to be enforced on a screen field level. Likewise, Turbo ScrEdit allows display only fields to be changed into data entry fields. ------------------------------------------------------------ Procedure: S_SetDisplayOff(FieldNumber) Function: Changes the field type from DISPLAY ONLY to DATA ENTRY. Remarks: This procedure is a function that returns a result status that indicates if the field was successfully changed from display only to data entry. The status codes returned are: 0 - Successfully completed. 2 - The field indexed by FieldNumber does not exist. 3 - The field indexed by FieldNumber is not currently a display only field. 4 - Specified field number is not greater than 0. Defined C: int S_SetDisplayOff(int FieldNumber) Defined Pascal: Function S_SetDisplayOff(FieldNumber:Integer):Integer; Example of Usage: Pascal C -------------------------------- ---------------------------- Var Result : Integer; int Result; . . . . If User_Access > 3 Then if (User_Access > 3) ==> Result := S_SetDisplayOff(3); Result = S_SetDisplayOff(3); . . . . -------------------------------- ------------------------------ In the above example if the users system security is greater than level three, the user is given update access to the field number three on the screen, otherwise field number three will remain a display only field and the user would have look only privileges. Page 52 Notice that the program is not programmatically testing the result field to see if it is zero. Actually the value returned is used for debugging the program. The finished application should work correctly. Parameters: FieldNumber.....An integer number of the field that is to be tested. Field numbers are listed on the Screen Listing generated by option F5 on the Turbo ScrEdit main menu. Changing DATA ENTRY fields to DISPLAY only fields: ----------------------------------------------------------------- When screens are created, the fields on the screen are defined as display only fields or data entry fields. Display only fields are not normally accessible to the person sitting at the key board. Display only fields are used by the programmer for displaying information on the screen that the user can see but not change. Turbo ScrEdit also allows the programmer to dynamically change data entry fields on the screen into "protected" fields by changing the field types from data entry to display only. Using this feature allows for such things as security access to be enforced on field level. Even as Turbo ScrEdit allows changing fields from data entry to display only, it also allows changing display only fields to data entry fields. ------------------------------------------------------------- Procedure: S_SetDisplayOn(FieldNumber) Function: Changes the field type from DATA ENTRY to DISPLAY ONLY. Remarks: This procedure is a function that returns a result status that indicates if the field was successfully changed. The status codes returned are: 0 - Successfully completed. 1 - Specified field is the last data entry field on the screen. Turbo ScrEdit requires that data entry screens have at least one data entry field. 2 - Specified field does not exist on the screen. 3 - Specified field is already defined as display only. 4 - Specified field number is not greater than zero. Defined C: int S_SetDisplayOn(int FieldNumber) Defined Pascal: Function S_SetDisplayOn(FieldNumber:Integer):Integer; Page 53 Example of Usage: Pascal C -------------------------------- ---------------------------- Var Result : Integer; int Result; . . . . If User_Access < 3 Then if (User_Access < 3) ==> Result:=S_SetDisplayOn(9); Result=S_SetDisplayOn(9); While Not S_Esc Do while (!S_Esc) Begin { . . . . . . End; } . . . . -------------------------------- ------------------------------ In the above example if the user is assigned a security level that is less than three, field 9 is changed into a display only field, and the user will have look only privileges. Notice that the program segment above is not programmatically testing the result field to see if it is zero. Actually the value returned is used for debugging the program. The finished application should work correctly. Parameters: FieldNumber.....An integer number of the field that is to be tested. Field numbers are listed on the Screen Listing generated by option F5 on the Turbo ScrEdit main menu. Customizing Turbo ScrEdit Screens programmatically: ----------------------------------------------------------------- Programs created with Turbo ScrEdit can be totally configured to the end users tastes by writing custom color configuration routines using the procedures described in this section. For help in how to use these procedures see the examples coded in ScrDemo.P and ScrDemo.C and described in the tutor. Changing the colors of a screen ------------------------------------------------------------- Procedure: S_ChangeScreenColor (Function,BackGround,ForeGround, StartRow,EndRow,StartColumn,EndColumn) Function: Changes the color attribute bytes in the current screen record. Changes are performed in the area specified by STARTROW, STARTCOLUMN, and ENDROW, ENDCOLUMN. The color changes are made for all the characters that are of the type specified by FUNCTION to the color specified by BACKGROUND and FOREGROUND. Page 54 Remarks: Only the screen record is changed, not the actual screen that is visible on the video display. For information on how to view the new screen colors see section "Displaying the color changes" of this manual. Color changes are temporary and will be reset the next time the screen is loaded. For more information on how to make the changes permanent see section "Making color changes permanent" of this manual. This procedure is a function that returns a result status. The status codes returned are: 0 - Successfully completed. 1 - Function parameter is not in the range of 1 to 4. 2 - Background color is not in range of 0 to 7. 3 - Foreground color is not in range of 0 to 30. 4 - StartRow is not in range of 0 to 24. 5 - StartRow is greater than EndRow or EndRow is greater than 24. 6 - StartColumn is not in range of 1 to 80. 7 - StartColumn is greater than EndColumn or EndColumn is greater than 80. Defined C: int S_ChangeScreenColor( unsigned int Control, unsigned int Bg, unsigned int Fg, unsigned int StartRow, unsigned int EndRow, unsigned int StartColumn, unsigned int EndColumn) Defined Pascal: Function S_ChangeScreenColor( Control, Bg, Fg : Byte; StartRow, EndRow, StartColumn, EndColumn : Integer):Integer; See example on next page. Page 55 Example of Usage: Pascal C -------------------------------- ---------------------------- Const All_Chars : Byte = 0; int All_Char = 0; Single_Lines : Integer = 1; int Single_Lines = 1; Double_Lines : Integer = 2; int Double_Lines = 2; Block_Lines : Integer = 3; int Block_Lines = 3; Var Result : Integer; int Result; . . . . ReadConfigRecord; ReadConfigRecord(); . . . . ==> Result:=S_ChangeScreenColor( Result=S_ChangeScreenColor( All_Chars, All_chars, ConfigRec.Bg, ConfigRec.Bg, ConfigRec.Fg, ConFigRec.Fg, 1,1,80,24); 1,1,80,24); ==> Result:=S_ChangeScreenColor( Result=S_ChangeScreenColor( All_Chars, All_chars, ConfigRec.LogoBg, ConfigRec.LogoBg, ConfigRec.LogoFg, ConFigRec.LogoFg, 10,4,70,6); 9,3,69,5); . . . . -------------------------------- ------------------------------ In the first few lines of the above example the valid values for the CONTROL parameter of S_ChangeScreenColor are defined. Next we see that a procedure is performed that will read the configuration file. Next we see two calls to S_ChangeScreenColor using the color codes stored in the configuration record. In the first call to S_ChangeScreenColor, we see that all characters positions in the screen starting at column 1 and row 1 (when using C remember indexing starts at 0) through column 80 and row 24 will be assigned the color codes stored in the configuration record fields Bg and Fg. In the next call to S_ChangeScreenColor, we see that all characters positions in the screen starting at column 10 and row 4 through column 70 and row 6 will be assigned the color codes stored in the configuration record fields LogoBg and LogoFg. Parameters: Control....... Selects one of the four modes: 0 - Change all color attribute bytes for all character positions in the specified area of the screen. 1 - Change all single lines character's color attributes found in the specified area of the screen. Page 55 2 - Change all double line character's color attribute bytes found in the specified area of the screen. 3 - Change all block line drawing characters attribute bytes found in the specified area of the screen. Bg............ The new background color value to be used (valid values 0 through 7.) Fg............ The new foregound color value to be used (valid values 0 through 30 with 16 through 30 being blinking.) StartRow...... The top or first row of the screen to be changed. (valid values Pascal:1 through 24, C:0 through 23.) EndRow........ The bottom or last row of the screen to be changed. (valid values Pascal:1 through 24, C:0 through 23.) StartColumn... The top left starting column on screen. (valid values Pascal:1 through 80, C:0 through 79.) EndColumn..... The bottom right ending column on the screen. (valid values Pascal:1 through 80, C:0 through 79.) Changing field colors ------------------------------------------------------------- Procedure: S_ChangeFieldColor (FieldNumber,FieldMode,ForeGround,BackGround); Function: Changes the Normal, Display, and Prompt color codes that have been previously defined for the specified field. Remarks: When a field's colors are changed, the new color will be displayed on the screen by the next call to S_ReadScreen, S_ReadField, S_ReadKey, or S_RefreshScreen. Color changes are temporary and will be reset the next time the screen is loaded. For more information on how to make the changes permanent see section "Making color changes permanent" of this manual. This procedure is a function that returns a result status that indicates if the screen field was successfully changed. The status codes returned are: 0 - Successfully completed. 1 - Field specified does not exist. 2 - Field Mode specified is out of range 1 to 3. 3 - Specified Background color is not in the range of 0 to 7. 4 - Specified Foreground color is not in the range of 0 to 30. Page 57 Defined C: int S_ChangeFieldColor( unsigned int FieldNumber, unsigned int FieldMode, unsigned int Bg, unsigned int Fg) Defined Pascal: Function S_ChangeFieldColor( FieldNumber, FieldMode, Bg, Fg : Integer;):Integer; Example of Usage: Pascal C -------------------------------- ---------------------------- . . . . Var Result : Integer; int Result; . . . . Procedure Load_YourScreen; void Load_YourScreen() Begin { S_DelayScreen := True; S_DelayScreen = 1; S_LoadScreen('YourScreen'); S_LoadScreen("YourScreen"); For X := 1 to 9 do for (x=0;x<9;x++) Begin { ==> Result:=S_ChangeFieldColor( Result=S_ChangeFieldColor( X,0, X,0, ConfigRec.NormalBg, ConfigRec.NormalBg, ConfigRec.NormalFg); ConfigRec.NormalBg); ==> Result:=S_ChangeFieldColor( Result=S_ChangeFieldColor( X,1, X,1, ConfigRec.PromptBg, ConfigRec.PromptBg, ConfigRec.PromptFg); ConfigRec.PromptBg); ==> Result:=S_ChangeFieldColor( Result=S_ChangeFieldColor( X,2, X,2, ConfigRec.DisplayBg, ConfigRec.DisplayBg, ConfigRec.DisplayFg); ConfigRec.DisplayBg); End; } S_RefreshScreen; S_RefreshScreen(); . . . . -------------------------------- ------------------------------ In the code segment above we see that each time the procedure "Load_YourScreen" is called, the screen "YourScreen" is loaded, prepared for use, and displayed on the screen. Notice that the S_DelayScreen variable has been set to TRUE to keep the screen from being displayed. Next we see that a loop is performed to loop through nine screen fields changing the color assignments of the fields to the colors defined in the configuration record. When the loop is finish the procedure S_RefreshScreen is called to display the modified screen. Page 58 Notice also that the program segment above is not programmatically testing the result field to see if it is zero. Actually the value returned is used for debugging the program. The finished application should work correctly. Parameters: FieldNumber...The unique field number to be changed. FieldMode.....Specifies the field display mode that is to be assigned new color codes. There are three valid values: 0 = New colors are to be assigned to the "Normal" mode of the field (an empty field that is not being edited.) 1 = New colors are to be assigned to the "Prompt" mode of the field (field data is being entered or edited.) 2 = New colors are to be assigned to the "Display" mode of the field (None empty, not being edited.) ForeGround....Specifies the new foreground color for the field (valid values 0 through 30.) BackGround....Specifies the new background color for the field (valid values 0 through 7.) Displaying the color changes. ------------------------------------------------------------- Procedure: S_RefreshScreen Function: Repaints the current screen. Remarks: This procedure refreshes the current video display with the current screen, or last screen loaded by S_LoadScreen. ** WARNING ** if no screen has been loaded, your system will fill the display with random characters and will most likely hang. You will have to perform a hard reset and reboot to resume. Defined C: int S_RefreshScreen() Defined Pascal: Procedure S_RefreshScreen; See Example on next page. Page 59 Example of Usage: Pascal C -------------------------------- ---------------------------- . . . . Var Result : Integer; int Result; . . . . Procedure Customize_YourScreen; void Customize_YourScreen() Begin { S_DelayScreen := True; S_DelayScreen = 1; S_LoadScreen('YourScreen'); S_LoadScreen("YourScreen"); For X := 1 to 9 do for (x=0;x<9;x++) Begin { Result:=S_ChangeFieldColor( Result=S_ChangefieldColor( X,0, X,0, UserNormalBg, UserNormalBg, UserNormalFg); UserNormalBg); Result:=S_ChangeFieldColor( Result=S_ChangefieldColor( X,1, X,1, UserPromptBg, UserPromptBg, UserPromptFg); UserPromptBg); Result:=S_ChangeFieldColor( Result=S_ChangefieldColor( X,2, X,2, UserDisplayBg, UserDisplayBg, UserDisplayFg); UserDisplayBg); End; } S_StoreColorChanges; S_StoreColorChanges(); . . . . -------------------------------- ------------------------------ In the code segment above we see that when the procedure "Customize_YourScreen" is called, the screen "YourScreen" is loaded, prepared for use, and displayed on the screen. Because we set D_DelayScreen to TRUE, the screen is not displayed. Next we see that a loop is performed to loop through nine screen fields changing the color assignments of the fields to the user defined color codes for each of the field modes. Notice also that the program segment above is not programmatically testing the result field to see if it is zero. Actually the value returned is used for debugging the program. The finished application should work correctly. After the loop is finished and the field colors have been redefined, the new screen is displayed on the video by a call to S_RefreshScreen. Parameters: None. Page 60 Making color changes permanent. ------------------------------------------------------------- Procedure: S_StoreColorChanges Function: Updates the actual screen image and the screens field definitions that are stored in the current screen library file. Remarks: Use this procedure after you have changed the color attributes of the screen or its fields. This procedure makes changes permanent. Defined C: int S_RefreshScreen() Defined Pascal: Procedure S_RefreshScreen; Example of Usage: Pascal C -------------------------------- ---------------------------- . . . . Var Result : Integer; int Result; . . . . Procedure Customize_YourScreen; void Customize_YourScreen() Begin { S_DelayScreen := True; S_DelayScreen := 1; S_LoadScreen('YourScreen'); S_LoadScreen("YourScreen"); For X := 1 to 9 do for (x=0;x<9;x++) Begin { Result:=S_ChangeFieldColor( Result=S_ChangefieldColor( X,0, X,0, UserNormalBg, UserNormalBg, UserNormalFg); UserNormalBg); Result:=S_ChangeFieldColor( Result=S_ChangefieldColor( X,1, X,1, UserPromptBg, UserPromptBg, UserPromptFg); UserPromptBg); Result:=S_ChangeFieldColor( Result=S_ChangefieldColor( X,2, X,2, UserDisplayBg, UserDisplayBg, UserDisplayFg); UserDisplayBg); End; } S_StoreColorChanges; S_StoreColorChanges(); S_RefreshScreen; S_RefreshScreen(); . . . . -------------------------------- ------------------------------ In the code segment above we see that when the procedure "Customize_YourScreen" is called, the screen "YourScreen" is loaded, prepared for use, and displayed on the screen. Because we set S_DelayScreen to TRUE, the screen is not displayed. Next we see that a loop is performed to loop through nine screen fields changing the color assignments of the fields to the user defined color codes for each of the field modes. Page 61 Notice also that the program segment above is not programmatically testing the result field to see if it is zero. Actually the value returned is used for debugging the program. The finished application should work correctly. After the loop has changed the field colors, the screen and screen fields are rewritten to the screen file making the changes permanent. The screen is then displayed. Parameters: None. *