Category : Recently Uploaded Files
Archive   : ASILIB12.ZIP
Filename : MULTIWIN.DOC

 
Output of file : MULTIWIN.DOC contained in archive : ASILIB12.ZIP

************************ MULTI-WINDOW SUBSYSTEM ****************************

ASILIB Multi-Window text mode video subroutines
Copyright (C) 1994 Douglas Herr þ All rights reserved

ASILIB's multi-window system allows several pop-up windows to be stored
at any given time, and permits any one window or any group of overlapping
or non-overlapping windows to be displayed on the screen in any position
and in any order. Pop-up windows may be created, printed to, cleared or
moved whether displayed or hidden. Up to 10 pop-up windows may be open at
any time.

IN GENERAL: to use ASILIB's multi-window subroutines, you need to:

1) Initialize the system with MWINIT. This sets up screen buffers and
saves the base screen which the windows will be displayed on top of.
You may re-initialize at any time with MWINIT when you want to change
the base screen.

2) Determine the default status of newly-opened windows. See MWDEFAULT.
If ASILIB's defaults are OK with you, you don't need to change them.

3) Open your windows with MWOPEN. You will need to tell MWOPEN the window
dimensions. For each window, MWOPEN returns a handle you will need to
use when referring to the window.

4) Fill in your window. You can clear, fill with a character, add borders,
titles and other text to the window.

5) Unhide selected or all windows with MWUNHIDE or MWUNHIDEALL. If your
default status includes "not hidden" then you can skip this step.

6) Show them on the screen with MWDISPLAY. You won't see anything if your
program doesn't call MWDISPLAY. MWDISPLAY makes a working copy of the
base screen, adds the windows to it, then pop the whole thing onto your
screen. You can make any changes you want to any open windows, but you
won't see the changes until you call MWDISPLAY.

Other ASILIB subroutines allow you to enable or disable the "shadow" effect
for one or all open windows, hide or unhide one or all windows, and
re-arrange the order in which they appear.

When you are done with a window, you may release the memory buffers it
occupies with MWCLOSE.


°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWBORDER: Puts single- or double-lined border, or character border,
around an open window; sets window's border flag. The
Multi-Window border flag prevents MWClear, MWFill, MWPrint
and MWCenter from over-writing the border for the selected
window.

Parameters: Windowhandle, windowcharacter, colorattribute.

Windowhandle is any valid handle returned by MWOpen which
has not been closed by MWClose or MWCloseAll.

Windowcharacter is an ASCII character to be used to create
the border. Special cases: if windowcharacter = 0, a single-
line border is used. If windowcharacter = -1, a double-lined
border is used.

Colorattribute specifies the color attribute to be used to

print the border. See ColorAtt.

Restrictions: Requires valid window handle; no error code is returned for
invalid handle. Window border will overwrite anything within
one character of the edge of the window.

Example:

REM initialize Multi-window system and open the first window.
REM for this window I want a single-line bright red border
REM with a black background

call sub "mwinit",mwseg
row0 = 5
col0 = 15
row1 = 20
col1 = 45
call sub "mwopen", row0, col0, row1, col1, handle0
call sub "mwborder", handle0, 0, 12


°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWCENTER: centers a string in selected window

Parameters: windowhandle, textstring, windowrow, colorattribute

Windowhandle is a valid handle returned by MWOpen which
has not been closed by MWClose or MWCloseAll.

Textstring is string data that you want centered horizontally
in the pop-up window.

Windowrow is the row in the window where you want the string
to be printed. Window_row is the vertical position in the
window; for example, if windowrow = 1, the string will be
centerd on the first row of the window (note that if the
window has a border, the first row of the window is the first
row inside the border).

Color attribute specifies the color attribute to be used to
print the border. See ColorAtt.

Restrictions:
Requires valid window handle; no error code is returned for
invalid handle.

Example:

REM initialize Multi-window system and open the first window.
REM for this window I want a single-line bright red border
REM with a black background and a heading on the 2nd row
REM inside the border.

call sub "mwinit",mwseg
row0 = 5
col0 = 15
row1 = 20
col1 = 45
call sub "mwopen", row0, col0, row1, col1, handle0
bordercolor = 12
call sub "mwborder", handle0, 0, bordercolor
textcolor = 14
windowheading = "My First Pop-up Window"
call sub "mwcenter", handle0, windowheading, 2, textcolor



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWCLEAR: clears a window managed by the MultiWindow system.

