Power-Programmierung

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

/ Power-Programmierung / CD2.mdf / c / library / dos / edit / edutils / readme.doc < prev

Wrap

Text File | 1994-03-06 | 49.0 KB | 1,052 lines

------------------------------------------------------------------------------- ----------------------------- EDUTILS Version 1.0 ----------------------------- ------------------------------------------------------------------------------- Written By: Kenneth J. Macke (c) Copyright 1994 Kenneth J. Macke EDUTILS is a library of text-mode eduting functions designed to make it as easy as possible to add editing and viewing of files and string variables into your programs. To offer suggestions, please write the following address, or contact me at my Compuserve or Internet address. Compuserve address: 73020,2265 Internet address: 73020,2265@CompuServe.COM Kenneth J. Macke P.O. Box 11313 Cincinnati, OH 45211 Shareware is a wonderful concept that enables the programmer to write new and innovative programs and utilities that can be used by anyone on a "try before you buy" basis. The number of registrations for this program will show me the interest that exists for this utility, and will determine whether or not I release another improved version. If you find this utility useful, please register! To register, use the following chart to determine the registration fee, then send your name, address, and phone number with a check or money order made payable to Kenneth J. Macke to the above address. REGISTRATION FEES ┌────────────────────────────────┬─────────────────────┐ │ Description of User Account │ Registration Fee │ ├────────────────────────────────┼─────────────────────┤ │ Personal use only │ $15 │ │ Personal use to be sold │ $25 │ │ Business internal use │ $35 │ │ Business use to be sold │ $45 │ └────────────────────────────────┴─────────────────────┘ ------------------------------------------------------------------------------- DISCLAIMER EDUTILS has been thoroughly tested and should perform exactly as specified. However, as with all software, some problems may still exist. It is recommended that you test any application developed with EDUTILS thoroughly on test data to your satisfaction before using it in full. I cannot assume any responsibility for damage or lost data caused in part or in full by EDUTILS or any application developed with EDUTILS. -- Kenneth J. Macke ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- TABLE OF CONTENTS 1. Introduction.......................................................1 2. Installation.......................................................2 3. Choosing the Correct EDUTILS Library...............................3 4. Compiling and Linking Your Programs................................4 5. Using the EDUTILS Functions........................................5 6. Changing Editor Parameters........................................14 7. What Happened? Examining Result Codes............................19 APPENDIX A. A listing of the ed_set_default_parameters function.....22 APPENDIX B. Examples................................................24 APPENDIX C. Usage Notes.............................................25 ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- 1. Introduction 1 EDUTILS is a library of Editing Utilities which allows any programmer to add simple text-mode editing/viewing windows to their programs. With EDUTILS you can write very short, simple programs to create a README-style file viewer, and Panel Field Editor, or just simplify the task of acquiring character data from the user. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- 2. Installation 2 The EDUTILS Package consists of the following files: README.DOC -- This documentation file ORDER.DOC -- Registration information EDUTILS.H -- Include file EDUTILSS.LIB -- Small Memory Model Library EDUTILSM.LIB -- Medium Memory Model Library EDUTILSC.LIB -- Compact Memory Model Library EDUTILSL.LIB -- Large Memory Model Library FILEVIEW.C -- Example File Viewer program source code FILEVIEW.PRJ -- Example File Viewer Turbo C 3.0 Project File FILEVIEW.EXE -- Example File Viewer program executable PANEL.C -- Example Panel Editor program source code PANEL.PRJ -- Example Panel Editor Turbo C 3.0 Project File PANEL.EXE -- Example Panel Editor program executable In order to use EDUTILS, simply copy the EDUTILS.H file into the directory where your Turbo C Include files are stored, and copy EDUTILSS.LIB, EDUTILSM.LIB, EDUTILSC.LIB, and EDUTILSL.LIB into the directory where your Turbo C Library files are stored. For example, if your Include directory is C:\TC\INCLUDE, and your Library directory is C:\TC\LIB, then perform the following commands: copy EDUTILS.H C:\TC\INCLUDE copy EDUTILS?.LIB C:\TC\LIB ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- 3. Choosing the Correct EDUTILS Library 3 One of the main considerations in using EDUTILS in your program is choosing the correct EDUTILS library to use when linking your program. There are four libraries to choose from--one for each of four separate memory models: Small, Medium, Compact, and Large. You must select the library which uses the same memory model as the one that your compiler is set to use. For example, Turbo C uses the Small memory model by default. Therefore, you would use the Small model EDUTILS library, EDUTILSS.LIB. Use the following chart to determine which EDUTILS Library to use: Memory Model Map ┌──────────────┬───────────────────────┬──────────────┬──────────────────┐ │ │ SEGMENTS │ POINTERS │ EDUTILS │ │ Memory Model │ Code Data Stack │ Code Data │ Library to Use │ ├──────────────┼───────────────────────┼──────────────┼──────────────────┤ │ SMALL │ [64K] [----64K----] │ Near Near │ EDUTILSS.LIB │ │ MEDIUM │ [1MB] [----64K----] │ Far Near │ EDUTILSM.LIB │ │ COMPACT │ [64K] [----1MB----] │ Near Far │ EDUTILSC.LIB │ │ LARGE │ [1MB] [----1MB----] │ Far Far │ EDUTILSL.LIB │ └──────────────┴───────────────────────┴──────────────┴──────────────────┘ Figure 1-1 -- Determining which Memory Model and EDUTILS Library to use. Memory Model Descriptions 1. SMALL Memory Model. The Small Memory Model gives the program 64K bytes of Code space, and 64K bytes of Data space. If your program is relatively small and the maximum number of lines you wish to Edit with EDUTILS is 200 lines or less, then use the SMALL Memory Model, and compile with the EDUTILS Library "EDUTILSS.LIB". 2. MEDIUM Memory Model. The Medium Memory Model gives the program 1M bytes of Code space, and 64K bytes of Data space. If your program is relatively large and the maximum number of lines you wish to Edit with EDUTILS is 200 lines or less, then use the MEDIUM Memory Model, and compile with the EDUTILS Library "EDUTILSM.LIB". 3. COMPACT Memory Model. The Compact Memory Model gives the program 64K bytes of Code space, and 1M bytes of Data space. If your program is relatively small and the maximum number of lines you wish to Edit with EDUTILS is 2000 lines or less, then use the COMPACT Memory Model, and compile with the EDUTILS Library "EDUTILSC.LIB". 4. LARGE Memory Model. The Compact Memory Model gives the program 1M bytes of Code space, and 1M bytes of Data space. If your program is relatively large and the maximum number of lines you wish to Edit with EDUTILS is 2000 lines or less, then use the LARGE Memory Model, and compile with the EDUTILS Library "EDUTILSL.LIB". If you link with a library and you have disastrous results, then double-check the memory model that your compiler is using and select a different EDUTILS library. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- 4. Compiling and Linking your Programs 4 You can compile your programs either from within the TURBO C IDE (Interactive Development Environment) or from the command line. Include the following line at the top of your program: #include <EDUTILS.H> This includes the function declarations and other definitions needed for EDUTILS to operate. Within the Turbo C Development Environment, add the proper library to your Project. To see what memory model your program is currently using, hit ALT-O (to enter the "Options" menu), and hit enter with the cursor on the "Application..." selection. The Memory Model that your program is using is listed on the "Model" line. From the command line use the following command to compile your program: tcc -I<include dir> -L<library dir> program.c EDUTILSS.LIB where <include dir> -- The directory where the Include Files are stored <library dir> -- The directory where the Library Files are stored program.c -- The name of your program EDUTILSS.LIB -- The name of the EDUTILS library To use the Large Memory Model with your program, use the following command: tcc -ml -I<include dir> -L<library dir> program.c EDUTILSS.LIB where -ml -- Indicates that Large Memory Model should be used <include dir> -- The directory where the Include Files are stored <library dir> -- The directory where the Library Files are stored program.c -- The name of your program EDUTILSL.LIB -- The name of the EDUTILS library You do not need to use the -I and -L parameters if you use the default Include and Library directories. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- 5. Using the EDUTILS Functions 5 The main EDUTILS functions are: a. int ed_display_string (char * str, int screen_len, int max_len); b. int ed_display_string_xy (int x, int y, char * str, int screen_len, int max_len); c. int ed_edit_file_field (ED_PARMS * inparms, char * filename); d. int ed_edit_string (char * str, int screen_len, int max_len); e. int ed_edit_string_xy (int x, int y, char * str, int screen_len, int max_len); f. int ed_edit_text_field (ED_PARMS * inparms, void * store_lines, int max_lines, int max_chars); g. int ed_editor (ED_PARMS * inparms, char * filename, void * store_lines, int max_lines, int max_chars); h. void ed_set_default_parameters (ED_PARMS * inparms); A description of the features of each function is described below. Using the EDUTILS Functions (continued) 6 a. ed_display_string (); Display a string edit window and return Syntax: int ed_display_string (char * str, int screen_len, int max_len); This function will display a string edit window at the current cursor position using the current foreground & background colors. The arguments should be exactly the same as those passed later to ed_edit_string when string editing is performed. This function is meant to be called when there are several fields to be edited at once and you wish them to appear on the screen before the user is allowed to edit them. Variables: str -- Pointer to character string to be displayed screen_len -- Number of characters that can appear in the edit window at one time. If you do not wish any horizontal scrolling to take place, this value should be 1 larger than max_len. max_len -- Maximum number of characters that can be entered in the string. Using the EDUTILS Functions (continued) 7 b. ed_display_string_xy (); Display a string edit window and return Syntax: int ed_display_string_xy (int x, int y, char * str, int screen_len, int max_len); This function will display a string edit window at the specified cursor position using the current foreground & background colors. The arguments should be exactly the same as those passed later to ed_edit_string when string editing is performed. This function is meant to be called when there are several fields to be edited at once and you wish them to appear on the screen before the user is allowed to edit them. Variables: x -- Horizontal cursor position. Range is from 1 to 80. y -- Vertical cursor position. Range is from 1 to 25. str -- Pointer to character string to be displayed screen_len -- Number of characters that can appear in the edit window at one time. If you do not wish any horizontal scrolling to take place, this value should be 1 larger than max_len. max_len -- Maximum number of characters that can be entered in the string. Using the EDUTILS Functions (continued) 8 c. ed_edit_file_field (); Edit a File Syntax: int ed_edit_file_field (ED_PARMS * inparms, char * filename); This function will display an Edit Window and will allow the user to edit the contents of the file specified. The functionality of this function is completely modifiable, by altering the passed parameters. For example, the parameters can be set up to automatically fill the edit buffer with the contents of the file, and to automatically save the edit buffer into the file when editing is complete. Or, the parameters can be set so that editing of the file is not allowed--thus producing a file VIEWER. For more information about the editing parameters, refer to Section 6, Changing Editor Parameters. Variables: inparms -- Parameters to use during editing. For a complete description of the ED_PARMS parameters structure, refer to Section 6, Changing Editor Parameters. filename -- The name of the file to use when loading or saving. This should be the complete pathname referring to the file. Using the EDUTILS Functions (continued) 9 d. ed_edit_string (); Activate a string edit window Syntax: int ed_edit_string (char * str, int screen_len, int max_len); This function will invoke a string edit window at the current cursor position using the current foreground & background colors. The user will be allowed to view and modify the contents of the passed string. Control will return back to the program when the user presses a key corresponding to the function FN_QUIT, such as the ESC Key or the ENTER Key. Variables: str -- Pointer to character string to be displayed & edited screen_len -- Number of characters that can appear in the edit window at one time. If you do not wish any horizontal scrolling to take place, this value should be 1 larger than max_len. max_len -- Maximum number of characters that can be entered in the string. Using the EDUTILS Functions (continued) 10 e. ed_edit_string_xy (); Activate a string edit window Syntax: int ed_edit_string_xy (int x, int y, char * str, int screen_len, int max_len); This function will invoke a string edit window at the specified cursor position using the current foreground & background colors. The user will be allowed to view and modify the contents of the passed string. Control will return back to the program when the user presses a key corresponding to the function FN_QUIT, such as the ESC Key or the ENTER Key. Variables: x -- Horizontal cursor position. Range is from 1 to 80. y -- Vertical cursor position. Range is from 1 to 25. str -- Pointer to character string to be displayed & edited screen_len -- Number of characters that can appear in the edit window at one time. If you do not wish any horizontal scrolling to take place, this value should be 1 larger than max_len. max_len -- Maximum number of characters that can be entered in the string. Using the EDUTILS Functions (continued) 11 f. ed_edit_text_field (); Edit an array of text string variables Syntax: int ed_edit_text_field (ED_PARMS * inparms, void * store_lines, int max_lines, int max_chars); This function will display an Edit Window and will allow the user to edit the contents of the string variable specified. The functionality of this function is completely modifiable, by altering the passed parameters. For example, the parameters can be set up to automatically fill the edit buffer with the contents of the string, and to automatically save the edit buffer into the string when editing is complete. Or, the parameters can be set so that editing of the string is not allowed--thus producing a VIEWER. For more information about the editing parameters, refer to Section 6, Changing Editor Parameters. Variables: inparms -- Parameters to use during editing. For a complete description of the ED_PARMS parameters structure, refer to Section 6, Changing Editor Parameters. store_lines -- A pointer to the two dimensional array which holds the strings to be edited. The declaration of this variable in the calling program should be as follows (for example): char store_lines [200][80]; where 200 is the maximum number of lines to be allowed in the edit buffer, and 80 is the maximum number of characters per line. max_lines -- Refers to the maximum number of lines to allow in the edit buffer. In the above example, this would be 200. Note that this should EXACTLY match the first dimension of the declared variable, otherwise the results are unpredictable. max_chars -- Refers to the maximum number of characters per line to allow in the edit buffer. In the above example, this would be 80. Not that this should EXACTLY match the second dimension of the declared variable, otherwise the results are unpredictable. Using the EDUTILS Functions (continued) 12 g. ed_editor (); Edit an array of text string variables or a file Syntax: int ed_editor (ED_PARMS * inparms, char * filename, void * store_lines, int max_lines, int max_chars); This function is simply a combination of the ed_edit_file_field and ed_edit_text_field functions. When called, it will display an Edit Window and will allow the user to edit the contents of the file or string variable specified. The functionality of this function is completely modifiable, by altering the passed parameters. For example, the parameters can be set up to automatically fill the edit buffer with the contents of either the string or the file, and to automatically save the edit buffer into the string, the file, or both when editing is complete. Or, the parameters can be set so that editing of the string is not allowed--thus producing a VIEWER. For more information about the editing parameters, refer to Section 6, Changing Editor Parameters. Variables: inparms -- Parameters to use during editing. For a complete description of the ED_PARMS parameters structure, refer to Section 6, Changing Editor Parameters. filename -- The name of the file to use when loading or saving. This should be the complete pathname referring to the file. store_lines -- A pointer to the two dimensional array which holds the strings to be edited. The declaration of this variable in the calling program should be as follows (for example): char store_lines [200][80]; where 200 is the maximum number of lines to be allowed in the edit buffer, and 80 is the maximum number of characters per line. max_lines -- Refers to the maximum number of lines to allow in the edit buffer. In the above example, this would be 200. Note that this should EXACTLY match the first dimension of the declared variable, otherwise the results are unpredictable. max_chars -- Refers to the maximum number of characters per line to allow in the edit buffer. In the above example, this would be 80. Not that this should EXACTLY match the second dimension of the declared variable, otherwise the results are unpredictable. Using the EDUTILS Functions (continued) 13 h. ed_set_default_parameters (); Store default parameters in structure Syntax: void ed_set_default_parameters (ED_PARMS * inparms); This function resets all of the parameters contained in the ED_PARMS Editor Parameters structure to their default values. This function should be called to initialize every parameter structure that is defined before it is first used. To see the default values which are stored in the structure, refer to Appendix A, "A listing of the ed_set_default_parameters function" Variables: inparms -- Pointer to the parameter structure in which to store the default parameter values. For a complete description of the ED_PARMS parameters structure, refer to Section 6, "Changing Editor Parameters". ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- 6. Changing Editor Parameters 14 The following is the definition of the ED_PARMS parameter stucture. A more detailed description of each parameter follows. typedef struct { int max_num_lines; /* Max Num lines for this buffer */ int min_num_lines; /* Min Num lines for this buffer */ int max_line_length; /* Max Length of each line in the buffer */ int screen_top; /* Topmost row of editing window */ int screen_bottom; /* Bottommost row of editing window */ int screen_left; /* Leftmost column of editing window */ int screen_right; /* Rightmost column of editing window */ int editing_background; /* Editing Window Background Color */ int editing_foreground; /* Editing Window Foreground Color */ int highlight_background; /* Background Color for highlighted text */ int highlight_foreground; /* Foreground Color for highlighted text */ int overtype_cursor; /* CURSOR_LINE or CURSOR_BLOCK */ int insert_cursor; /* CURSOR_LINE or CURSOR_BLOCK */ int wrap_line; /* TRUE-words wrap to next line */ int remove_ending_spaces; /* TRUE-Spaces removed from ends of lines */ int remove_ending_chars; /* TRUE-Chars removed at end if others inserted before it */ int status_allowed; /* TRUE-Status will be displayed */ int status_x; /* X position of status on screen */ int status_y; /* Y position of status on screen */ int status_type; /* STATUS_ALL, STATUS_COL, STATUS_LINE, or STATUS_NONE */ int message_allowed; /* TRUE-Message will be displayed in position */ int message_x; /* X position of message on screen */ int message_y; /* Y position of message on screen */ int message_max_len; /* Maximum length of message to be displayed */ int error_on_borders; /* TRUE-Displays error msgs at top and bottom of files */ int load_automatically; /* LOAD_NONE, LOAD_ARRAY, LOAD_FILE, LOAD_BOTH */ int save_automatically; /* SAVE_NONE, SAVE_ARRAY, SAVE_FILE, SAVE_BOTH */ int restore_window; /* TRUE-Edit window will be replaced with previous contents on exit */ int vertical_scrolling; /* TRUE-Page Up & Down will be active */ int editing_allowed; /* TRUE-user will be allowed to modify buffer */ int exit_after_display; /* TRUE-Function will exit after display */ char default_filename [50]; /* Default File to load if no file specified */ char char_types [256]; /* Regular Character Types */ char esc_char_types [256]; /* Escape Character Types */ } ED_PARMS; Changing Editor Parameters (continued) 15 Detailed Parameter Descriptions ------------------------------- 1. int max_num_lines; /* Max Num lines for his buffer */ Indicates that maximum number of lines that can be allowed in the Edit Buffer. Change this value to keep a user from entering more lines in the buffer than you wish them to (especially for editing character string variables). The absolute maximum value for Small and Medium model programs is 200 lines, whereas the absolute maximum value for Compact and Large model programs is 2000 lines. 2. int min_num_lines; /* Min Num lines for this buffer */ This parameter is for future use and should be left alone. 3. int max_line_length; /* Max Length of each line in the buffer */ Indicates the maximum number of characters that can be allowed in a single line. Change this value to keep a user from entering more characters in a line than you wish them to. The absolute maximum value for this parameter is 256. 4. int screen_top; /* Topmost row of editing window */ int screen_bottom; /* Bottommost row of editing window */ int screen_left; /* Leftmost column of editing window */ int screen_right; /* Rightmost column of editing window */ These four parameters dictate the edit window size and position. The valid range for screen_top and screen_bottom is between 1 and 25. The valid range for screen_left and screen_right is between 1 and 80. 5. int editing_background; /* Editing Window Background Color */ int editing_foreground; /* Editing Window Foreground Color */ These two parameters indicate the Foreground and Background colors to use for the editing window. The values allowed here are between 0 (for BLACK) and 15 (for WHITE). The values correspond directly to the Turbo C Color Constants (BLACK, BLUE, GREEN, CYAN, etc) defined in <CONIO.H>. Changing Editor Parameters (continued) 16 6. int highlight_background; /* Background Color for highlighted text */ int highlight_foreground; /* Foreground Color for highlighted text */ These two parameters are for future use and should be left alone. 7. int overtype_cursor; /* CURSOR_LINE or CURSOR_BLOCK */ int insert_cursor; /* CURSOR_LINE or CURSOR_BLOCK */ These two parameters describe the look that the cursor should have in each of two edit modes. The values which can be used are CURSOR_LINE or CURSOR_BLOCK. 8. int wrap_line; /* TRUE-words wrap to next line */ This parameter is for future use and should be left alone. 9. int remove_ending_spaces; /* TRUE-Spaces removed from end of lines */ This parameter indicates whether spaces should be removed from the ends of each line after editing. The valid values for this parameter are either TRUE or FALSE. 10. int remove_ending_chars; /* TRUE-Chars removed at end if others inserted before it */ This parameter only has effect during editing while in INSERT mode. With remove_ending_chars set to FALSE, and in INSERT mode a character is typed and there are already the maximum number of characters possible in the current line, then an error will occur and the character pressed will not be inserted (You can not have any more than parms.max_line_length chars in a line at one time). With remove_ending_chars set to TRUE, and in INSERT mode a character is typed with the line already filled with characters, the characters at the end of the line will be eliminated to make room for the new characters being inserted. 11. int status_allowed; /* TRUE-Status will be displayed */ int status_x; /* X position of status on screen */ int status_y; /* Y position of status on screen */ int status_type; /* STATUS_ALL, STATUS_COL, STATUS_LINE, or STATUS_NONE */ The status_allowed parameter indicates whether or not the current Column or Line numbers will be displayed on the screen. Set this parameter to TRUE if you which them to be displayed, otherwise FALSE. The parameters status_x and status_y indicate the x & y positions of the current line & column status display on the screen. The status_type parameter can be set to STATUS_ALL, STATUS_COL, STATUS_LINE, or STATUS_NONE to indicate what numbers you would like displayed. For example with status_allowed set to TRUE and status_type set to STATUS_ALL, both the current line and the current column will be displayed. Changing Editor Parameters (continued) 17 12. int message_allowed; /* TRUE-Message will be displayed on screen */ int message_x; /* X position of message on screen */ int message_y; /* Y position of message on screen */ int message_max_len; /* Maximum length of message to be displayed */ The message_allowed parameter indicates whether or not the editor's messages will be displayed on the screen. Set this parameter to TRUE if you which them to be displayed, otherwise FALSE. The parameters message_x and message_y indicate the x & y positions of the message to be displayed on the screen. The message_max_len parameter indicates the maximum length of a message to be displayed on the screen. For example, you wish the displayed messages to start in column 45, you would want to set message_max_len to 35 so messages do not go past the end of the screen. 13. int error_on_borders; /* TRUE-Displays error msgs at top and bottom of files */ This parameter determines whether an error message will be produced and displayed on the screen when the user tries to move the cursor past the top of the file, end of the file, or past the maximum number of characters allowed in the line. Can be set to either TRUE or FALSE. 14. int load_automatically; /* LOAD_NONE, LOAD_ARRAY, LOAD_FILE, LOAD_BOTH */ int save_automatically; /* SAVE_NONE, SAVE_ARRAY, SAVE_FILE, SAVE_BOTH */ These two parameters determine the initial load and final save states of the edit buffer. The values for load_automatically are: LOAD_NONE, LOAD_ARRAY, LOAD_FILE, or LOAD_BOTH. When set to LOAD_NONE, the edit_buffer is not loaded with anything. When set to LOAD_ARRAY, the edit buffer is filled with the contents of the passed character array. When set to LOAD_FILE, the edit buffer is filled with the contents of the specified file. When set to LOAD_BOTH, an attempt is made to first load the edit buffer with the specified file, and if an error occurs, load the contents of the passed array. The values for save_automatically are: SAVE_NONE, SAVE_ARRAY, SAVE_FILE, and SAVE_BOTH. When set to SAVE_NONE, the edit buffer is not automatically saved. When set to SAVE_ARRAY, the contents of the edit buffer are automatically saved in the passed array. When set to SAVE_FILE, the contents of the edit buffer are automatically saved in the specified file. When set to SAVE_BOTH, the contents of the edit buffer are automatically saved in both the passed array and the specified file. Changing Editor Parameters (continued) 18 15. int restore_window; /* TRUE-Edit window will be restored */ When set to TRUE, this parameter indicates that the contents of the screen that were there before the edit buffer was first displayed will be restored. When set to FALSE, the edit buffer will remain on the screen on exit. 16. int vertical_scrolling; /* TRUE-Page Up & Down will be active */ When set to TRUE, Page UP and Page DOWN keys will be active. When set to FALSE, the Page UP and Page DOWN keys will not function during editing. 17. int editing_allowed; /* TRUE-user allowed to modify buffer */ When set to FALSE, this parameter indicates that the editing window should function as a Viewer only. That is, the user will not be allowed to modify any of the data that appears in the buffer. When set to TRUE, editing operations will work as normal. 18. int exit_after_display; /* TRUE-Function will exit after display */ When set to FALSE, control will remain in the EDUTILS function until the user pressed some key to cause it to exit. When set to TRUE, EDUTILS will display the Edit Window as required, but will then immediately exit and control will be passed to the calling program. The major purpose of this parameter is for Panel Editing Windows, where the program should display all of the fields in the Panel before the first field should be edited. 19. char default_filename [50]; /* Default File to load */ This parameter specifies the name of the file to use as a default file if there was not a file specified. 20. char char_types [256]; /* Regular Character Types */ char esc_char_types [256]; /* Escape Character Types */ These two parameters are for future use and should be left alone. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- 7. What happened? Examining Result Codes 19 The following is a listing of the ED_RESULTS result code structure. It can be accessed by the variable ed_results at any time through your program. It is declared externally from within the EDUTILS.H include file. typedef struct { int num_lines; int cur_line; int line_offset; int num_bytes; int mode; int x; int y; int offset; int pos; char filename [100]; // The name of the file which was edited int rc; // Return Code. TRUE-Success, FALSE-Failure char last_char; char last_char_extended; char last_function; char term_reason [100]; char last_message [81]; } ED_RESULTS; Examining Result Codes (continued) 20 The following is a brief explanation of the fields in the structure. a. num_lines An integer which gives the total number of lines in the edit buffer during the last edit session. b. cur_line An integer containing the number of the line which the cursor was on when the edit session terminated. Since the lines are numbered starting with 1, the first line would be represented by 1. c. line_offset An integer representing the number of lines which have scrolled off of the top of the screen. During normal edit sessions, when no vertical scrolling has taken place, this variable should contain 0. d. num_bytes An integer containing the number of characters in the edit buffer (not including carriage returns) upon termination of the edit session. e. mode An integer representing the insert/overstrike state when the edit session terminated. The possible values for mode are defined in EDUTILS.H and are: MODE_INSERT and MODE_OVERTYPE f. x The horizontal position of the cursor on the screen when the edit session ended. The range will be between 1 and 80. g. y The vertical position of the cursor on the screen when the edit session ended. The range will be between 1 and 25. h. offset An integer representing the number of character columns that were scrolled off of the left-hand side of the edit window. During a normal edit session where no horizontal scrolling occurs, this value will always be 0. i. pos An integer representing the current position of the cursor from within the current line. Each character is number starting from 0. Therefore, if the edit session was terminated with the cursor positioned on the 3rd character of the line, then pos should be 2. j. filename A character string which holds the path and filename of the file which was last passed to the edit function. k. rc An integer field referring to the return code returned by the function. In all honesty, I don't know whether or not the value returned in this variable can be trusted. Examining Result Codes (continued) 21 l. last_char A character variable which refers to the last character pressed by the user. This variable is useful for knowing what the user wishes to do next. The value returned in this variable is exactly equal to the ASCII code returned by the Turbo C "getch()" function. If an extended character was entered, last_char will be set to 0, and last_char_extended will be set to the extended key code. m. last_char_extended A character variable which normally contains 0 unless an extended character is entered. n. last_function An integer variable referring to the Function represented by the last key hit by the user. The possible values which can be returned are listed in the include file EDUTILS.H and start with "FN_". For example, if the ESC key is pressed, the last_function variable will be set to FN_QUIT. Or, if the F3 key is pressed during editing, which saves the file and exits the edit session, then FN_SAVE_AND_QUIT will be returned in last_function. Note that the functions assigned to each key can be modified. For default key assignments, refer to Appendix A, "A listing of the ed_set_default_parameters function". o. term_reason A character string variable which indicates the reason for the termination of the edit session. This variable is not currently in use. p. last_message A character string variable which contains the last message which was written to the screen. An example would be "No more than 80 characters can be in a line!". Note that the message window can be shut off so no messages will be written to the screen, but the messages will still be stored in this variable. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- APPENDIX A. A listing of the ed_set_default_parameters function 22 The following is the listing for the ed_set_default_parameters function. For the actual values of constants referred to below, look in the include file EDUTILS.H. (c) Copyright 1994 Kenneth J. Macke /********************************************************************/ void ed_set_default_parameters (ED_PARMS * inparms) { int I; inparms->max_num_lines = 500; // MAX_NUM_LINES; inparms->min_num_lines = 1; inparms->max_line_length = 100; // MAX_LINE_LENGTH; inparms->screen_top = 10; inparms->screen_bottom = 20; inparms->screen_left = 10; inparms->screen_right = 70; inparms->wrap_line = FALSE; inparms->remove_ending_spaces = TRUE; inparms->remove_ending_chars = FALSE; inparms->overtype_cursor = CURSOR_LINE; inparms->insert_cursor = CURSOR_BLOCK; inparms->editing_background = BLUE; inparms->editing_foreground = YELLOW; inparms->highlight_background = RED; inparms->highlight_foreground = WHITE; inparms->status_allowed = TRUE; inparms->status_x = 60; inparms->status_y = 24; inparms->status_type = STATUS_ALL; inparms->message_allowed = TRUE; inparms->message_x = 1; inparms->message_y = 24; inparms->message_max_len = 60; inparms->error_on_borders = TRUE; inparms->load_automatically = LOAD_FILE; inparms->save_automatically = SAVE_NONE; inparms->restore_window = TRUE; ed_set_default_parameters function (continued) 23 inparms->vertical_scrolling = TRUE; inparms->editing_allowed = TRUE; inparms->exit_after_display = FALSE; strcpy (inparms->default_filename, "readme"); for (I = 0; I < 256; I++) { /* Default all chars */ inparms->char_types [I] = 0; /* to invalid. */ inparms->esc_char_types [I] = FN_INVALID; } for (I = SMALLEST; I <= LARGEST; I++) /* Printables */ inparms->char_types [I] = FN_REGULAR; inparms->char_types [ESC] = FN_QUIT; inparms->char_types [BACKSPACE] = FN_BACKSPACE; inparms->char_types [ENTER_KEY] = FN_NEW_LINE_AFTER; inparms->char_types [25] = FN_DELETE_LINE; inparms->esc_char_types [LEFT] = FN_LEFT; inparms->esc_char_types [RIGHT] = FN_RIGHT; inparms->esc_char_types [UP] = FN_UP; inparms->esc_char_types [DOWN] = FN_DOWN; inparms->esc_char_types [PAGE_UP] = FN_PAGE_UP; inparms->esc_char_types [PAGE_DOWN] = FN_PAGE_DOWN; inparms->esc_char_types [HOME] = FN_START_OF_LINE; inparms->esc_char_types [END_KEY] = FN_END_OF_LINE; inparms->esc_char_types [DELETE] = FN_DELETE_CHAR; inparms->esc_char_types [INSERT_KEY] = FN_INSERT_MODE; inparms->esc_char_types [F2] = FN_SAVE_FILE; inparms->esc_char_types [F3] = FN_SAVE_AND_QUIT; inparms->esc_char_types [F4] = FN_QUIT; inparms->esc_char_types [F5] = FN_NEW_LINE_BEFORE; inparms->esc_char_types [ALT_L] = FN_MARK_LINES; } /* ed_set_default_parameters */ /********************************************************************/ ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- APPENDIX B. Examples 24 There are two examples included with EDUTILS. Both of which can and should be modified and used by registered users royalty free. EXAMPLE 1: FILEVIEW FileView is a README.COM-style file viewer which defaults to reading a file called 'README.DOC', but will read whatever file is passed to it on the command line. EXAMPLE 2: PANEL Panel is a simple Panel Field editor which prompts the user for their Name, Address, City, State, and Zip Code. When all of the fields have been entered, the program terminates and all of the information is printed. Both of the above examples are simple in their functionality, but are meant to demonstrate the possible uses for the EDUTILS functions. If you can think of other examples which might better demonstrate the features of EDUTILS, or if you can think of ideas for improving the existing examples, please feel free to write me through either electronic mail or snail-mail. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- APPENDIX C. Usage Notes 25 I. One important thing to remember about EDUTILS is that it expects the current text window to be defined as: window (1,1, 80,25); All edit windows defined in your programs and utilized with the EDUTILS functions will use this full screen window as a reference point. If you define the text window to be something other than full screen before you call an EDUTILS function, you will find that it has been reset to full screen once the function has terminated. II. Remember that the editing functions that are associated with keys can be assigned to different keys. To do this you must make the proper change to the "char_types" and "esc_char_types" variables within the ED_PARMS parameters structure. Refer to Appendix A, "A listing of the ed_set_default_parameters function" to see how the default key functions are assigned. Since this is more of an advanced feature and is not explained very well in this documentation, I will be happy to answer any questions you may have via electronic mail. ------------------------------------------------------------------------------- Thank you for trying EDUTILS. A lot of blood, sweat, and tears have gone into this project (especially the documentation). Since this is the first release of this product, I more than expect there to be some questions, complaints, and suggestions from the public at large. If have anything you wish to tell me about EDUTILS, no matter how small or insignificant, PLEASE WRITE! Your suggestions may influence a future version! Kenneth J. Macke P.O. Box 11313 Cincinnati, OH 45211 Compuserve address: 73020,2265 Internet address: 73020,2265@CompuServe.COM