Using Low Level Functions for Creating a Memory Screen

The define virtual window function wn_vdef() is very convenient, since it defines both the window and the memory screen at the same time. There may be instances, however, where you would want to create a memory screen independently of the window and then associate the memory screen to the window.

You can do this using the low-level Vermont Views functions defined below.

To create a window with no buffer, use the window definition with no buffer function, wn_nbdef()

WINDOWPTR wn_nbdef(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

*/

The call to wn_nbdef() is identical to that of wn_def(). The only difference is that no memory screen is assigned to the window. For more information on the argument list for wn_nbdef(), refer to the description of the wn_def() function in Chapter 23, "About Windows."

A memory screen can be created independently of a window using the memory screen definition function, ms_def():

SCRPTR ms_def(rowq, colq, att)

int rowq;

/* Number rows in memory 

*/

int colq;

/* Number columns in memory

*/

UCHAR att;

/* Attribute: Clear memory screen

*/

This function creates a memory screen of the specified rows and columns and fills it with spaces using the att attribute specified in the call.

Note: It is recommended that you use the same attribute as the window, or you will get a patchwork effect when writing to the memory screen with the window attribute.

Since a memory screen holds information about characters and attributes for each character, the amount of memory required to allocate a memory screen from the heap is the number of rows in the memory screen times the number of columns in the memory screen times two.

To assign the memory screen to the window, call the set window buffer function, sw_msbuf():

void sw_msbuf(msp, wnp)

SCRPTR msp;

/* Memory screen to use as buffer

*/

WINDOWPTR wnp;

/* Pointer to window to make virtual

*/

This function assigns the memory screen as the window's buffer by assigning the pointer to the memory screen as one of the window structure members.

In the code example above, we could have used these functions instead of the wn_vdef() function. The code would be as follows

WINDOWPTR wnp;

SCRPTR msp;



wnp = wn_nbdef(5, 5, 10, 20, (UCHAR)LNORMAL, BDR_DLNP);

msp = ms_def(20, 20, LNORMAL);

sw_msbuf(msp, wnp);

If you create the memory screen directly by calling ms_def(), you must free the memory screen when you have finished using it. The function to free a memory screen is ms_free():

void ms_free(msp)

SCRPTR msp;        /* Pointer to memory screen            */

You can also create a memory screen and associate it with a window by calling wn_msmod(), as discussed in Chapter 25, "Changing the Appearance of Windows." However, if you create the memory screen using wn_msmod(), the memory screen is sized to fit the interior work area of the window exactly. If you create the memory screen by calling ms_def(), you can specify the dimensions of the memory screen and make it any size that you desire.

If you create a memory screen using wn_msmod(), you do not need to free the screen by calling ms_free(). Vermont Views handles freeing the memory screen in this instance.

Note: Be very careful when using the low level functions in your code. All windows must have a buffer before you can write to them. It is the responsibility of the programmer to ensure that the memory screen is allocated and assigned to the window.