Parameters: windowhandle, colorattribute

Windowhandle is a valid handle returned by MWOpen which
has not been closed by MWClose or MWCloseAll.

Colorattribute specifies the color attribute to be used to
clear the window. If a border has been specified, the border
will not be cleared. See ColorAtt.

Restrictions:
Requires valid window handle; no error code is returned for
invalid handle.

Example:

REM initialize Multi-window system and open the first window.
REM for this window I want a single-line bright red border
REM with a black background and the remainder of the window should
REM be black.

call sub "mwinit",mwseg
row0 = 5
col0 = 15
row1 = 20
col1 = 45
call sub "mwopen", row0, col0, row1, col1, handle0
bordercolor = 12
call sub "mwborder", handle0, 0, bordercolor
clearcolor = 0
call sub "mwclear", handle0, clearcolor




°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWCLOSE: releases a window's memory buffer to DOS

Parameters: windowhandle

Windowhandle is a valid handle returned by MWOpen which
has not previously been closed by MWClose or MWCloseAll.

After calling MWClose with a valid handle, that window is
no longer available, the handle is no longer valid and the
memory buffer used by the window has been returned to DOS.

Restrictions:
Requires valid window handle; no error code is returned for
invalid handle.

Example:

REM I'm done with the window associated with handle0
call sub "MWClose", handle0



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWCLOSEALL: close all open windows, releasing buffers

Parameters: None.

Closes all windows, releasing all memory buffers associated
with the windows. Does not release buffers initialized with
MWInit.

Restrictions:
None; after calling MWCloseAll, all window handles will no
longer be valid.

Example:

REM I'm going to call the ASILIB subroutine "SYSTEM".
REM I don't need the open windows any more, so I want to make as much
REM RAM available as possible.

call sub "MWCloseAll"



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWDEFAULT: change default status of opened windows.

Parameters: statusbits

Statusbits tell MWOpen what defaults to use when opening
a new window; does not affect previously-opened windows.

bit 0 if zero, hide windows
if one, display window
bit 2 if zero, no shadow
if one, shadow enabled

Windows may be either hidden or displayed; if hidden, the
window will not appear on the screen when MWDisplay is
called. Displayed windows will been shown on the screen
when MWDisplay is called.

Each window may have a "shadow" appearing below it and on the
right side to give a "3-D" appearance. Status bit 2 determines
whether each window is opened with or without the shadow.

Restrictions:
Affects default status of windows opend AFTER MWDefault
is called; does not affect status of previously-opened
windows.

Example:

REM I want all opened windows to have a shadow, but not displayed
REM until I call each one individually.
REM To do this I need to set bit 2 and clear bit 0.

statusbits = &bin100
call sub "mwdefault", statusbits



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWDISPLAY: display open windows on the screen

Parameters: None.

MWDisplay updates the screen by displaying all unhidden
open windows. No windows will ever show up on the screen
if you don't call MWDisplay.

Restrictions:
You must call MWInit before using MWDisplay. If MWDisplay
is called before initializing the Multi-window system,
MWDisplay will take no action and return to the calling program.
Text mode only.

Example:

REM I have initialized the Multi-window system and created some windows.
REM Now I want to display the windows on the screen.

call sub "mwdisplay"



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWFILL: Fills a window managed by the MultiWindow system.

Parameters: Window handle, color attribute, fill character

Windowhandle is a valid handle returned by MWOpen which
has not been closed by MWClose or MWCloseAll.

Colorattribute specifies the color attribute to be used to
fill the window. If a border has been specified, the border
will not be overwritten. See ColorAtt.

Fill character is the ASCII code for the character you want
to fill the window with.

Restrictions: Requires valid window handle; no error code is returned for
invalid handle.

Example:

REM initialize Multi-window system and open the first window.
REM for this window I want a single-line bright red border
REM with a black background and the remainder of the window should
REM filled with red "?".

call sub "mwinit",mwseg
row0 = 5
col0 = 15
row1 = 20
col1 = 45
call sub "mwopen", row0, col0, row1, col1, handle0
bordercolor = 12
call sub "mwborder", handle0, 0, bordercolor
fillcolor = 4
fillchar = ASC("?")
call sub "mwfill", handle0, fillcolor, fillchar






°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWHIDE: hide selected window

Parameters: Window handle

Windowhandle is a valid handle returned by MWOpen which
has not been closed by MWClose or MWCloseAll.

