The following tutorial example, dwn_basics.c, illustrates getting a window, wn_basics, from a Designer library named tutor.vvd. Try it on your system. You will find it helpful to run this tutorial program before reading the explanation.
The function ki(), which waits for a keystroke, is included in this program only to hold the window on the screen for viewing.
| #include <vv_des.h> | /*Enable Designer library | */ |
| include <vv_main.h> | ||
| int main(void) | ||
| { | ||
| DLIBPTR libp; | /* Pointer to library | */ |
| WINDOWPTR wnp; | /* Pointer to window | */ |
| vv_init(); | /* Initialize Vermont Views | */ |
| vs_clr(); | /* Clear the whole screen | */ |
| libp = dl_open("tutor.vvd"); | /* Open the Designer library | */ |
| wnp = dl_wnget("wn_basics", NULLP, libp); | /* Read window from library | */ |
| dl_close(libp); | /* Close the Designer library | */ |
| wn_up(wnp); | /* Display the window | */ |
| ki(); | /* Wait for a keystroke | */ |
| wn_dn(wnp); | /* Take window down | */ |
| wn_free(wnp); | /* Free the window | */ |
| vv_exit(); | /* Exit Vermont Views | */ |
| return(0); | /* Exit Vermont Views | */ |
| } |
The program illustrates the steps to using Designer windows in your applications. They are as follows:
| 1 | Include the system header files. |
| 2 | Declare the variables. |
| 3 | Open the library containing the window. |
| 4 | Read the window from the Designer library with dl_wnget(). |
| 5 | Close the library. |
| 6 | Set the window on the screen with wn_up() and wait for user input. |
| 7 | Remove the window from the screen with wn_dn(). |
| 8 | Free the window structure with wn_free(). |
Step 1: Include the system header files.
All definitions needed for the display facilities of Vermont Views, including windows, are contained in the vv_sys.h header file. Keyboard input is enabled by including the vv_key.h header file. Since this application uses a Designer library, you must also include the Designer header file, vv_des.h, which enables Designer library functionality. vv_des.h automatically brings in vv_sys.h and vv_key.h, so it is not necessary to include them explicitly in the code.
As with all Vermont Views applications, you must include the vv_main.h header file as the last Vermont Views header file in the application.
Step 2: Declare the variables.
Declare a variable of type WINDOWPTR, which is a pointer to a window structure.
Declare a Designer library pointer of type DLIBPTR, which is a pointer to a library structure.
Step 3: Open the library containing the window.
Before you can use a Designer window, you need to get it from the Designer library. First, the Designer library is opened with the function dl_open().n
|
Naming Tip: Functions that deal with a Designer library the abbreviation "dl" for Designer library.
In the code example, the call to open the library tutor.vvd is as follows:
|
dl_open() opens the file specified in the call and uses the data in the file to create a library structure. A pointer to the library structure is returned.
In applications using several library files, you may keep as many library files open as the operating system can handle. Under PCDOS, this is determined by the number of FILE entries in the config.sys file for the machine.
Step 4: Read the window from the Designer library with dl_wnget().
A window structure is allocated and the initial values of the structure members are set using the Designer library window get function, dl_wnget():
|
||
|
|
|
|
|
|
|
|
|
|
|
|
For funclistp, specify a pointer to the function list of user functions for the window or library. If you have attached activate or suspend functions to the window, you will need to specify a valid function list pointer. You can create this function list in the Designer; see the Designer User's Guide for details.
This function will allocate memory for the window structure and a memory screen of the appropriate size. It initializes the memory screen with the information read from the Designer library, and returns a pointer to the window structure. It will write to the memory screen buffer any lines, text, or boxes that were added to the window in the Designer.
Naming Tip: Functions that deal with a window have the abbreviation "wn" for window. Designer library functions begin with "dl."
Step 5: Close the library.
After you read the window out of the library, the library file can be closed. This is accomplished with the close Designer library function, dl_close().
|
The call in our example is as follows:
|
Step 6: Display the window and wait for user input.
After a window is declared and defined, it is placed on the screen with the window up function, wn_up():
|
wn_up() calls the up function stored in the window structure. By default, the function installed to put a window on the screen is wn_set(), which simply places the window on the screen. You can change this window up function, in the Designer or in code, to make the window explode or roll onto the screen.
When the window is set on the screen, the border, margins, and window contents are displayed as specified in the Designer.
After you have displayed the window, you may want to wait for the user to press a key before taking the window down. The function to wait for a keystroke is ki().
Step 7: Remove the window from the screen with wn_dn().
To remove the window from the screen, call the window down function, wn_dn():
|
wn_dn() calls the down function stored in the window structure. By default, the function installed to take the window off the screen is wn_unset(), which simply removes the window from the screen. You can change this window down function, in the Designer or in code, to make the window implode or unroll.
When a window is taken down, any screen region uncovered is automatically redrawn.
Note: Instead of using wn_up(), ki() and wn_dn() to display the window, wait for a keystroke, and then take the window down, you could make a single call to the window process function, wn_proc(). For a basic window, wn_proc() is the equivalent of calling wn_up(), ki() and wn_dn(). You will find more information about wn_proc() later in this chapter, and also in Chapter 26, "Working with Windows."
Step 8: Free the window structure with wn_free().
When you are through with a window, you can free all memory that was allocated for it. To do this, use the window free function, wn_free():
|
You should only free a window when it is not in use.
