OS/2 Shareware BBS: 10 Tools

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

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / SCRNMS.ZIP / EDITOR.DOC next >

Wrap

Text File | 1990-03-15 | 44KB | 1,272 lines

--------------------------------------------------------------- Data Acquisition Functions Library --------------------------------------------------------------- Copyright (c) 1988-90, Christopher Laforet Copyright (c) 1990, Chris Laforet Software All Rights Reserved _________________________________________________________________ Chapter 1 Chapter 1 Introduction Introduction _________________________________________________________________ The data acquisition functions library contains a number of important routines for the handling of database fields, as well as some helpful utilities such as keystroke return, current date/time clock, tone generation, and error handling. This library requires the support routines of the Screen and Keyboard Library. Notice, these routines are made exclusively for LARGE MODEL, how else can serious applications be developed? This library uses my philosophy of data acquisition. The first step in this philosophy is that data is entered in fields delimited by underscores. The edit_field() function is fine- tuned to this fact. Why underscores? Well underscores show clearly the limits of a field regardless of color combinations. It is hard to miss that the following requires a 10 character name Name: __________ regardless of if the field is in monochrome or is in a different color. The second step in this philosophy is that trailing spaces in input is to be trimmed. There might be circumstances when this philosophical stance is incorrect, but 99% of the time it is true. Hence, the edit_field() function trims off trailing spaces. The third step in this philosophy is that one can never predict the future, and one might wish to take control of the incoming data and massage it to suit one's needs! Hence, the edit_field() function takes a pointer to a user-defined function which receives control every time a user presses a key. The last step of my philosophy is that programmers have intelligence and since this is a fact, they have the right to control every aspect of the data acquisition cycle. Hence there are no extremely high-level functions, but rather a set of mid-level tools to assist the programmer. These routines are Copyrighted (c) 1988-89 by Christopher Laforet and Copyrighted (c) 1990 by Chris Laforet Software. All rights are reserved by the copyright holder. There are absolutely no warranties implied or otherwise on these routines. Use at your own risk. Use them at your own risk. While no software can be guaranteed absolutely bug-free, these routines have been extensively tested and work on most IBM-PC compatible displays. The author and copyright holder shall in no way be held liable for any damages incurred by the use of these routines. --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 2 Page 2 _________________________________________________________________ Chapter 2 Chapter 2 Structures and Macros Structures and Macros _________________________________________________________________ These routines require that all compiling be done with byte packing or alignment (-Zp1 switch in MSC 5.xx or -a in Zortech 2.xx). Here is a listing of structures used in this library. struct choice { char choice_letter; char *choice_string; }; All editing functions (edit_field() pop_menu(), and select_menu()) return one of the following macro values which are defined in EDITOR.H: E_EXIT E_QUIT E_END E_FORE E_BACK E_PGDN E_PGUP ERROR For more information on how these returns are made, see the chapter entitled "Keystrokes." The following macros are also able to be returned from the user function passed to edit_field(): E_INVALID - invalid keystroke E_VALID - valid keystroke, repaint field E_NOPAINT - valid keystroke, do not repaint field The error() function uses one of the following constants to describe its actions: NOTICE - Notify of a warning message NON_FATAL - Indicate a non-fatal error has occurred FATAL - Indicate a fatal error has occurred and exit The clock_flag variable can be either CLOCK_ON (1) or CLOCK_OFF (0) depending on if the user wants the on-screen clock to show or not. The clock position variable is given as an int which is composed of (row << 8) + column (see the documentation on the screen library for more information of this format). --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 3 Page 3 _________________________________________________________________ Chapter 3 Chapter 3 Field Editing Formats Field Editing Formats _________________________________________________________________ The edit_field() function accepts as one of its arguments a string which describes the format of the input field from the keyboard. 3.1-Format Types 3.1-Format Types _________________________________________________________________ 3.1.1-Overriding Formats 3.1.1-Overriding Formats _________________________________________________________________ Format Description ------- ---------------------------------------------------- A Alpha Only 0 Numeric Only O AlphaNumeric Only X Alpha and printable symbols including space S Alpha and space only P AlphaNumeric and printable symbols including space Z Zip+4 rules 3.1.2-Format Modifiers 3.1.2-Format Modifiers _________________________________________________________________ Format Description ------- ---------------------------------------------------- U Uppercase all Alpha L Lowercase all Alpha C Capitalize first letters 3.1.3-Extended Format Modifiers 3.1.3-Extended Format Modifiers _________________________________________________________________ Format Description ------- ---------------------------------------------------- J Jump over (space holder for special formats) . Decimal point here (field must be completely numeric) --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 4 Page 4 3.1.4-Using Format Strings 3.1.4-Using Format Strings _________________________________________________________________ There are two forms of syntax in using format strings. The first of these (called Format String) is a short format which starts with the letter F (for format) is followed by an overriding modifier and optionally by a format modifier and then by an ascii maximum length (required). Formats like this may be like this: FAU12 - meaning up to a 12 character caps-only alpha field. FA60 - meaning up to a 60 character (caps) alpha field. F010 - meaning up to 10 numeric characters. Notice that on this type of field, length is NEVER absolute. The second type of format is called an Extended Format and actually "spells out" the exact way the field is to behave. Examples of this are: AA0000JA - Caps alphas with numbers and a skipped spot. 00j00j00 - Date formatting (MM/DD/YY form). 00000.00 - Dollars and cents format (not absolute). Depending on their form, these formats may be absolute (all or nothing). 3.1.5-Rules for Format Strings 3.1.5-Rules for Format Strings _________________________________________________________________ There are a few presumptions (rules?) used in setting up formats which dominate their usage. 1. Zip+4 (Z) rules cannot be used in extended formats. 2. Format modifiers (U,L,C) cannot be used in extended formats. 3. In extended formats, the case of letters is significant for alpha locations (e.g. "AaaA" means accept alpha as upper, lower, lower, upper). 4. No normal format string can begin with a modifier or extended modifier (e.g. this is illegal FCA10. The A comes before the C). 5. Z and 0 type fields cannot have format modifiers (C, U, L) in their makeup. 6. Any error in format type will return an E_ERROR return immediately upon calling edit_field(). You might wish to trap for this when you first set up your functions, but remove the trap to save code space once the function is fully debugged. --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 5 Page 5 3.2-User Defined Function for Editor 3.2-User Defined Function for Editor _________________________________________________________________ There is provision for a pointer to a user data handling function to be passed to edit_field(). This function may be used to get a specially formatted string (i.e. DOS pathname) or to somehow massage the data in the field based on the keystroke. This function will be called with every keystroke with a flag set to E_VALID if the keystroke was actually utilized by the editor or E_INVALID if it was not. The function must return an int and must be one of the above mentioned constants (E_VALID, E_INVALID, or E_NOPAINT). Notice that when the function receives a copy of the string being edited, it will be PACKED (that is to say, any skips represented in extended formats with the J modifier, will not be reflected in the string). Also, the offset value is the offset into the format template NOT the offset into the edited string. The function must return E_VALID if it doesn't want an error beep but requests that the field be repainted and the cursor repositioned. It must return E_NOPAINT if the function doesn't want the beep or a repaint. E_INVALID is reserved as a return requesting an error beep be sounded and the field be repainted but the cursor remain where it was prior to calling the function. If the function does nothing with the keystroke it must return exactly the same constant (E_VALID or E_INVALID) as it was passed in the action variable so that the correct default action might be accomplished. --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 6 Page 6 _________________________________________________________________ Chapter 4 Chapter 4 Functions Functions _________________________________________________________________ Here is a discussion of all functions available in this library. NOTICE: In order to select the OS/2 library (protected mode) you must define PROTECTED before the EDITOR.H file is #included (e.g. #define PROTECTED or -DPROTECTED on the compiler's command line). 4.1-Field Editing Functions 4.1-Field Editing Functions _________________________________________________________________ * int edit_field(int cursor, int hicolor, int locolor, int clock_flag, int clock_pos, int clock_color, char *format, char *string, int (*user_function)(int cursor, int hicolor, int locolor, int clock_flag, int clock_pos, int clock_color, char *format, char *string, int *offset, int *string_offset, int insert, int keystroke, int action)); The edit_field() function handles the actual physical editing of an ascii field. It uses a format string as was previously defined in the preceding section. It may be passed a pointer to a function to handle extra keystrokes or a NULL if none is required. The parameters to this function include offset which is a pointer to the current format, string_offset which is a pointer to the current offset in the string, and insert which is TRUE is insert mode is on. Clock flag may either be CLOCK_ON or CLOCK_OFF. Returns condition macro which made it exit (see above) such as E_EXIT. The edit field now handles decimal point entry correctly (calculator style) with the correct formatting (e.g. 0000.00 means 2 decimal places). --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 7 Page 7 If the help system is activated and if there is not already an active topic registered, this function registers a help topic called "field editor" so it is your responsibility to provide a help page with this tag name. Example: char fname[16]; int rtn; int change = 0; _vcw('_',LT_GRAY | ON_RED,0x410,15); /* cutout */ fname[0] = '0'; ... rtn = edit_field(0x410,YELLOW | ON_RED, LT_GRAY | ON_RED,CLOCK_ON,0x32, LT_GRAY | ON_BLUE,"FAC15",fname,NULL); if (rtn == E_EXIT) change = 1; /* editing change occurred */ if (rtn == E_EXIT || rtn == E_FORE) /* move to next field */ else if (rtn == E_BACK) /* move to previous field */ else if (rtn == E_QUIT) /* abort the editing */ else if (rtn == E_END) /* save the editing and go to next screen */ --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 8 Page 8 * int pop_menu(int start, int hicolor, int locolor, char *title, int max_choices, struct choice *choices, int shadow, int space, int clock_flag, int clock_pos, int clock_color); The pop_menu() function pops up a little box with a series of choices (with or without shadow) at the specified coordinate and returns one of the constants mentioned above. If the return is greater than ascii space (0x20), then the return value contains the ascii value of the choice made. Choices are always uppercased. If the help system is activated and if there is not already an active topic registered, this function registers a help topic called "popup menu" so it is your responsibility to provide a help page with this tag name. Example: struct choice yn[2] = { {'Y',"Yes"}, {'N',"No"}, }; int rtn; rtn = pop_menu(0x810,WHITE,LT_GRAY,"Employee?", 2,yn,1,1,CLOCK_ON,0x32,LT_GRAY | ON_BLUE); if (rtn >= ' ') { if (rtn == 'Y') ...; else if (rtn == 'N') ...; rtn = E_EXIT; /* so rtn will indicate change */ } --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 9 Page 9 * int select_menu(int start, int hicolor, int locolor, int selcolor, char *title, int max_choices, char **choices, int width, int selection, int clock_flag, int clock_pos, int clock_color); The select_menu() function opens a box on the screen (with a shadow) of specified width (if width > 30) and displays a list of strings for selection. If a character is hit from the keyboard and there is a string beginning with that character, the light- bar will go to that selection. The choices should be sorted alphabetically before this function is called (preferably case insensitively). If Enter is hit, E_EXIT will be in the lower nibble of the return value (return & 0xf) and the upper 12 bits (return >> 4) will have the offset of the chosen string. If selection is indicated other than 0, the highlight bar will be set to that selection (1 will be the second selection, etc). If the help system is activated and if there is not already an active topic registered, this function registers a help topic called "selection menu" so it is your responsibility to provide a help page with this tag name. Example: char *choices[5] = { "Management", "Clerical", "Maintenance", "Part Time Employee", "Other", }; int rtn; int emp_type; rtn = select_menu(0xa20,WHITE | ON_BLUE, LT_GRAY | ON_BLUE,WHITE | ON_RED,"Employee type", 5,choices,30,0,CLOCK_ON,0x32,LT_GRAY | ON_BLUE); if ((rtn & 0xf) == E_EXIT) { emp_type = rtn >> 4; ... rtn = E_EXIT; /* so rtn will indicate change */ } --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 10 Page 10 4.2-Special Screen Functions 4.2-Special Screen Functions _________________________________________________________________ * int askyn(char *title, char *prompt, int hicolor, int locolor, int clock_flag, int clock_pos, int clock_color); This function opens a box in the center of the screen and prints the title and prompt strings. Upon receipt of a Y or an N, the function returns 1 (Yes) or 0 (No). Example: int quit = 0; if (askyn("Confirm Exit","Are you SURE you want to exit the program?",WHITE | ON_RED, LT_GRAY | ON_RED,CLOCK_ON,0x32,LT_GRAY | ON_BLUE)) { quit = 1; } * struct window *open_message(char *message,int color); This function blows open a window in the center of the screen with the specified color. It prints the message centered in the box. It titles the box in blinking attribute text "For Your Information". You can then use the update_time() function periodically to keep the time updated. This function is meant for providing information while a lengthy process is being executed. Example: struct window *wndw; wndw = open_message("Please wait....reindexing database",WHITE | ON_RED | BLINK); while () /* reindexing database */ { ... update_time(0x32,LT_GRAY | ON_BLUE); } if (wndw) close_message(wndw); --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 11 Page 11 * void close_message(struct window *wndw); This function closes a window previously opened with the open_message() function. Example: See example for open_message() function. 4.3-Error Handling Functions 4.3-Error Handling Functions _________________________________________________________________ * void error(int type, char *string, int clock_flag, int clock_pos, int clock_color); This will blow open a box in the center of the screen and print the error message string. If the type is E_FATAL, then the program will terminate (using exit(1)) and the error message will be once again be printed, this time to stderr. The color of the box is set by the variable __error_color which is by default set to intense white on red. Example: if (!(fd = fopen("xxx","rb"))) error(FATAL,"Unable to open file!",0,0,0); * void set_critical_error(void); * int critical_error(int deverr, int errcode, int far *devhdr); These functions set up and handle DOS critical errors by blowing open a window in the screen and providing A)bort, R)etry and I)gnore error responses (Notice Abort doesn't abort the program but merely returns the error to the function call). To begin critical error processing, call set_critical_error() and the rest will be handled by Int 24h calls from DOS. The color of the box is set by the variable __error_color which is by default set to intense white on red. These functions are not available under OS/2. --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 12 Page 12 4.4-Keyboard Functions 4.4-Keyboard Functions _________________________________________________________________ * int read_keyboard(int clock_flag, int clock_pos, int clock_color); This function returns a keystroke from the keyboard mapped into an int. Normal characters are zero in the high byte and an ascii value in the low byte, but extended keystrokes contain a 1 in the high byte and the scan code in the low. Screen blanking is set for 60 seconds but can be changed by setting the __screen_blank_time variable to any number of seconds. A value of 0 indicates no blanking is to be done. If the clock_flag is on, the display of the clock will be of the form: [ MM/DD/YYYY CN|^A HH:MM:SS ] where C (Caps lock), N (Number lock), | (Shift), ^ (Ctrl), and A (Alt) are keyboard status flags. If jump is set on (see set_jump_on()), after the determined amount of time, longjmp() is executed to the previously prepared setjmp() location. * extern void far update_time(int clock_pos, int clock_color); This function serves to update the clock and keyboard status indicators during long periods of activity other than waiting for keyboard input and thus avoid moments wherin the clock appears to have stopped working. Example: See example for open_message() function. * void set_jump_off(void); * void set_jump_on(int total_time, jmp_buf jump_buffer); These functions set the system to execute a longjmp() to the previously set location (using setjmp()) after total_time seconds of keyboard inactivity. It is meant for systems which need to automatically log a person off after a certain amount of time. By default, of course the system is set to not jump. --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 13 Page 13 * void disable_boot(void); * void enable_boot(void); The disable_boot() function will disable the Ctrl-Alt-Del warm boot capability of the computer temporarily. The enable_boot() function restores everything to normal. NOTICE: Under no condition should a program exit without calling enable_boot() or else the machine would be in a highly unstable state and will eventually crash! This is an application which demands the use of the standard atexit() or onexit() functions. These functions is not available in OS/2. * int register_key(int key, int (far *handler)(int key, int clock_flag, int clock_pos, int clock_color)); This function sets a default function to occur upon receipt of the specified keystroke (key is as defined in keys.h). The handler is a pointer to the function which must return 1 if the keystroke must be passed along to the program after its action is complete, or return 0 to make the keystroke handler "eat" the keystroke and wait for the next key. *WARNING* The function must either guard against or handle reentrancy if it calls the read_keyboard() function. * void deregister_key(int key); This function removes the specified key from the default- handling queue and restores normal meaning to the keystroke. * int (far *query_key(int key))(); This function returns a pointer to the default function registered for the specified key or NULL if none is registered. --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 14 Page 14 4.5-Help Functions 4.5-Help Functions _________________________________________________________________ * int open_help(char *pathname,int hicolor,int locolor); This function opens the help file given in pathname and assigns the FILE * to helpfd. This function returns non-zero if an error occurs or 0 if it is successful. The help colors are set to the specified colors. The helpfile must have been created with HELPGEN (v 2.00 or greater) and may contain "hot links" to other help pages. For more information on HELPGEN, see the chapter "Using Helpgen." * void close_help(void); This function closes the help system's file and deallocates memory used for saving link information. This function must be called before opening a new help system. * void set_help_colors(int hicolor,int locolor); This function changes the default help colors set by open_help() to the new colors specified. * int set_help_key(int key); This function changes the default help key (originally F1) to the key code passed. It returns the previous keycode. * void set_help_colors(int hicolor,int locolor); This function changes the default help colors set by open_help() to the new colors specified. --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 15 Page 15 * void register_help(char *help_topic); * void deregister_help(void); * const char *query_help_topic(void); These functions allow you to set what help appears on the screen when the help key is pressed. register_help() registers the page tagname of the help to be active (i.e. the %page% name in the help source file). deregister_help() removes any help topic. query_help_topic() returns a pointer to the current help topic and this may be saved to be replaced later. If the string length of the help topic is 0, there is no topic registered. Example: char old_topic[41]; strcpy(old_help,query_help_topic()); register_help("Using Macros"); ... register_help(old_help); 4.6-Sound Functions 4.6-Sound Functions _________________________________________________________________ * void sound(int tone,int duration); * void beep(void); These functions should be self-explanatory. The tone value is in Hz, and the duration is measured approximately in milliseconds. --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 16 Page 16 _________________________________________________________________ Chapter 5 Chapter 5 Keystrokes Keystrokes _________________________________________________________________ The following are reserved keystrokes by the editing functions and must not be used by any user functions (specifically in the user function of edit_field): Esc or Alt-Q - Abort edit returning E_QUIT Enter - Save current edit returning E_EXIT C-End or Alt-X - Abort edit returning E_END (save) Tab - Abort edit returning E_FORE (next) S-Tab - Abort edit returning E_BACK (prev) PgUp - Abort edit returning E_PGUP PgDn - Abort edit returning E_PGDN C-PgUp - Page up on select_menu() C-PgDn - Page down on select_menu() Alt-C - Clear field LeftArrow - Move left one space RightArrow - Move right one space C-LeftArrow - Go to start of field C-RightArrow - Go to end of edited string Backspace - Delete character left of cursor Delete - Delete character under cursor Insert - Toggle insert mode on or off It should be obvious that some of these keys are meaningless in pop_menu() and select_menu()! --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 17 Page 17 _________________________________________________________________ Chapter 6 Chapter 6 Using Helpgen Using Helpgen _________________________________________________________________ Helpgen is the help file compiler for use with the help functions in this library. Helpgen is a bound application, which means that it works equally well under DOS or OS/2. Helpgen expects a flat-ASCII textfile (no embedded control characters) and will compile it to a file with the same base name as the file but with the extension .HLP. In order to demarcate certain parts of the help source file, there are special keywords. These are: %title% - used to set a title for the help system, or for the specific help page. %width% - reserved. The width is fixed at 74 columns. %height% - reserved. The height is fixed at 21 lines. %page% - Starts a new help page and labels it with a label for hypertext jumps. %rem% - indicates line is a comment line. %center% - indicates line must be centered. % - used to indicate "hot links" as shown below. Here is a sample help file: %rem% This is a sample file using the HELPGEN system %rem% %rem% First of all a global title. Used if local titles are not %rem% defined --> %title% Sample Help File %rem% Now for the first page. Page titles are limited to 40 %rem% characters. These are used by "hot links" and by the %rem% register_help() function --> %page% first page %center%This is the FIRST page of the help system. This can be used to jump to the %SECOND%second page% page or even to the %THIRD%third page% page of the system. You may use the arrow keys or tab to highlight the appropriate jump or just page sequentially through the help using the PgUp and PgDn keys! %page% second page %rem% This time we will use a local title --> %title% The Second Page %center%This is the SECOND page of the help system. --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 18 Page 18 %center%%Go back to the FIRST page%first page% %center%%Go to the THIRD page%third page% %page% third page %center%This is the THIRD and LAST page of the help system. %center%%Go back to the FIRST page%first page% %center%%Go back to the SECOND page%second page% -------- As you can see, the hot links are made by using the term to be highlighted in the first pair of % symbols followed by the page name to jump to (e.g. % Term to be Highlighted % page name %). --------------------------------------------------------- Data Acquisition Functions Library Data Acquisition Functions Library Page 19 Page 19 Contents Contents Chapter 1 Introduction 2 Chapter 2 Structures and Macros 3 Chapter 3 Field Editing Formats 4 3.1 Format Types . . . . . . . . . . . . . . . . 4 3.1.1 Overriding Formats . . . . . . . . . . . 4 3.1.2 Format Modifiers . . . . . . . . . . . . 4 3.1.3 Extended Format Modifiers . . . . . . . 4 3.1.4 Using Format Strings . . . . . . . . . . 5 3.1.5 Rules for Format Strings . . . . . . . . 5 3.2 User Defined Function for Editor . . . . . . 6 Chapter 4 Functions 7 4.1 Field Editing Functions . . . . . . . . . . . 7 4.2 Special Screen Functions . . . . . . . . . 11 4.3 Error Handling Functions . . . . . . . . . 12 4.4 Keyboard Functions . . . . . . . . . . . . 13 4.5 Help Functions . . . . . . . . . . . . . . 15 4.6 Sound Functions . . . . . . . . . . . . . . 16 Chapter 5 Keystrokes 17 Chapter 6 Using Helpgen 18 i