After calling MWHide with a valid handle, that window is
ignored by MWDisplay. The window may be unhidden with
MWUnHide.


Restrictions: Requires valid window handle; no error code is returned for
invalid handle.

Example:

REM initialize Multi-window system and open the first window.
REM for this window I want a single-line bright red border
REM with a black background and the remainder of the window should
REM filled with red "?". I'll keep this window hidden for now.

call sub "mwinit",mwseg
row0 = 5
col0 = 15
row1 = 20
col1 = 45
call sub "mwopen", row0, col0, row1, col1, handle0
bordercolor = 12
call sub "mwborder", handle0, 0, bordercolor
fillcolor = 4
fillchar = ASC("?")
call sub "mwfill", handle0, fillcolor, fillchar
call sub "mwhide", handle0



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWHIDEALL: hide all open windows

Parameters: None.

Example:

call sub "mwinit", mwseg

REM program opens several windows
.
.
.

REM make all open windows disappear
call mwhideall
call sub "mwdisplay"



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWINIT: initializes multi-window system. Several pop-up windows may
be popped onto or removed from a base screen in any order.
You must re-initialize the multi-window system each time the
base screen changes. MWInit does not affect any open windows.

Parameters: Mwseg

MWINIT allocates screen buffers and save a copy of the current
screen as its "base screen". When the pop-up windows are
displayed, they are displayed on top of the base screen. You
may change the base screen at any time whether pop-up windows
are open or not by calling MWINIT again. MWINIT returns the
segment address of the screen buffers as mwseg. When you are
done with pop-up windows, you may release the screen buffer
with ASILIB's FREEDOS subroutine. If mwseg = 0, then
insufficient DOS memory is available.

Restrictions: Text mode only; all screen dimensions supported by ASILIB
are OK.

Example:

REM initialize multi-window system
call sub "mwinit", mwseg


°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWNOBORDER: clears the border flag for the associated window

Parameters: Windowhandle.

Pop-up windows managed by ASILIB's multi-window display system
may have borders which are protected from window clearing and
writing operations; this subroutine clears the "border flag"
for the specified window so that the border may be cleared or
overwritten. See also MWOPEN and MWBORDER.

Restrictions: Requires valid window handle; no error code returned for
invalid handle.

Example:

REM initialize Multi-window system and open the first window.
REM for this window I want a single-line bright red border
REM with a black background

call sub "mwinit",mwseg
row0 = 5
col0 = 15
row1 = 20
col1 = 45
call sub "mwopen", row0, col0, row1, col1, handle0
call sub "mwborder", handle0, 0, 12

.
.
.
REM some time later I want to clear the entire window,
REM including the border

call sub "mwnoborder", handle0
colorattribute = &hex0107
call sub "mwclear", handle0, colorattribute


°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWNOSHADOW: Disables "shadow" effect for selected window.

Parameters: Window handle

Pop-up windows managed by ASILIB's multiwindow system may
be opened with a "shadow" enabled. MWNOSHADOW disables the
"shadow" effect for the selected window. See also MWOPEN,
MWSHADOW and MWDEFAULT.

Restrictions: Requires valid window handle; no error code returned for
invalid handle.

Example:

.
.
REM Initialize Multi-window system open a window and disable the "shadow"
REM effect for this window.

call sub "mwinit", mwseg
row0 = 5
col0 = 15
row1 = 20
col1 = 45
call sub "mwopen", row0, col0, row1, col1, handle0
call sub "mwnoshadow", handle0



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWOPEN: Opens a pop-up window.

Parameters: row0, col0, row1, col1, handle

(row0, col0) are the screen coordinates of the upper-left
corner of the requested window; (row1, col1) are the lower-
right screen coordinates of the window. Handle is returned
by MWOPEN so that you may refer to this window when using
other Multi-window subroutines. If Handle is returned = 0,
the window could not be opened.

Up to 10 windows may be open at any time; if you need more,
you will need to change MWINDOW_COUNT in multiwin.asm and
re-assemble. If two or more windows overlap on the screen,
the one opened last will be displayed on top of the other(s).
The window appearing on top may be changed with MWTOP.

Note the default status of all opened windows:
hidden
no shadow
no border

You may change the status of any open window with MWUNHIDE,
MWHIDE, MWSHADOW, MWNOSHADOW, MWBORDER AND MWNOBORDER;

All open windows may be hidden or un-hidden with
MWHIDEALL OR MWUNHIDEALL;

