Basic Windows

Our second window program, wn_basics.c, writes "Hello, world" in a window. 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.

The program illustrates the steps to use a basic window to display information to a user and wait for a key to be pressed. They are as follows:

Step 1: Include the system header files vv_key.h and vv_main.h.

All definitions needed for the display facilities of Vermont Views, including windows, are contained in the vv_sys.h header file. The header file to enable keyboard input is vv_key.h. #include vv_key.h in your application. Since vv_key.h #includes vv_sys.h, it is not necessary to #include vv_sys.h explicitly.

As always, you must #include vv_main.h, which contains the global variables for the system, as the last Vermont Views header file in the main program.

Step 2: Declare a pointer to a window structure.

Declare a variable to be of type WINDOWPTR. WINDOWPTR is a typedef for a pointer to a window structure. The structure definitions can be found in the "Structures" section of the Function Reference.

Step 3: Allocate and initialize the window with wn_def().

A window structure and a memory screen of the appropriate size are allocated and the initial values of the structure members are defined using the window definition function, wn_def():

WINDOWPTR wn_def(rb, cb, rowq, colq, att, bdrp)

int rb;

/* Beginning row of window

*/

int cb;

/* Beginning column of window 

*/

int rowq;

/* Number rows to make window

*/

int colq;

/* Number columns to make window

*/

UCHAR att;

/* Attribute for writing to window 

*/

BORDERPTR bdrp;

/* Pointer to border to use for window

*/

Naming Tip: Functions that deal with a window have the abbreviation "wn" for window.

Specifying the Location and Size of the Window (rb, cb, rowq, colq)

For the first two arguments, rb and cb, you specify the screen coordinates of the top left corner of the window. The top left corner of the screen has the coordinates of (0,0). The arguments rowq and colq specify the number of rows and columns you want the window to take up on the screen. This size includes the frame of the window, so you need to account for the border if you specify it in bdrp, and for margins if you plan to add them to the window.

To make your applications portable, you can use vs_rowq() and vs_colq() to specify the size and location of the window. vs_rowq() returns the number of rows on the screen, and vs_colq() returns the number of columns on the screen.

For example, to have a message line window that is the width of the window and on the last line of the screen, use the following call to wn_def():

wn_def = wn_def(vs_rowq()-1, 0, 1, vs_colq(), LERROR, BDR_SLNP);

Specifying the Window Attribute (att)

Video display in the Vermont Views system is controlled by logical attributes. Logical attributes are defined such that monochrome attributes are used when the program is running on a monochrome display and color attributes are used when the program is running on a color display.

The window attribute, or the color of the window, is set to the logical attribute specified in the att argument. The window attribute specifies the background color of the window and the color used by default when writing characters to the window. By default, the attribute specified in wn_def() is also used for the border and margins.

In the example program, the window attribute is set to LNORMAL. LNORMAL is a logical attribute that is set to appear on the screen as normal on a monochrome display and as white on blue on a color display. Table 23.1 lists a sampling of the logical attributes available for use. For a complete list of the system-defined logical attributes, or for more information about creating your own logical attributes, see Chapter 46, "Controlling Color with Logical Attributes."

Table 23.1: Partial List of Logical Attribute Definitions

Specifying the Window Border (bdrp)

Table 23.2 lists the defined pointers to the system borders and what type of borders they are. Appearance of borders is operating system dependent. Specify one of these for the bdrp argument.

Table 23.2: Border Types

In the example program, the statement:

wnp = wn_def(5, 5, 10, 35, LNORMAL, BDR_DLNP);

allocates a window structure and initializes it to define a window that starts at the coordinates (5, 5) on the physical screen. The window has 10 rows, 35 columns, and has a double-line border. The window attribute is LNORMAL. The inside work area of this window has 8 rows and 33 columns since the border is taking up one row and column on each side.

Processing Function for a Basic Window

Each window is assigned a processing function when it is created. The processing function associated with a basic window created with wn_def() puts the window on the screen, waits for the user to press a key, and then removes the window from the screen.

Defaults Set by wn_def()

When a window is created in code, default values used for members not specified in the call are copied from the global window template WN_WNP. Unless changed by the application, WN_WNP has no margins, title, border text, shadows or scroll bars. The virtual cursor and the buffer origin are at (0,0), horizontal and vertical scrolling quantities are set to 1, and the maximum number of lines to scroll up when writing to a full window is set to AS_NEEDED. The following window options are turned on: word wrap, virtual cursor advance, and clear-to-end-of-row. The logical attribute array is set to NULLP (indicating the system array will be used). wn_set() and wn_unset() are used for the window up and down functions. The video screen is set as the window's destination and FULL_WNP is assigned as its parent window.

If values other than the defaults are desired, assign them with the set window functions after defining the window. For more information on these functions, see Chapter 25, "Changing the Appearance of Windows." Refer to the description of wn_def() in the Function Reference for more information on the default settings.

Step 4: Write to the window.

The function v_st() is a basic function for writing a string to a window. Writing to windows is explained in more detail in Chapter 24, "Writing to Windows." The two v_st() calls in the wn_basics.c tutorial program,

v_st("Hello, world!\n", wnp); 

v_st("Press any key to continue.\n", wnp);

write the specified strings to the window. The characters are written using the window attribute. In this case, the window attribute was specified in the wn_def() call and is LNORMAL. Thus, the string appears as normal text on a monochrome display and as white characters on a blue background on a color display under PCDOS and other memory-mapped displays.

Output to windows happens within the working area of a window, the area within the window's margins. By default, wn_def() sets the top, bottom, left and right margins to zero.

The location of the output is controlled by the location of the window's virtual Virtual cursor. The virtual cursor has coordinates based on the upper-left corner of the working area. The position is automatically updated by most of the window output functions.

Output automatically starts at the top-left corner of the working area of the window, which corresponds to a virtual cursor location of (0, 0). The virtual cursor stays within the margins of the window. Thus, the string "Hello, world!" is written just within the border of the window since the default is to have no margins.

Output to a window can be done simply, as in wn_basics.c, but there are a wide variety of options for controlling the location, color, and format of output to windows. Writing to windows is described in detail in Chapter 24, "Writing to Windows."

Step 5: Set the window on the screen with wn_up() 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():

int wn_up(wnp)

WINDOWPTR wnp;        /* Pointer to window            */

wn_up() calls the up function specified in the window structure. By default, the up function is wn_set(). (You can change this function to a function that explodes or rolls the window on the screen. See Chapter 25, "Changing the Appearance of Windows," for more information.)

When the window is set on the screen, the border and the window contents are displayed. In the code example, the window is displayed with a black background on a monochrome display or a blue background on a color display, and a double-line border is used.

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 6: Remove the window from the screen with wn_dn().

To remove the window from the screen, call the window down function, wn_dn().

int wn_dn(wnp)

WINDOWPTR wnp;        /* Pointer to window            */

wn_dn() calls the down function stored in the window structure which, by default, is wn_unset(). (You can change the function that takes a window down. See Chapter 25, "Changing the Appearance of Windows," for more information.)

When a window is taken down, any 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 7: Free the window structure with wn_free().

When you are through with the 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.