Designer: To view a memory file through a Designer window, follow the steps below. In step 4, there are instructions on how to read the window from the Designer library file, instead of defining the window in code.
Code: The following program illustrates the steps required to create a memory file and view text from an ASCII text file, mf_basic.txt, located on the default drive. This program can be found in the tutorial area by the name of mf_basic.c.
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
General: The following are the steps for creating and viewing a memory file:
| 1 | Include the header file vv_wnkt.h. |
| 2 | Declare pointers to a memory file and a window. |
| 3 | Define a memory file with mf_def(). |
| 4 | Allocate a window and associate it with a memory file. |
| 5 | Write text to the memory file, in this case, by reading test from a disk file with mf_rd(). |
| 6 | Pass control to the user to browse through the memory file with mf_browse(). |
| 7 | Free the memory allocated for the memory file with mf_free(). |
| 8 | Free the memory allocated for the window with wn_free(). |
An explanation of each step follows.
Step 1: Include the header file vv_wnkt.h
The system header file vv_sys.h contains all definitions and prototype definitions to create and maintain memory files. Memory file viewing capabilities are defined in vv_wnkt.h. Since vv_wnkt.h includes the system header file, all you need to do is include vv_wnkt.h in your main program. In modules where you are only creating and maintaining memory files, it is only necessary to include vv_sys.h.
As always, vv_main.h must be the last Vermont Views header file included in your main program.
Step 2: Declare pointers to the memory file and the window.
The first step in creating a memory file is to declare a pointer to a memory file structure with MFILEPTR.
Because we need a window to display the memory file in, you must also declare a pointer to a window structure.
Step 3: Define a memory file with mf_def().
The memory file definition function mf_def() allocates memory for the memory file structure and the associated arrays and structures that underlie the memory file. It returns a pointer to the memory file structure. The call is as follows:
|
||
|
|
|
|
|
|
For maxrows, specify the number of rows in the memory file (not including a position for an end of file marker). The number of text lines placed in a memory file cannot exceed maxrows.
For maxcols, specify the maximum number of columns allowed on any one line, not including the terminal null that ends each line.
Specifying a large value of maxcols for a file will not directly affect the memory use of the file, but rather will only change the length of a string that can be stored on a single row of a file. Memory use is determined primarily by the amount of text that is placed in the memory file after the memory file is defined. If you want to be sure that lines being placed in a memory file will not be truncated, specify a safely large value for maxcols.
If you reading text from an ASCII disk file and are not sure of the correct memory file size, use the function mf_size(), discussed later in this chapter, to determine the number of rows and columns needed..
Naming Tip: Functions dealing with memory files contain the abbreviation "mf" for memory files.
Step 4: Create a window to associate with the memory file.
Code: Define the window by calling the function wn_mfdef():
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
rb, cb, rowq, and colq refer to the physical location and dimensions of the window on the screen. att specifies the attribute to use when displaying the memory file. bdrp defines the border type to use with the window. mfp is the memory file to associate with the window.
wn_mfdef() is very similar to wn_def(), the function used to allocate a window with a memory screen. wn_mfdef(), however, does not allocate a buffer for the window. The window uses the memory file as its buffer. For this reason, you cannot write to a window that is associated with a memory file; you must update the memory file instead. See Chapter 23, "About Windows," for more information on the arguments passed to wn_def() and wn_mfdef().
The window you define is the one in which the memory file will be viewed. wn_mfdef() also associates the memory file with the window. You can customize the appearance of the window by adding a border title, changing the border color, the margins, or adding scroll bars. Refer to Chapter 23, "About Windows" and Chapter 25, "Changing the Appearance of Windows" if you are not familiar with defining and using windows already.
Designer: You can also use a window that was created with the Designer to view a memory file. Read the window from the Designer library and associate a memory file with it as follows:
First, open the Designer library using the function dl_open():
|
||
|
|
|
|
|
|
dl_open() returns a pointer to the Designer library.
Next, read a window from the library using the function dl_wnget():
|
||
|
|
|
|
|
|
|
|
|
dl_wnget() returns a pointer to the window.
Finally, associate a memory file with the window by using the set window memory file function, sw_mf():
|
||
|
|
|
|
|
|
Step 5: Write text to the memory file.
Information can be placed in a memory file from either an ASCII disk file or by writing strings directly to the file. In our coding example above, lines were read from a file on disk by calling the memory file read function, mf_rd():
|
||
|
|
|
|
|
|
This function reads lines from the ASCII text file, places them in rows in the memory file (starting at row zero), and adjusts values in the MFILE structure so that view memory file functions will work properly.
If the file to be read in has more lines than the maximum number of rows in the memory file, some of the lines will not be read in. In this case, VV_ERR is set to Memory file:FILETOOBIG; however, this is not considered a fatal error, and the program will continue to run. You can check the value of VV_ERR after this call to see if this condition occurred.
If a line in the disk file is longer than the maximum number of columns in the memory file, the line transferred to the memory file is truncated at that length. This is not considered an error, and VV_ERR does not get set.
If mf_rd() is successful, it returns a one. mf_rd() can encounter a number of different runtime errors, including insufficient memory and errors opening or closing the specified text file. Although we did not do so in the coding example, you should test for these errors in your code.
Note: Because of the C convention of using the backslash to introduce special characters (such as '\t' for tabs), use two backslashes in PCDOS path names (e.g., "c:\\temp\\screen.txt").
Step 6: Pass control to the user to browse through the memory file with mf_browse().
By simply calling mf_browse(), you set the window on the screen, display the memory file in the window, and pass control to the user. The viewing event table VIEWETP is in use during memory file browsing.
How much the memory file origin shifts within the window when the user uses the arrow keys depends on the horizontal and vertical adjust quantities of the window. By default, the adjust quantities are both set to 1. This means that if the user is on the bottom row of the window and presses the Down Arrow key, the window origin in the memory file shifts up one row. On slower displays, you may want to increase the adjust quantity to avoid continuous updating of the window when the user is moving one row at a time through the memory file.
When the user presses the Quit key or the Exit key, the window is removed from the screen and mf_browse() returns AC_QUIT or AC_EXIT, respectively.
As with all event tables, the system event table (SYSETP) is searched first. If the event code is not found in the system event table, the viewing event table is searched. If the event code is found, the function associated with the event code is called. You can change the key assignments or add your own functions to the event table. For more information, see Chapter 38, "Writing Event Functions," and Chapter 39, "Installing Event Functions and Modifying Event Tables."
Step 7: Free the memory allocated for the memory file with mf_free().
If you are finished with viewing the memory file or using its contents, you can free all the memory allocated for the memory file with the free memory file function, mf_free():
|
Step 8: Free the memory allocated for the window with wn_free().
When you are through with the window, free the memory that was allocated for its structure with wn_free().
