Using a Designer Virtual Window

Windows can be created in code or by using the Designer. In general, the Designer is used to create either a basic window or a virtual window, and to put the associated text, lines, and boxes onto the memory screen.

The following tutorial example, dwnv_basic.c, illustrates getting a window, wnv_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.

#include <vv_des.h>

#include <vv_wnkt.h>

#include <vv_main.h>

int main()

{

    DLIBPTR libp;

/* VV Designer library pointer    

*/

    WINDOWPTR wnp;

/* Pointer to a window structure

*/

    vv_init();

/* Initialize Vermont Views

*/

    vs_clr();

/* Clear the video screen

*/

/*  Open the designer library and get window                    

    libp = dl_open("tutor.vvd");

    wnp = dl_wnget("wnv_basics", NULLP, libp);

    dl_close (libp);    

*/

/*  Process the window, when through free it up    

    wn_proc(wnp);      

    wn_free(wnp);      

*/

    csr_mv(vs_rowq() - 1, 0);

/* Move cursor to the last screen row

*/

    vv_exit();

/* Exit Vermont Views

*/

    return(0);

}

The program illustrates the steps to using Designer virtual windows in your applications. They are as follows:

Step 1: Include the system header files.

To enable the user to scroll the virtual window, you must #include vv_wnkt.h in your program. This links in the viewing event table. Since this application uses a Designer library, you must include the header file vv_des.h. The Designer header file, vv_des.h, enables Designer library functionality and automatically brings in vv_key.h and vv_sys.h.

As with all Vermont Views applications, you must include vv_main.h 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().

DLIBPTR dl_open(libname_stp)

UCHAR *libname_stp;

Naming Tip: Functions that deal with a Designer library begin with the abbreviation "dl" for Designer library.

In the example, the call to open the library tutor.vvd is as follows:

libp = dl_open("tutor.vvd");

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():

WINDOWPTR dl_wnget(name_stp, funclistp, libp)

UCHAR *name_stp;

/* Name of window to get from Designer library 

*/

UCHAR *funclistp;

/* Function list for activate and suspend funcs

*/

DLIBPTR libp;

/* Pointer to library containing window

*/

For funclistp, specify a pointer to the function list. You can generate the function list in the Designer. Only activate and suspend functions can be attached to a window. In our example, there are no user functions attached to the Designer window, so we simply pass a NULLP. For more information on processing windows, see Chapter 26, "Working with Windows."

This function will allocate memory for the window structure and a memory screen of the appropriate size. It initializes the window structure 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.

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().

dl_close(libp)

DLIBPTR libp;        /* Pointer to library to close         */

The call in our example is as follows:

dl_close(libp);

Step 6: Process the virtual window.

The function wn_proc() calls the processing function that was associated with the window when it was created. Since this is a virtual window, the processing function puts the window on the screen and allows the user to scroll through the text in the memory screen. When the user is done they may press the Quit or Exit key (KEY_ESC and KEY_F10 by default) to bring the window down and end processing of the window.

Step 7: 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():

void wn_free(wnp)

WINDOWPTR wnp;        /* Window structure to free            */

You should only free a window when it is not in use.