Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / BASIC / GLIB14.ZIP / FED.DOC < prev next >

Wrap

Text File | 1988-02-06 | 16.7 KB | 357 lines

Field Editor Keyboard Input Handler (C) InfoSoft, 1987, 1988 I. Introduction The care and use of FED can be a tad involved so it is documented separate from the rest of GIZLIB. This does not mean that it can or may be distributed seperately from the rest of GIZLIB or FED.DOC. There are several (indeed many!) text input handlers around. I know, because I have, or have looked at many of them. Many of them require significant editing to work, or they are not modular, or they require the event trapping switch, or they were inadeqaute in functionality. This is not to imply that FED is without its own failings, but overall, it is very flexible. FED, which originally stood for Field EDitor, is modular. It can be called from the main code of another program very easily. As is, FED is very flexible in most every aspect. You can change most all of the operating parameters with the change of a flag or two. Finally, FED does not require the use of any event trapping switch, it identifies extended key codes on its own, like most any text input routine should. II. FED Files The key FED files are: FED-DEMO.BAS - The demo EMP.DAT - A random file of 7 or so records for the demo CHGFLD.SUB - The FCODE handler from FED-DEMO that can be easily modified for use in your program. The demo is a pretty simple random file allowing you to edit the various records in the file. It is especially easy to use after reviewing this documentation. You are encouraged to read this first so that as FED-DEMO executes, you can notice some of the key features. III. FED Parameters, Syntax FED uses several switches and 3 arguments to control the flow and text input. The formal or direct parameters are: TEXT$ - The text string to edit. FSIZ - An integer telling FED the maximum length allowed for the TEXT$, the current text to be edited. FCODE - The exit code returned by FED to tell you HOW they completed that field or what key was pressed to exit FED. You should understand that you can actually use any names that suit you in a call to a SUB...STATIC / END SUB subroutine. That is, you could use ED$ instead of TEXT$, or T$, or whatever you want. FED will operate just as expected, as long as you pass them in the right order. The correct syntax: CALL fed(text$, fsiz%, fcode%) The importance of FSIZ is that FED will not allow input after that maximum size is reached, and maybe beep (bleep actually). FED does not change FSIZ on the return, so be sure to reset it for each successive call. IV. Incorporating FED to your code There are a few simple things to do to get FED running in your program: FED works off of 3 formal arguments (covered above) and several COMMON parameters shared with the main, calling program. This allows you to share some parameters with FED very easily such as Foreground Color, upper casing etc. The actual use and meaning of these common parameters are covered later, here we are explaining how to set up for FED to work in your program. This is done by simply including the following line in the beginning of your main code: COMMON /fedvars/ fg%, bg%, fgd%, bgd%, bleep%, edt%, nums%, num$, upcase% The meaning and use of the variables will be covered later, but in setting up FED for use, it is important that you list them EXACTLY as shown, ie in the order shown, WITH the type declarations. The first four are foreground and background colors and the rest are listed alphabetically. Note that such COMMON statements must appear in your code BEFORE any executable statements. If you are not familar with the use of COMMON it is suggested that you review pp 228-232 of the QB3 manual. Also refer to the FED-DEMO source for proper set up. In implementing the FED variables, we have opted to make several of them COMMON to allow FED to read and literally share the value of these varibles with your main program and at the same time, keeps you from having to pass all of them as formal arguments to FED. That is, intead of: CALL fed(t$,fsiz,fcode, fg,bg, fgd,bgd, bleep, edt, nums,num$, upcase) all we do is: CALL fed(t$, fsiz, fcode) Additionally, a benefit of this is that the COMMON switches are used or reset MUCH less often in use than say, the text$ would be; for example, most likely, you would set the color switches once (fg, fgd, bg and bgd), but text$ gets changed at almost every call. The only restriction in this is that unlike the formal arguments passed in the parentheses, the COMMON /fedvars/ variabls _MUST_ use the variable names shown. That is, while t$ can be changed to text$ or fcode can be used as fed.return.code as you please, fg must be referenced as fg, fgd as fgd, edt as edt, upcase as upcase etc etc. The use of a blockname (/fedvars/) prevents FED from interfering with other COMMON or COMMON SHARED variables, more precisely, it allows the USE of additional COMMON or COMMMON SHARED variables. To name additional variables as COMMON declare them like this: DEFINT a-z COMMON /fedvars/ fg%, bg%, fgd%, bgd%, _ bleep, edt%, nums%, num$, upcase% ' FED block defined COMMON SHARED /newblock/ arg1, arg2, arg3 ' different block COMMON SHARED a,_ ' "blank" block of b,_ ' COMMON variables c,_ z Note that /fedvars/ need not carry the SHARED attribute, but the use of a blockname allows FED to share those variables that it needs and ONLY those, ie a SIZE error is not encountered if you use other COMMON variables. This allows for maximum flexibility. Of the /fedvars/ variables, only edt, a more or less auxilliary flag is altered by FED. V. Internal Editting Keys Internally, FED does several things to provide a professional "look" to its operation. First, lets look at the editing fiunctions and keys recognized: HOME Places cursor at start of text or field. END Places cursor at first blank at end of the text. Ctrl - End Clear line from cursor to end of line. Ctrl - X Clear all text from current field. Ctrl - U Undoes current edit. This does not restore the text to it's form in a disk text file, but restores the text to the form it was UPON ENTRY TO FED. It cannot know what the text was or what form it was in PRIOR to the CALL. Arrow Keys Move one character Right or Left. FED will not allow the user to Cursor right into the hatched area if that means that more than 1 space trails the text. That is, via the the right arrow, it will not allow more than 2 consecutive spaces, as in "J. DOE " or "J Q Public". Multiple spaces can be achieved via the insert key or space however. Ctrl-Arrow Moves one word right or left Keys Ins Insert works as expected, allowing text to be inserted at the cursor, and changes the cursor to a block. The Insert state is toggled off upon exiting FED or "finishing" the field or text. Del As expected, deletes characters right of the cursor. No key state flags (such as a [ INS ] or [ Caps ] indicator) are put to the screen. This was viewed as intrusive in that where FED places the flag could be an unacceptable location in some applications, and it seemed to not be in the interest of speed, to be painting and repainting such indicators. VI. FED Return Codes - FCODE This is the half of the meat of the program (The other half is internal). FCODE returns to you a value dependant on what key is pressed to complete the editing of the text. Needless to say, FED has undergown several forms and formats since I first started work on it. The object of most changes has been to make the FCODEs more intuitive. The current state may not seem to be as intuitive as they could be at first glance, but in keeping the dual goals of ease of use AND flexibility, but the actual FCODE handler (the routine called CHGFLD in FED-DEMO) can be "canned", or predone to be incorporated into your program. FCODE Returns: Enter - 0 F1 - 1 F8 - 8 F2 - 2 F9 - 9 F3 - 3 F10 - 10 F4 - 4 PgUp - 11 Up Arrow - 5 PgDn - 12 Dn Arrow - 6 Ctrl-PgUp - 13 F7 - 7 Ctrl-PgDn - 14 Escape - 15 Note that not EVERY possible key is trapped or returned. Most notably, F5 and F6 are not trapped. This is not because FED is lazy or dumb, but simply to cut down on the number of FCODES you need to handle (and handle whether your program uses or needs those codes or not) and to leave 2 keys open for response to any standing ON KEY() key traps your main program may need to have active at all times. I have used FED in several applications and more often than not, the keys trapped as is, are MORE than enough to do the job. If you look at FED-DEMO you will see that it does quite a bit, in record paging, abort and save keys, and still has 3 or 4 FCODEs unused. In the long run, you should find that FED offers a suffient number of editting keys and with the use of a pre-done CHGFLD routine, it should be easy to handle the number of FCODES that it can return. Your distribution diskette or original archive should have a file called CHGFLD.SUB that can be easily edited (add a few RETURN <label>'s to it and paste it into your current code). FED and CHGFLD together should make text input and data entry applications very easy and simple. Throughout the demo, you can also note the integration of different GIZLIB functions and how they complement FED. VII. Internal Handling, COMMON Parameters FED does a few things internally on its own and a few others you control and change throughout the course of your program by resetting the COMMON parameters. If you are not familiar with SHARED parameters you should refer to your QB manual. These are not passed as formal arguments inside the parentheses when the program is CALLed but are set in your main program. Using the value of FSIZ as the maximum length allowed, FED provides hatching from the end of the actual text to that maximum length. If a string is longer than FSIZ upon entry to FED, it is truncated to the maximum length. ( It is important to note that upon GETting a string from a random file, QB pads the string with spaces from the end of the text for the length of the FIELD. That is, if you LSET "JOHN DOE" in a FIELD 15 characters long, after a GET, the name becomes "JOHN DOE ". If you pass this as is to FED with a FSIZ of 15, no hatching will appear because FED does not distinguish the spaces as blank text or attempt to modify the string. See STRIP in GIZLIB for QB3.) - FED also highlights the current text or data as well as providing the hatching. When the editing is completed, and one of the 15 FCODE keys are hit to exit the field (actually FED is exitted, and control is returned to you), the highlighting is turned off. This color control is handled thru the use of 2 sets of color codes: FG, BG and FGD and BGD. These must be assigned valid BASIC color codes in the course of your main code. At the start, FED uses the FGD, BGD (as in ForeGround_Data, BackGround_Data) colors and upon exitting, redisplays it in the FG, BG colors. These only need to be set once. - Caps or uppercase input from the keyboard can be forced on the fly (ie without a sepoarate call) via the UCASE switch. Set UPCASE to 1 or non zero for caps, 0 for to allow either lower or upper case. Note: Previous to GLIB 1.3, this parameter was named 'ucase', starting with GLIB 1.3, this is renamed 'upcase' to aviod conflicting with QB4's statement UCASE$. - Numbers ONLY can be selected in the same manner with the switch NUMS. When this is set, only numberic input is allowed, so to allow for a mixed string such as an address, NUMS should be OFF (nums=0). Additionally, you can redefine allowable characters for different entries via NUM$. For example, in a phone number entry the characters "()-" may be allowable beyond 0-9, but in a dollar based entry $ and "." may be allowable. So prior to the CALL for a phone entry NUM$ would be set to "1234567890()-", or ".1234567890$" for the dollar based entry. This method of defining the entire string rather than just the extra ()-$ or . characters was chosen to allow category type entries also. That is, to force, say a gender selection of M or F, set UPCASE to 1, NUMS to 1 and NUM$ to "MF". If NUM$ is set to null, (num$=""), it defaults to "1234567890". - If the text string upon exitting FED is different than it was at the start of the CALL to fed, then EDT is set to non-zero. This allows you to test to see if field in a record has been altrered. FED only sets it to 1 never to 0. Since FED is just handling the input for different strings, it never knows when a set of fields equalling a full record is completed. The EDT is how FED tells you that something has indeed been editted. ( Using this flag, you can include code in the CHGFLD routine to flash a message that an EDIT is in process, as is done in FED-DEMO. It is also useful in precluding certain functions if an edited record is not saved. An example of this is shown in FED-DEMO where paging is disallowed if a record is edited and unsaved. - The final COMMON parameter to cover is BLEEP, this is a switch to indicate whether sound is to be on or off. The sound is more of a bleep than a beep. If this switch is set on (non zero) it allows the bleep sound effect to sound at various times: - An attempt to cursor right when the string has reached FSIZ (maximum length). - An attempt to enter an invalid character (an alpha character when nums is ON). - When an inserted character will cause the text to exceed the maximum length. - Cursor left attempted left of first character position. - If cursor right appends more than 1 successive blanks to the text. Regardless of the state of bleep, FED disregards any such illegal activities. BLEEP just adds an error sound to the process. While the error sound has it's uses, it is not recommended that it be on all the time - there are time when it is inappropriate. In such cases, (such as in an office bullpen setting where such BLEEPING would be annoying), set BLEEP yo 0. In summary, the COMMON switch (0 or 1) parameters are: UPCASE - Convert alpha input to Uppercase NUMS - Allow (numeric) input only from NUM$ NUM$ - Character string filter of allowable input to be used if NUMS is not 0. FGD, BGD - Foreground and Background colors to diplay the string in while that string is undergoing editing via FED. FG, BG - Colors FED restores the string to upon exiting FED. EDT - Flag set by FED to show if text is changed. BLEEP - Switch to turn on or off BLEEPER error signal.