The default status of newly-opened windows may be changed
with MWDEFAULT.

Restrictions: MWOPEN assumes that the window is smaller than the screen
dimensions and that (row0, col0) and (row1, col1) are within
the screen boundaries. Minimum values for row0 and col0 are
1; on a 25-row, 80-column screen maxumum row1 = 25, maximum
col1 = 80. Text mode only.

Example:

call sub "mwinit", mwseg
row0 = 5
col0 = 15
row1 = 20
col1 = 45
call sub "mwopen", row0, col0, row1, col1, handle0


°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWPRINT: print an ASCIIZ string in an open window

Parameters: handle, st$, wrow, wcolumn, colorattribute

Handle is a window handle returned my MWOPEN; st$ is the
text you want printed; (wrow, wcol) are the coordinates
within the window where you want the string printed, and
colorattribute is an ordinary text-mode color attribute.
Note that the coordinates are relative to the WINDOW, not
relative to the SCREEN. Note also that if a border is
enabled, the coordinates are relative to the window area
within the border. The upper left corner of any window
is located at (1, 1).

Restrictions: Text mode only; handle must be a valid handle returned by
MWOPEN; if the string is too long to fit within the window
it will be truncated.

Example:

REM I want to print some text on the 2nd row of a window, flush with
REM the left side. I'll use bright red on black.


wrow=2
wcolumn=1
wcolor=12
wstring$="Print this in the window"
call sub "mwprint", handle, wstring$, wrow, wcolumn, wcolor



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWPRINTCE: Prints a string in selected window & clears to right edge
of window; clears to border if the window's border is enabled.

Parameters: Same as MWPRINT.

Example: See MWPRINT.



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWSELECT: Determines which window is visible at screen coordinate.

Parameters: screen row, screen column, handle

Given screen row and screen column, MWSELECT returns the
handle of the window visible at these coordinates. If no
window is visivle at these coordinates, handle is returned = 0.

Example:

REM I want to determine the handle of the window visible at (5,15)

wrow=5
wcolumn=15
call sub "mwselect", wrow, wcolumn, handle
if handle=0 then
REM no window at these coordinates.
else
.
.
.




°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWSHADOW: Enables "shadow" effect for selected window.

Parameters: window handle

A "shadow" effect can be turned on by calling this subroutine
with a valid window handle. This enables the "shadow" for
only the selected window - no other windows are affected.
See also MWOPEN, MWDEFAULT and MWNOSHADOW.

Example:

REM I want a "shadow" effect visible for the window associated with
REM handle3.

call sub "mwshadow", handle3


°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWTITLE: Center a string at the top of an open window.

Parameters: window handle, title$, colorattribute

Given a window handle and string to print, MWTITLE prints
the string centered at the top of an open window,
overwriting part of the border if nessesary. This is
unlike all other MWxxx subroutines which leave the border
intact. The title is printed using the color colorattribute.

Example:

REM print a title at the top of window "window3"

colorattribute=12
title$="How I spent my Summer Vacation"
call sub "mwtitle", window3, title$, colorattribute

REM now show my window title on the screen
call sub "mwdisplay"



°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWTOP: displays selected window on top of all others

Parameters: windowhandle

Windowhandle is the handle returned by MWOPEN when the window
is created. After calling MWTOP, the window associated with
windowhandle will be displayed "on top" of all others the
next time MWDISPLAY is called.

Restrictions: Text mode only; windowhandle must be a valid window handle.

Example:

REM open a mWindow, jumping to windowerror: if there's a problem.
REM later in the program I want to dislplay this window on top
REM of all others
call sub "mwopen", row0, col0, row1, col1, handle
if handle = 0 then windowerror:

.
.
.
call sub "mwtop", handle


°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWUNHIDE: Allow selected window to be displayed

Parameters: window handle

By default, all windows are opened with "hidden" status.
MWUNHIDE allows MWDISPLAY to show the window on the screen.
MWUNHIDE affects only the window associated with 1 handle.
To change the default status of all newly-opened windows to
"not hidden", use MWDEFAULT.

Example:

REM I want to show window7 on the screen

call sub "mwunhide", window7
call sub "mwdisplay"


°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°°

MWUNHIDEALL: unhide all open windows

Parameters: None.

Example:

call sub "mwinit", mwseg

REM program opens several windows
.
.
.

REM make all open windows visible
call sub "mwunhideall"
call sub "mwdisplay"