Category : Alternate Operating Systems - Quarterdeck DesqView, CP/M, etc
Archive   : DVGLUE17.ZIP
Filename : DVGLUE.DOC

 
Output of file : DVGLUE.DOC contained in archive : DVGLUE17.ZIP
!!THIS IS A EARLY BETA VERSION AND MAY NOT BE REDISTRIBUTED!!
version 1.7 (1/3/93)

IF YOU SEE THIS VERSION OF DV-GLUE ANYWHERE EXCEPT THE TWO LOCATIONS
LISTED BELOW, PLEASE ASK THE SYSTEM OPERATOR OR ARCHIVE MAINTAINER
TO REMOVE IT. Beta versions should only be available from
Fidonet: Soundingboard BBS, 1:129/26 1-412-621-4604
Internet: CS.CMU.EDU [128.2.222.173] in /afs/cs/user/ralf/pub
(change directories with a single command)

THIS BETA VERSION IS NOT SUPPORTED. BUG REPORTS WILL BE (MORE OR LESS)
CHEERFULLY ACCEPTED, BUT REQUESTS FOR ASSISTANCE WILL BE ROUTED TO THE
BIT BUCKET. (due to time limitations, it has not yet been tested under
DV/X, and the large-model library may still have some problems not
present in the small-model library; I also haven't had time to
completely update the documentation)

Note: the UI*() functions may require one of Borland's C compilers to
use, as they are still written in C (they will be redone in assembler
prior to the final release). The remainder of the library should work
equally well under MS C.



DV-GLUE v1.70á
-------------
(c) Copyright 1988, 1993 Ralf Brown
All Rights Reserved.



DV-GLUE is a collection of some 290 functions which give your programs
access to the power of the DESQview[*] and DESQview/X (as well as
TopView[**]) environments. DV-GLUE also includes functions to access
other Quarterdeck programs such as QEMM-386 and VIDRAM.

See file @COPYRIT.NOT for full copying permissions/restrictions. It
basically says that you can use these functions as long as you don't
try to claim them as your own and give proper credit.









---
[*] DESQview and DESQview/X are trademarks of Quarterdeck Office Systems
[**] TopView is a trademark of International Business Machines, Inc.

-----------------------------------------------------------------------------
To use this library in your own programs, add the line
#include "dvglue.h"
to the start of each source file using functions from the library. If you
are using constants for building your own streams, also add the line
#include "dvstream.h"
to the start of the module. If you are using any of the UI... functions,
add the line
#include "dvgui.h"
Then add DVGLUEx.LIB to the list of files to compile (if you are using
TCC), or add DVGLUEx.LIB to the .PRJ file, where 'x' is the letter
corresponding to the memory model you are using.

If you have been using version 1.01 or earlier, see @HIST for details
of the massive function renamings which have taken place, as well as
several functions with changed parameters.
-----------------------------------------------------------------------------
A number of the functions at the core of this package were originally written
by John Navas and have since been modified pretty much beyond recognition. The
original versions of these can be found in the file TVGLUETC.ARC on the Dog
Lab BBS (415) 594-9806.





Ralf Brown
December 30, 1992

Direct e-mail to:
[email protected] (Internet) \
ralf%cs.cmu.edu@carnegie (BITnet) > preferred
...!{harvard,ucbvax}!cs.cmu.edu!ralf (UUCP) /
Ralf Brown 1:129/26.1 (FIDOnet)
or post a message addressed to me on the DESQVIEW or DR_DEBUG echomail
areas on FIDOnet
-----------------------------------------------------------------------------

Setup
-----

Before you can call any of the functions in this library, you must
first initialize the library by calling DVinit() or DVXinit(). At the
end of the program, before exiting, you should call DVexit() or
DVXexit(). DV-GLUE attempts to have DVexit()/DVXexit() called
automatically, but you should call the appropriate one explicitly to
make sure it is in fact invoked. All of the 'init' and 'exit'
functions described in this section may safely be called multiple
times; calls after the first are ignored except for returning the
appropriate value.

int DVinit(int min_version)
initialize DESQview interface and return DESQview version as a hex
number: 0x0201 == version 2.01, 0x214 == version 2.20. If the
program uses functions requiring a newer version of DESQview
than is in use, DVinit() prints an error message and terminates
the program. The automatically-determined version may be
overridden by passing a non-zero value for 'min_version' (which
is then used as the minimum permitted DESQview version).

void DVexit(void)
clean up the DESQview interface before terminating program.

int DVXinit(int min_version)
initialize the DESQview/X interface and return the DESQview/X
version as a hex number: i.e. 0x0102 == version 1.02. If the
program uses functions requiring a newer version of DESQview/X
than is in use, DVXinit() prints an error message and terminates
the program. The automatically-determined version may be
overridden by passing a non-zero value for 'min_version' (which
is then used as the minimum permitted DESQview/X version).

void DVXexit(void)
clean up the DESQview/X interface before terminating program.

Some of the functions in DV-GLUE require additional initialization
functions, which should be called as appropriate.

void XDIinit(void)
Prepare for the use of the XDI...() functions. Returns the
multiplex number being used by DESQview's External Device
Interface or 0 if it is not available (i.e. DV < 2.26).

void XDIexit(void)
Cleanup the XDI interface prior to program termination.
Although DV-GLUE attempts to have this function called
automatically at program termination, you should call it
explicitly to ensure that the XDI interface is in fact shut
down properly.

int QEMMinit(void)
Prepare for the use of the QEMM...() functions. Returns the
QEMM version as a hex number (i.e. 0x0603 == version 6.03) or 0
if QEMM is not installed. Use of this function is optional
unless you need to know the QEMM version number, as the other
QEMM...() functions call it as needed.

int QOSinit(void)
Prepare for the use of the QOS...(), MANIFEST...(), and
VIDRAM...() functions. Returns 0 if no Quarterdeck programs
are installed on the multiplex interrupt (INT 2Fh), or the
multiplex number (default DEh) being used if one or more
programs are installed.

Pre-Processor #defines
----------------------

The following two predefined symbols are useful to determine whether the
correct version of DV-GLUE is being used.

DVGLUE_version is the version number times 100
DVGLUE_versionSTR is a string in the form "n.nn"

Global Variables
----------------

int _dvversion
The DESQview version as a hex number (i.e. 2.22 yields
_dvversion == 0x0216).

char _dvmajor
char _dvminor
These two variables contain the version of DESQview broken down
into major and minor components (i.e. 2.22 yields _dvmajor == 2
and _dvminor == 22).


Low-Level Primitives
--------------------

Most of the functions described in later sections call on internal
equivalents of one or more of the functions in this section.

OBJECT DVwin_stream(OBJECT window,BYTE *stream)
send the specified stream to the window. The return value is
normally NIL, as only window streams containing opcode E6h
(create new window) return a value. If the stream contains
opcode E6h, the return value will be the handle of the new
window if successful or NIL on failure.

void DVsendmsg(int message,int modifier,OBJECT object,PARMLIST *params)
send a message with the parameters specified in "params", returning
any result values in "params". The PARMLIST type is a struc with
two fields:
int num_args ; /* number of parameters sent/returned */
DWORD arg[9] ; /* up to nine args may be sent or returned */

void DVsendmsg0(int message,int modifier,OBJECT object)
send a parameterless, non-value-returning message to the specified
object.

DWORD DVsendmsg1(int message,int modifier,OBJECT object)
send a parameterless message which returns a single value to the
specified object.

Windows
-------

One of the strongest features of the DESQview API is its windowing
capabilities. DV-GLUE gives you the capability to create, move, resize,
color, title, and close windows, among other things.

Each window has a logical cursor which need not be in the same place as the
hardware cursor--after all, the hardware cursor could be in some other
program's window. There are calls to manipulate the logical cursor and move
the hardware cursor to the position corresponding to the logical cursor.

OBJECT DVwin_new(OBJECT window,int rows,int cols)
create a new window which is a child of the given window and is
"rows" high and "cols" wide. Returns the handle of the new window.

void DVwin_free(OBJECT window)
close the specified window.

void DVwin_attach(OBJECT window)
attach the specified window to its parent window, such that when one
window is moved, the other also moves.

void DVwin_detach(OBJECT window)
detach the specified window from its parent window, such that each
window moves independently of the other.

void DVwin_clear(OBJECT window)
Erase the entire window. Does not affect the logical cursor's
position.

void DVwin_fill(OBJECT window,char c)
Fill the entire window with the specified character.

void DVwin_attr(OBJECT window,int attr)
Set the default output attribute for the given window.

void DVwin_cursor(OBJECT window,int row,int col)
Move the window's logical cursor to the specified position.

void DVwin_hcur(OBJECT window)
Move the hardware cursor to where the window's logical cursor is.

void DVwin_repchar(OBJECT window,char c,int count)
Write the character "c" to the given window "count" times.

void DVwin_repattr(OBJECT window,int attr,int count)
Change the attribute of the next "count" characters of the given
window to "attr."

void DVwin_blanks(OBJECT window,int count)
Write the specified number of blanks to the given window.

void DVwin_lsize(OBJECT window,int rows,int cols)
Change the logical size (not the displayed size) of the given window
to be "rows" high by "cols" wide.

void DVwin_origin(OBJECT window,int row,int col)
Move the upper left corner of the visible portion of the window to
be at (row,col).

void DVwin_resize(OBJECT window,int rows,int cols)
Change the size of the given window on the screen to be "rows" high by
"cols" wide. You need to call DVwin_redraw() to ensure that the
window's size is updated on the screen.

void DVwin_move(OBJECT window,int row,int col)
Move the given window such that its upper left corner is at
(row,col). You need to call DVwin_redraw() to ensure that the
window's position is updated on the screen.

void DVposwin(OBJECT window,OBJECT parent,int pos,int row_offset,int col_offset)
Move the given window to a position relative to the parent window.
The values for "pos" specify both the horizontal and vertical
position: one of
PW_HCURR current horizontal position
PW_HCENTER centered horizontally in parent window
PW_LEFT at left edge of parent
PW_RIGHT at right edge of parent
ORed with one of
PW_VCURR current vertical position
PW_VCENTER centered vertically in parent window
PW_TOP at top edge of parent
PW_BOTTOM at bottom edge of parent
optionally ORed with
PW_NOREDRAW don't refresh the screen
"row_offset" and "col_offset" are then added to the position selected
by "pos". These values are signed, so negative values move the window
up and left.

For this function, NIL specifies the current task's main window if
given for "window", but specifies the full screen if given for
"parent".

void DVwin_minsize(OBJECT window,int rows,int columns)
Keep the user from reducing the window's size below the specified size

void DVwin_maxsize(OBJECT window,int rows,int columns)
Keep the user from increasing the window's size beyond the specified
size.

void DVwin_title(OBJECT window,char *title)
Set the window's title to the given string.

void DVwin_bottom(OBJECT window)
move the window behind all other windows belonging to the current
task.

void DVwin_top(OBJECT window)
move the window in front of all other windows belonging to the current
task.

void DVwin_topsys(OBJECT window)
move the window in front of all other windows in the system.

void DVwin_reorder(OBJECT win,unsigned first,unsigned second,...)
Put the specified window in front, with "first", "second", etc.
being put behind it. "first", "second", etc. are the OBJSEG of
the object handle for the respective windows.

void DVwin_redraw(OBJECT window)
Update the physical screen to accurately reflect the window.

void DVredrawwin(OBJECT window)
Same as DVwin_redraw(), but uses different method to tell DESQview to
update the screen image of the window. This method does not make the
given window active.

void DVwin_scroll(OBJECT window,int top,int left,int height,int width,int dir)
Scroll the specified region of the window's virtual screen in the
given direction. The valid directions are
SCRL_LEFT
SCRL_RIGHT
SCRL_UP
SCRL_DOWN

int DVprintf(OBJECT window,char *format, ...)
Just like printf(), but writes to the specified window, or the
task's main window if 'window' is NIL. DVprintf() supports all
format specifications supported by the Borland C++ 3.0 printf()
except floating-point formats (%e %f %g %E and %G).

void DVwin_swrite(OBJECT window,char *string)
Write the string to the given window. Note that \n is not converted
to \r\n.

void DVwin_write(OBJECT window,char *string,int len)
Write the first "len" characters of the string to the given window.

void DVwin_writeca(OBJECT window,char *chars,char *attr,int len)
Write the first "len" characters and attributes to the given window
starting at the current position of the logical cursor.

void DVwin_writea(OBJECT window,char *attr,int len)
Change the attributes of the first "len" characters from the current
cursor position to be those specified by "attr".

void DVwin_repattr(OBJECT window,int attr,int count)
change the attributes of the next "count" characters on the virtual
screen to "attr"

void DVwin_repchar(OBJECT window,int character,int count)
write "count" copies of the character to the virtual screen for the
given window.

int DVwin_read(OBJECT window,void *buffer,int maxsize)
Read the remainder of the current line in the given window, and copy
up to "maxsize" characters into the buffer.

int DVwin_nread(OBJECT window,void *buffer,int n)
Read the next "n" characters or attributes from the given window and
place them in the buffer.

void DVwin_gotoxy(OBJECT window,int x,int y)
Position windows cursor at row y and column x.

void DVwin_cursor(OBJECT window,int row,int col)
Position window's logical cursor at the given row and column.

void DVwin_color(OBJECT window,int logical_attr,int physical_attr)
Select the physical attribute for the given logical attribute.

void DVwin_frattr(OBJECT window,int attr)
set the attribute of the given window's frame.

--------------------------
There are a number of switches available:

void DVwin_atread(OBJECT window,int read_attr)
If "read_attr" is nonzero, DVwin_nread() gets attributes, if
"read_attr" is zero, DVwin_nread() gets characters.

void DVwin_ctrl(OBJECT window,int ctrl)
If "ctrl" is nonzero, output to the given window will interpret
CR, LF, BS, etc. If "ctrl" is zero, those characters will be
displayed.

void DVwin_logattr(OBJECT window,int logattr)
If "logattr" is nonzero, DESQview will translate the attributes used
for the window, i.e. the attributes become logical. If "logattr" is
zero, then the attributes written to a window are those displayed on
the screen, i.e. physical attributes.

void DVwin_leave(OBJECT window,int leave)
If "leave" is nonzero, then writing to a window will not change the
attributes in the positions which are overwritten. If "leave" is
zero, then characters output to the window will be given the currently
active default attribute.

void DVwin_frame(OBJECT window,int frame)
If "frame" is nonzero, then the window's frame will be displayed.
If "frame" is zero, the window will not have a frame.

void DVwin_hide(OBJECT window)
make the given window invisible

void DVwin_unhide(OBJECT window)
make the given window visible


Query Functions
---------------

In addition to setting window characteristics, you can find out the status of
most anything that you can set.

int DVqry_attr(OBJECT window)
Returns the current default character attribute for the window.

void DVqry_cursor(OBJECT window,int *row,int *column)
Returns the position of the window's logical cursor in "row" and
"column".

void DVqry_position(OBJECT window,int *row,int *column)
Returns the position of the given window in "row" and "column"

void DVqry_origin(OBJECT window,int *row,int *column)
Returns the origin of the visible portion of the window in "row" and
"column".

void DVqry_lsize(OBJECT window,int *rows,int *columns)
Returns the logical size of the window in "rows" and "columns"

void DVqry_size(OBJECT window,int *rows,int *columns)
Returns the displayed size of the window in "rows" and "columns"

void DVqry_title(OBJECT window,char *title,int size)
Returns the first "size" characters of the window's title in "title"

int DVqry_color(OBJECT win,int logical_attr)
Returns the physical attribute which the given logical attribute is
mapped to.

int DVqry_frattr(OBJECT window)
Returns the attribute of the window's frame.

int DVwin_width(OBJECT window)
Return the width of the virtual screen for the given window.

The switches which may be set can also be read:

int DVqry_atread(OBJECT window)
returns TRUE if DVwin_nread() gets attributes, FALSE if it gets
characters.

int DVqry_ctrl(OBJECT window)
returns TRUE if control characters are interpreted, FALSE if not

int DVqry_logattr(OBJECT window)
returns TRUE if logical attributes are being used, FALSE if physical
attributes are used.

int DVqry_leave(OBJECT window)
returns TRUE if writing to the window will leave the character
attributes unchanged, and FALSE if the attributes are changed to the
current default attribute.

int DVqry_frame(OBJECT window)
returns TRUE if the window has a frame, FALSE otherwise.

int DVqry_hidden(OBJECT window)
returns TRUE if the window is hidden, FALSE if it is visible.

Keyboard Objects
----------------

Keyboard objects let you direct keyboard input to a specified window, to send
data that another process thinks came from the keyboard, and other things.

OBJECT DVkbd_new(void)
create a new keyboard object and return its handle.

void DVkbd_free(OBJECT kbd)
destroy keyboard object. Do not attempt to free the default keyboard!

void DVkbd_open(OBJECT kbd, OBJECT window)
connect "kbd" to the indicated window

void DVkbd_close(OBJECT kbd)
disconnect the keyboard from its window

int DVkbd_messages(OBJECT kbd)
determine how many messages are pending for the keyboard

void DVkbd_clear(OBJECT kbd)
remove all pending messages from the keyboard

OBJECT DVmykbd(void)
return the handle of the current task's default keyboard. For the
functions described in this section, the special handle NIL represents
the default keyboard.

OBJECT DVkbdof(OBJECT task)
return the handle for the given task's default keyboard.

int DVkbd_read(OBJECT kbd,char *buffer,int maxsize)
wait for a keyboard message on "kbd", and then fill "buffer" with up
to (maxsize-1) characters from the message. Returns the actual size
of the message read.

If the keyboard is in field mode, then the user can edit the input
fields at will, and the return contains the contents of all input
fields in the following format:

BYTE field number
WORD length of field data
N BYTES contents of field

This repeats until the field number is zero, which signals the end of
the data.

int DVkbd_status(OBJECT kbd)
return status of last message read from "kbd". If the keyboard is in
field mode, the status will indicate how the entry was terminated.
1 = pressed RETURN
27 = pressed ESC

void DVkbd_write(OBJECT kbd,char *data,int size,int status)
write a message of the given size to "kbd", using the given status,
which may then be checked by the reader with DVkbd_status().

void DVkbd_setflags(OBJECT kbd,int flags)
set the keyboard behavior flags for "kbd" that correspond to the set
bits of "flags"

Valid flags (OR together):
KBD_FIELDMODE put keyboard into field mode
KBD_ACTIVE keyboard is active in "kbd"s window
KBD_INSERT keyboard is in "insert" mode
KBD_CONCURRENT program continues running during input
KBD_FILTERALL filter all keystrokes through DVkbd_setesc
handler

void DVkbd_clrflags(OBJECT kbd,int flags)
clear the keyboard behavior flags for "kbd" that correspond to the set
bits of "flags". The valid flags are the same as for DVkbd_setflags.

void DVkbd_setesc(OBJECT kbd,void far (*func)(void))
set a keyboard filtering function. Not yet tested.

Timers
------

The timer management functions allow you to create, destroy, set, and read
timer objects which can provide for delays.

OBJECT DVtimer_new(void)
create a new timer object and return its handle

OBJECT DVtimer_free(void)
destroy a timer object and return its memory to the common pool

void DVtimer_begin(OBJECT timer,DWORD length)
start a timer counting down from "length". The timer will run for
10 * length milliseconds (though the timer's resolution is actually
only 55 milliseconds).

void DVtimer_set(OBJECT timer,int hour,int minute,int second,int hundredths)
Start a timer counting down such that it finishes at the indicated
time.

DWORD DVtimer_len(OBJECT timer)
return the amount of time left on the timer.

DWORD DVtimer_elapsed(OBJECT timer)
return the amount of time elapsed since the timer was started.

void DVtimer_start(OBJECT timer)
start the timer counting down

void DVtimer_stop(OBJECT timer)
stop the timer from counting down

void DVtimer_close(OBJECT timer)
close the timer object. Also stops the countdown.

DWORD DVtimer_wait(OBJECT timer)
wait until the timer completes its countdown, and return the time in
1/100ths seconds since midnight at the time the counter finished.

int DVtimer_status(OBJECT timer)
find out whether the timer is running or not.

Pointers
--------

OBJECT DVptr_new(void)
creates a new pointer object and returns its handle

void DVptr_free(OBJECT pointer)
destroy the given pointer object

void DVptr_open(OBJECT pointer, OBJECT window)
connect the mouse pointer to the given window, where NIL means the
current task's default window

void DVptr_close(OBJECT pointer)
disconnect the mouse pointer from its window

void DVptr_icon(OBJECT pointer,char symbol)
set the character used to represent the mouse pointer.

void DVptr_goto(OBJECT ptr,int row,int col)
move the mouse pointer to the given position relative to the window's
upper left corner

void DVptr_setflags(OBJECT pointer,WORD flags)
set pointer behavior flags. The valid flags (OR together) are:
PTR_BUTTON only report on button activity (requires a
previous call to DVenable())
PTR_RELEASE report on button release as well as press
PTR_ABSOLUTE pointer coordinate relative to phys screen
PTR_SLOWCLICK button held 1/2 sec before it "click"s. Used
to allow chords to be pressed.
PTR_NOTFORE report even is window is not in foreground
PTR_NOTTOP report even if window in not topmost
PTR_HIDDEN mouse pointer is invisible inside window

void DVptr_clrflags(OBJECT pointer,WORD flags)
clear pointer behavior flags. What the flags are is not yet known.

void DVptr_erase(OBJECT pointer)
discard all unread pointer messages

int DVptr_messages(OBJECT pointer)
return the number of unread pointer messages

int DVptr_read(OBJECT window,POINTER_MSG *msg)
wait for the next pointer message, and put it in "msg"
Returns 0 on success, -1 on error.

The format of the POINTER_MSG is:
int row ;
int column ;
BYTE button_state
Valid bits in button_state are:
BUTTON_PRESS \ only available if pointer flag PTR_RELEASE
BUTTON_RELEASE / is set
BUTTON_LEFT
BUTTON_RIGHT

int DVptr_status(OBJECT pointer)
return the pointer's status. This value is the same as the
button_state field of POINTER_MSG (see above).

void DVptr_goto(OBJECT ptr,int row,int col)
move the mouse pointer to the given position relative to the window's
upper left corner

void DVptr_setscale(OBJECT pointer,int rows,int cols)
Set the scaling of the pointer's coordinates such that the window it
has been connected to with DVptr_open() is considered to be "rows"
high and "cols" wide.

void DVptr_getscale(OBJECT pointer,int *rows,int *cols)
returns the scaling factors previously set with DVptr_setscale().

void DVwin_point(OBJECT window,OBJECT pointer)
move the mouse pointer to the location of the given window's logical
cursor.

Keyboard Mouse
--------------

For those systems without a mouse attached, DESQview provides a "keyboard
mouse" which emulates a mouse using the numeric keypad. There are two
functions relating to the keyboard mouse:

int DVqry_kmouse(void)
returns TRUE if DESQview is using a keyboard mouse, FALSE if not

void DVapi_kmouse(int active)
if "active" is TRUE, turn on the keyboard mouse, if it is FALSE
turn off the keyboard mouse.

Panel Files
-----------

OBJECT DVpanel_new(void)
create a new panel object and return its handle

void DVpanel_free(OBJECT panel)
destroy the panel object

void DVpanel_open(OBJECT panel,char *filename)
associate the panel object with a disk file

void DVpanel_data(OBJECT panel,BYTE *data,int length)
associate inline panels with the panel object

void DVpanel_close(OBJECT panel)
close the panel file on disk

DWORD DVpanel_status(OBJECT panel)
check success of last DVpanel_open, DVpanel_data, or DVpanel_apply.
Return values:
00h success
14h ?
15h ?
16h invalid panel format
17h panel file already open
95h ?
98h null panel file name

int DVpanel_size(OBJECT panel)
return the number of panels in the panel file

char far * DVpanel_dir(OBJECT panel, int *num_entries)
get the directory of panels in the panel file. I have no idea
what the format of the directory entries is.

void DVpanel_apply(OBJECT panel,char *name,OBJECT window,OBJECT *retwin,
OBJECT *retkbd)
write the named panel from the panel file to the given window. If
"window" is NIL, then use the current task's default window.

"retwin" indicates which window was actually used, and "retkbd"
returns the keyboard that may have been created by the panel (NIL if
no keyboard was created)

Object Queues
-------------

Object queues let you wait for any one of multiple occurrences without
creating a separate task for each, and without polling for them.

void DVobq_add(OBJECT objectq, OBJECT item)
add the specified object to the given objectq. Using NIL for the
objectq will use the current task's objectq.

void DVobq_remove(OBJECT objectq, OBJECT item)
remove the specified object from the queue.

void DVobq_clear(OBJECT objectq)
remove ALL objects from the queue.

int DVobq_size(OBJECT objectq)
return the number of items in the specified queue.

DWORD DVobq_status(OBJECT objectq)
find out whether or not the object queue is open

void DVobq_open(OBJECT objectq)
open the given objectq. NIL means the current task's objectq.

void DVobq_close(OBJECT objectq)
close the given objectq. NIL means the current task's objectq.

OBJECT DVmyobq(void)
return the handle of the current task's objectq.

OBJECT DVobqof(OBJECT task)
return the handle of the given task's objectq.

OBJECT DVobq_read(OBJECT objectq)
wait for any object on the queue to have input, and return the handle
of the object which has input. For the queue to properly use all
objects in it, it must be closed (but not cleared, of course).

Multiple Threads of Execution
-----------------------------

The task management functions allow you to create and destroy threads, and
start, stop, and interrupt other threads.

OBJECT DVtask_new(OBJECT parent,char *title,int row,int col,int rows,int cols,
char far *stack,int stacksize,void far (*startaddr)(int),
int switch_menu)
create a new thread as a child of "parent", whose window has title
"title" (or the title of the parent, if title == NULL). The window
will the at (row,col) and will be "rows" lines high by "cols" columns
wide. If stack == NULL, a stack of size "stacksize" will be malloc'd,
otherwise the given stack will be used by the new task. The task will
begin by executing the function "startaddr", passing in the segment of
its parent task's handle.

If "rows" is negative, then the window will have the same number of
rows as the parent window; similarly for "cols".

If "switch_menu" is TRUE, the new task will be placed on the Switch
Windows menu.

void DVtask_free(OBJECT task)
kill the given task.

void DVforeonly(OBJECT task,int foreonly)
Sets whether or not a task will run in the background. If "foreonly"
if nonzero, the task will be suspended while in the background.

OBJECT DVmytask(void)
return the handle of the currently executing task

void DVinterrupt(OBJECT task,void far (*func)(void))

void DVtask_stop(OBJECT task)
suspend the given task. At least in DV 2.00, this call is ignored
unless the given task is the currently executing one.

void DVtask_start(OBJECT task)
restart the previously suspended task

void DVtask_post(OBJECT task)
start the given task and add its handle to the current task's objectq

WARNING: If you use multiple threads, you will have to ensure that library
routines which are not completely reentrant have a guarded replacement which
waits until any other threads have exited the function. By default,
DVGLUE.H contains #define's to protect malloc(), realloc(), and free().
Other functions to watch out for are rand(), srand(), ...printf(), and
...scanf().

Applications
------------

Applications are very similar to threads, except that each application has its
own code and data within a memory partition, and may contain multiple threads.
When a thread is started, it inherits the code of its parent; when an
application is started, it gets new code from an executable on disk.

OBJECT DVapp_new(OBJECT win,int row,int col,int rows,int cols,int switch_menu,
char *program, char *argv0, char *argv1, ..., NULL )
Start a new application as a child of the task owning "win". The
new window will be at (row,col) and will be rows by cols in size.
Load "program", and start it executing with the remaining arguments as
command line. If "switch_menu" is TRUE, the program will be listed
on the Switch Windows menu.

Returns the new application's handle, or NIL on error. The external
int _doserrno is set if the error was encountered while loading the
program. If it is 0 but the return value is NIL, then a new task
for the program could not be started.

Does not yet quite work.

OBJECT DVapp_start(void *pif_file, int pif_size)
Given the contents of the .PIF or .DVP file, start a new application in
a completely new memory partition. This function is known not to work
under all versions of DV, so use at your own risk (though I would
appreciate hearing from you which version (and date) you are using and
whether or not it worked).

v2.00 6-16-87 crashes
v2.01 10-16-87 does nothing
v2.22 11-07-88 works (yay!)

void DVapp_free(OBJECT app)
kill the given application.

void DVapp_goback(OBJECT app)
force the given application into the background

void DVapp_gofore(OBJECT app)
force the given application into the foreground

void DVapp_suspend(OBJECT app)
hide all windows belonging to the given application and suspend it.

void DVapp_hide(OBJECT app)
hide all windows belonging to the given application. The application
continues to run.

void DVapp_show(OBJECT app)
show the windows belonging to the given application.

Mailboxes
---------

Mailboxes provide a convenient way for different tasks to communicate.
Each task gets a mailbox by default, and this is the mailbox to which
asynchronous notification messages are sent (see a later section).

OBJECT DVmbx_new(void)
create a new mailbox and return its handle

void DVmbx_open(OBJECT mbx)
open a mailbox, making it available for messages. A task's default
mailbox is opened for you.
void DVmbx_close(OBJECT mbx)
close a mailbox, making it unavailable.

void DVmbx_free(OBJECT mbx)
destroy a mailbox object and return its memory to the pool of common
memory. Do not use this function on a task's default mailbox, as
the mailbox's memory is part of the task object's memory block.

OBJECT DVmymbx(void)
return handle for current task's default mailbox. Note that all of
the functions expecting a mailbox handle will accept NIL for the
default mailbox.
OBJECT DVmbxof(OBJECT task)
return the given task's default mailbox. This is useful for sending
mail to another task, such as a subtask you have created.

void DVmbx_name(OBJECT mbx,char *name)
give a mailbox a globally visible name. Using the next function,
anyone can then find the mailbox knowing only the name.
OBJECT DVmbx_find(char *name)
find the mailbox with the given name. Returns NIL if there is no
mailbox with that name.

void DVmbx_clear(OBJECT mbx)
discard all pending messages from the mailbox.

int DVmbx_size(OBJECT mbx)
return the number of pending messages in the mailbox

int DVmbx_status(OBJECT mbx)
return the status of the last message read

void DVmbx_write(OBJECT mbx,int ref,int status,char *msg,int length)
send the message "msg" with the given length to the mailbox
"mbx". The status is set to "status", and the message is passed by
reference if "ref" is nonzero, and by value (i.e. a copy is made)
if "ref" is zero.

void DVsendmail(OBJECT mbx,char *msg,int length)
send the message "msg" with the given length of the mailbox
"mbx". The status is set to zero, and the message is passed by
value (i.e. a copy is made).

int DVreadmail(OBJECT mbx,char *buffer,int maxsize)
wait for a message to arrive in the mailbox, and then fill buffer
with up to (maxsize-1) characters of the message. Returns the actual
size of the message read.

There are also two functions which use mailboxes to synchronize access to
resources, in effect treating the mailbox as a semaphore:

void DVlock(OBJECT mbx)
request exclusive access to resource. If another task has already
locked the mailbox, the current task will be halted until the other
task unlocks the mailbox. It is legal to lock the mailbox multiple
times, in which case you must unlock it the same number of times that
you locked it.
void DVunlock(OBJECT mbx)
release exclusive access to resource. If this unlocking corresponds
to the last lock placed on the mailbox, then any other task waiting to
lock the mailbox may proceed.

Fields
------

Fields are used in building a data-input screen which can be filled out by the
user. After setup, a single call lets the user fill out the entire screen,
after which the results can be read back.

void DVfld_header(OBJECT win,FT_HEADER header)
sets the field table header which defines how many fields there are,
the colors of the current field and selected fields, and the type of the
screen.

The FT_HEADER structure contains the following fields:
BYTE numfields the number of fields on the screen
BYTE type behavior flags, see DVfld_build_header
BYTE curr_attr attribute of current field during input
BYTE selected_attr attribute of any selected fields
int unknown must be zero

void DVfld_entry(OBJECT win,int field,FT_ENTRY entry)
sets up the specified field, indicating its position and type.

The FT_ENTRY structure contains the following fields
BYTE upleftrow \ row and column of upper left corner
BYTE upleftcol /
BYTE lowrightrow \ row and column of lower right corner
BYTE lowrightcol /
BYTE type type of the field, see DVfld_build_entry()
BYTE modifier type modifier, see DVfld_build_entry()
BYTE status don't quite know what this does
BYTE key2 second key of a two-key menu entry

BYTE *DVfld_build_header(int num_fields,int screen_type,
int curr_attr,int selected_attr)
begins building a stream for a screen with "num_fields" fields, using
the given screen type, where the current field will have attribute
"curr_attr" and any selected fields will have attribute
"selected_attr". All fields will have attribute "curr_attr" by
default, but this may be changed with DVfld_build_color() ;
Use DVfld_build_entry() and DVfld_build_color() to set the field
sizes and colors, and then use DVwin_stream(window,stream) to
send the stream to the window for which you want to define fields.
DO NOT FREE THE STREAM UNTIL AFTER YOU HAVE FINISHED A DVkbd_read()
ON THE WINDOW.

The following behaviors may be ORed together for the screen type:
F_NOREAD DVkbd_read() returns no data
F_READARRAY read returns a packed array of chars
F_READALL read returns var-length records of all fields
F_READNEW read returns var-length records of modified
fields
the above are mutually exclusive
F_NOFLAGS menu items returned as ' ' instead of 'Y'/'N'
F_RIGHTBUTTON right mouse button terminates entry
F_LEFTBUTTION left mouse button terminates entry
F_ALLOWKBD menu choices may be made by keystrokes

void DVfld_build_entry(BYTE *stream,int field,int upleftrow,int upleftcol,
int lowrightrow,int lowrightcol,int type,int modifier,
int status,int key2)
Define the given field (numbered from 1 to the number of fields) to
be the rectangle from (upleftrow,upleftcol) to
(lowrightrow,lowrightcol). Use the specified type of field (see
below), with the given modifier and status. "key2" should be zero
unless this is a menu entry that uses two keystrokes to select.

The legal types of fields are
F_NONENTRY no entries allowed on this field
F_MENUECHO place where keystrokes for a two-key menu are put
F_FILLIN fill-in-the-blank field
F_MENU menu selection

For type F_FILLIN, the legal modifiers (OR together) are:
F_BEEP beep when field is full
F_NEXT move to next field when field is full
F_NUMBER enter text from right to left, for numbers
F_UPPER force input to uppercase
F_CLEAR clear old field contents on first keystroke
For type F_MENU, the modifier is the first keystroke of the menu
entry, or 0 if the selection must be made with the mouse.

If the type of the field is F_MENU, then "status" is the attribute
to use when the mouse pointer is in the field.

void DVfld_build_color(BYTE *stream,int field,int attr)
given the stream built by DVfld_build_header() and DVfld_build_entry(),
set the attribute of the given field. Field numbers range from 1 of
the number of fields given to DVfld_build_header().

void DVfld_clear(OBJECT win,int field)
clears specified field to all blanks

void DVfld_char(OBJECT win,int field,int c)
fills the entire field with the specified character.

void DVfld_attr(OBJECT win,int field,int attr)
sets the display attribute of the specified field.

int DVfld_swrite(OBJECT win,int field,char *s)
write the characters of the string "s" to the specified field.
If the string is shorter than the field, the rest of the
field is padded with blanks. Returns TRUE if the string could
be written, FALSE otherwise.

int DVfld_write(OBJECT win,int field,char *s)
write EXACTLY enough characters of the string "s" to the specified
field in order to fill it. Returns TRUE if the string could be written,
FALSE otherwise.

void DVfld_cursor(OBJECT win,int field)
move the cursor to the specified field

void DVfld_scroll(OBJECT window,int field,int direction)
scroll the given field on the window one position in the specified
direction. Legal directions are SCRL_UP, SCRL_DOWN, SCRL_LEFT,
and SCRL_RIGHT.

void DVfld_type(OBJECT window,int field,int type)
Set the field's type. Legal types are F_NONENTRY, F_MENUECHO,
F_FILLIN, and F_MENU. See DV_fld_build_entry() above.

void DVfld_reset(OBJECT window)
Resets selected and modified bits on all field for the window.

void DVfld_marker(OBJECT window,char marker)
Sets the character to display at the left edge of fields which have
their "selected" bit set.

void DVfld_altmode(OBJECT keyboard,int altmode)
If "altmode" is TRUE, set the keyboard into field mode. If "altmode"
is FALSE, set the keyboard into character mode.

unsigned DVqry_fieldsize(OBJECT window,int field)
return the size in characters of the specified field on the window.

int DVqry_field(OBJECT window,int field,int buffersize,char *buffer)
put up to "buffersize" characters of the specified field on the given
window into the buffer. Return TRUE if the read was successful,
FALSE if not.

void DVqry_header(OBJECT window,FT_HEADER *header)
fill in "header" with the field table header, which indicates
the number of field and other information. See DVfld_header()
above for the format of the FT_HEADER structure.

void DVqry_entry(OBJECT window,int field,FT_ENTRY *entry)
fill in "entry" with the specified field table entry. See
DVfld_entry() above for the format of the FT_ENTRY structure.

int DVqry_type(OBJECT window,int field)
return the type byte of the specified field on the window. This byte
is also returned by DVqry_entry() as part of the field table entry.

Asynchronous Notification
-------------------------

A program running under DESQview may request to be notified when certain
events occur. When a selected event occurs, the specified handler is
immediately invoked, and a message is sent to the task's default mailbox
indicating which event occurred.

int DVwin_async(OBJECT win,void far (*func)(void),int stacksize)
Defines a notification handler for the window "win". You may share a
handler among multiple windows, as the events which apply to a single
window identify which window was affected.

"stacksize" specifies how many bytes to allocate from the heap for a
local stack which will be used inside the handler. If "stacksize"
is zero, the default of 512 bytes will be used.

Returns 0 on success, EOF on failure.

This function will not work in huge model at present. A supporting
function would have to be recoded entirely in assembler to get around
the huge model function entry code.

You may do pretty much anything inside the handler, except call
DVustack() or DVostack() [which will cause a crash] or call malloc()
and friends [which simply won't work]. Also to be avoided is
DVwin_async(our_window,NULL,n), as that does a free() on the stack
your code is executing on!

void DVwin_notify(OBJECT win,int event)
Call the notification handler set up with DVwin_async() on the
specified event. The events are defined in DVSTREAM.H and are:
DV_HMOVE window was moved left or right
DV_VMOVE window was moved up or down
DV_HSIZE window's width changed
DV_VSIZE window's height changed
DV_HSCROLL window was scrolled left or right
DV_VSCROLL window was scrolled up or down
DV_CLOSE window is requested to close itself
DV_HIDE window was hidden
DV_HELP DESQview main menu "Help for Program" selected
DV_COLORS DESQview "Rearrange" menu "Colors" option
DV_RAISE window was put in foreground
DV_LOWER window was put in background
DV_VIDEOMODE "Rearrange" "Video Options" selected
DV_SCISSORS_CUT "Scissors" menu "Cut" option selected
DV_SCISSORS_COPY "Scissors" menu "Copy" option selected
DV_SCISSORS_PASTE "Scissors" menu "Paste" option selected
DV_MAINMENU DESQview main menu popped up
DV_MENU_END DESQview main menu closed

void DVwin_cancel(OBJECT win,int event,int release)
Turn off notification of given event for the window "win". The events
are the same as for DVwin_notify().

If "release" is TRUE and this event is the last one to be cancelled
(of those enabled after the last DVwin_async() call for this window)
then the notification handler will be uninstalled and the local stack
for the handler will be freed.

void DVwin_allow(OBJECT win,int event)
Allow the specified event to occur on the window "win". The possible
events are defined in DVSTREAM.H and are
DV_HMOVE horizontal movement of the window
DV_VMOVE vertical movement of the window
DV_HSIZE changing the width of the window
DV_VSIZE changing the height of the window
DV_HSCROLL scrolling the window left or right
DV_VSCROLL scrolling the window up or down
DV_CLOSE main menu "Close" option
DV_HIDE allow DESQview "Rearrange" menu "Hide" option
DV_MARK access to DESQview's "Mark" menu
DV_SCISSORS access to DESQview's "Scissors" menu
DV_MAINMENU allow DESQview's main menu to pop up
DV_SWITCH allow switching to other window
DV_OPENMENU allow access to DESQview's "Open" menu
DV_QUIT allow DESQview main menu "Quit" option

void DVwin_disallow(OBJECT win,int event)
disallow the given event for the window "win". The events are the
same as for DVwin_allow().

NOTE: if a function is not completely reentrant, you may not use that
function within a notification handler unless the function cannot be called in
any code from which the notification may take place. If you are using a
guarded replacement (for functions such as malloc() and free()), you must
still follow this restriction, as you may otherwise hang the current process.

In addition, small-model code which assumes SS == DS (which some C library
functions do) will break, as SS will be different inside the notification
handler.

Second-Level Interrupts
-----------------------

WORD DVgetbit(void far (*handler)(void))
allocate a second-level interrupt, and set it to point to "handler"
Returns a bitmask with a single bit set, or 0 if no second-level
interrupt could be allocated.

void DVsetbit(WORD bitmask)
enqueue all second-level interrupts corresponding to set bits in the
bitmask.

void DVfreebit(WORD bitmask)
deallocate all second-level interrupts corresponding to set bits in
the bitmask.

Memory Allocation
-----------------

There are a number of functions to allocate and deallocate blocks of common
memory, and find out how much memory is available.

void DVcommon_mem(WORD *avail, WORD *largest, WORD *total)
sets "avail" to the total bytes of common memory available
sets "largest" to the number of bytes in the largest block of common
memory available
sets "total" to the total number of bytes of common memory

void DVconv_mem(WORD *avail, WORD *largest, WORD *total)
sets "avail" to the total kilobytes of conventional memory available
sets "largest" to the size in K of the largest block of conv memory
sets "total" to the total size of conventional memory in K

void DVexp_mem(WORD *avail, WORD *largest, WORD *total)
same as DVconv_mem, except that it reports on expanded memory

void far *DVgetmem(unsigned amt)
allocate "amt" bytes of system memory and return a pointer to the
allocated block.

void DVputmem(void far *block)
return the previously allocated block of system memory to the pool
of available memory.

Miscellaneous Functions
-----------------------

void DVpause(void)
give up rest of timeslice to other tasks/processes

void DVbegincrit(void)
void DVendcrit(void)
delimit a "critical section", during which TopView/DESQview will not
perform task switches.

void DVostack(void)
switch to task's private stack
void DVustack(void)
switch back to user stack

Use extreme caution with these two functions, as they switch the stack
out from under your C code. You will not be able to access local
variables after the stack switch, and any code which assumes SS == DS
will break.

void far *TVshadow(void)
returns address of shadow buffer for the current task's main window.
Under DESQview, it also starts shadowing, that is, automatically
updating the display. Under TopView, you must manually update the
display with the next function.
void TVupdate(void far *first, WORD count)
update the display from the shadow buffer, starting with the character
pointed to by "first", for "count" contiguous characters

void far *DVshadow_start(int *rows,int *cols)
similar to DVshadow(), but also returns size of shadow buffer in rows
and columns. Unlike DVshadow(), it will restart shadowing which has
been stopped by DVupdate() or DVshadow_stop().
void DVshadow_stop(void)
stop automatic updating of screen from shadow buffer. In DESQview 2.0
and higher, shadowing is also stopped by TVupdate(), but will not be
restarted by TVshadow().

int DVappnum(void)
returns the number of the current task as it appears on the "Switch
Windows" menu.

WORD DVprogname(void)
returns the offset within DESQVIEW.DVO of the current task's name.

void DVdbgpoke(char c)
write the character directly to the 25th line of the screen. After
the character is written, the next call will place the character in
the next position, wrapping back to the beginning of the 25th line
if necessary. Note that this function does not heed any windows which
may be on the screen, nor does it work properly in graphics modes.

void DVenable(void)
enable DESQview extensions for the current task. I don't yet know
what the extent of these extensions is.

void DVjustify(int justify)
if "justify" is nonzero, the viewport origins of windows will shift
to keep the cursor within the visible portion of the virtual screen.
If "justify" is zero, no such shifting will take place.

void DVgetbuf(OBJECT window,char far **buffer,int *size,int *flag)
Get the virtual screen buffer for the given window. On return,
"buffer" points to the screen buffer, which contains "size" bytes.
I don't know yet what "flag" is.

void DVsound(int frequency,int duration)
make a tone with the given frequency in Hertz for the given duration
in clock ticks (1/18 sec). The function returns immediately, while
the tone plays to completion. If another tone is already playing, the
new one is enqueued, up to 32 deep (if the queue is already full, then
the function waits until the current tone completes before returning).

void DVnosound(void)
cancel all tones queued up to be played, and turn off the current tone
(if any).

int DVobjtype(OBJECT obj)
return the type of the object. Possible return values are
WINDOW_CLASS
MAILBOX_CLASS
KEYBOARD_CLASS
TIMER_CLASS
OBJECTQ_CLASS
POINTER_CLASS
PANEL_CLASS
Note: This function works under DV 2.00 or higher, but uses
undocumented data structures if running under DV versions
less than 2.20.


XDI Functions
-------------



QEMM Interface
--------------

int QEMMinit(void)

int QEMMcall(DVGREGS *inregs, DVGREGS *outregs)

int QEMMget_state(void)

int QEMMset_state(int state)

int QEMMmem_avail(unsigned *total,unsigned *available)

int QEMMget_debug(DEBUGREGS *regs)

int QEMMset_debug(int INT01handling,DEBUGREGS *regs)

long QEMMget_CR0(void)

long QEMMmax_physmem(void)
Return the address of the highest byte of physical memory. If
you have 'top' memory in your system, this may be 0x00FFFFFF
(16M-1) even if you have less than 16M of RAM.

long QEMMphysaddr(int pagenum)
Return the physical address for the beginning of the specified
page in the logical address space (page number is linear
address divided by 4096).

int QEMMmemory_type(char *buffer)
Fill the 256-byte buffer with the type of each 4K page of
memory.

int QEMMhiram(void)
Return the segment of the start of the high memory chain or 0
if no high memory is available.

int QEMMget_accessed(char *buffer)

int QEMMset_accessed(char *buffer)

int QEMMget_memusage(QEMM_USAGE *buffer)

int QEMMcheck_remapping(char far *startaddr,unsigned pages)

int QEMMinportb(int portnumber)
Read the current value of an 8-bit I/O port. Returns the value
or -1 if this function is not supported by the installed QEMM.

int QEMMinportw(int portnumber)
Read the current value of a 16-bit I/O port (two consecutive
8-bit I/O ports). Returns the value or -1 if this function is
not supported by the installed QEMM.

int QEMMoutportb(int portnumber,unsigned value)
Write the specified value to an 8-bit I/O port. Returns 1 if
successful, 0 on error.

int QEMMoutportw(int portnumber,unsigned value)
Write the specified value to a 16-bit I/O port (two consecutive
8-bit ports). Returns 1 if successful, 0 on error.


VIDRAM Interface
----------------

void far *VIDRAM_entrypoint(void)

int VIDRAM_installed(void)

int VIDRAM_status(int *features,int *flags,int *monitor,int *memtop,
int *highram)

int VIDRAM_setup(int state,int features,int flags,int monitor,
unsigned memtop)



User Interface Functions
------------------------

The functions in this section are all high-level functions, which make use of
a number of the primitives described in previous sections. If you wish to use
them, you must include "DVGUI.H" after "DVGLUE.H".

The first function allows you to display menus that look like the ones
DESQview itself uses.

int UImenu(DVMENU *menu)
Displays the specified menu.

Format of the menu record:
typedef struct
{
char *title ; The menu's title
DVMENU_ITEM *items ; the actual items of which the menu
is composed
int row ; Position of menu. Values less
than 0 are measured from bottom
int col ; Position of menu. Values less
than 0 are measured from right
void (*before)(DVMENU *menu) ;
Function called before
displaying the menu or NULL.
void (*after)(DVMENU *menu) ;
Function called after menu is
removed or NULL.
int (*cancel)(OBJECT window,int status,char *results) ;
Function called when menu is
cancelled or NULL.
int (*error)(DVMENU *menu,OBJECT window,int errcode) ;
Function called on error or NULL
char allow_kbd ; Can menu items be selected from
the keyboard?
char allow_oversize ; Build menu even if too big for
screen?
char allow_move ; Allow user to move the menu?
char reset ;
char marker ; Marker character for selected
menu items
char text_color ; attribute for menu, 0 = default
char select_color ; attrib for selected items, 0 = default
} DVMENU ;

Format of a menu item:
typedef struct
{
char *entry ; The string to display for this entry
char type ; The item's type, see below
char key1 ; The first key to use
char key2 ; The second key to use, 0 if none
char selected ; the field starts out selected if nonzero
DVMENU_FUNC func ; the function to invoke
long arg ; optional argument to the function
} DVMENU_ITEM ;

Valid menu item types:
M_IGNORE this menu item should be skipped; useful for
"commenting out" unused items
M_TEXT descriptive text, not a selectable item
M_CENTER centered text, not a selectable item
M_SEP separator line, item.key1 is replicated across menu
M_FLAG set/clear flag variable
M_FUNC invoke a function
M_FUNCMENU same as M_FUNC, but leaves menu(s) visible
M_SUBMENU invoke a submenu displayed relative to original menu
M_SUBMENUR same as M_SUBMENU, but removes previous menu
for the duration of the submenu
M_QUIT quit current menu when selected
M_END indicates the end of the menu description

The above types may be ORed with any combination of the
following, though not all combinations are meaningful:
M_EXIT exit menu after performing function or setting flag
M_HOT menu key without visible entry (hotkey)
M_HI highlight line
M_SEL select the entry by default (if M_FLAG)
M_KEY the portion of the item's text after the last
blank is right-justified as the key name

Error returns: UImenu_build can return three errors, and you should
check for them before using the returned stream.
ME_NOMEM unable to allocate memory
ME_RESOURCE unable to allocate a needed resource
ME_TOOBIG menu won't fit on the screen
ME_BADITEM invalid menu item type. This is usually caused by
forgetting the M_END entry at the end of the menu
description. It can also be caused by a missing
string for M_ITEM and a string without blanks for
M_KEY.

Valid test function returns. These may be ORed together:
MA_DONE done, re-run menu \ mutually
MA_EXIT exit current menus > exclusive
MA_ABORT exit all menus /
MA_BEEP 1/4 second beep
MA_RESET reset "selected" bits for all menu items
MA_SELECT change "selected" status of all fields to match
changed values in the string which was passed to the
test function.

Status returned by UImenu():
0 RETURN pressed, unless a menu item defines RETURN as its
keypress
1 menu item selected by pressing left mouse button, or typing
the item's keystroke(s).
2 entry aborted with the right mouse button (possibly
Esc or PgUp as well)
27 entry aborted by pressing ESC.
73 entry aborted by pressing PgUp (keyboard mouse)
any other value indicates the extended-ASCII value of function or
Alt-keys which are not defined as fields and not used by DESQview
itself.

The next function lets the user move and resize a new window by dragging it
around with the mouse.

OBJECT UIwin_open(OBJECT parent,int minrows,int mincols,
int maxrows,int maxcols,int defrows,int defcols)
Prompt the user to use the mouse to position and size a new window,
which defaults to "defrows" by "defcols" in size, and must be at least
"minrows" by "mincols", but no more than "maxrows" by "maxcols."
Returns the handle for the new window.

The last function (for now), is a higher-level version of DVwin_async(),
which allows a separate handler for each possible event which DESQview can
notify a program of, and allows multiple handlers for the same event on
a single window.

int pascal UIsignal(OBJECT window,int direction,int num_signals,
SIGNAL_LIST *signals,int stacksize) ;
If 'direction' is DVSIG_ADD, UIsignal() arranges for the function(s)
listed in 'signals' to be given control if the corresponding DESQview
signal is received on the specified window. The value 'stacksize'
specifies the size of the local stack which will be allocated from the
heap. If 'stacksize' is zero, the default of 512 bytes will be used,
of which about 470 will be available to your function. UIsignal()
returns an identifier which must be used when removing the signal
handlers at a later time.

If 'direction' is DVSIG_REMOVE and 'stacksize' equals an identifier
previously returned by UIsignal() for the specified window, UIsignal()
removes that previously-installed set of signal handlers.

The handler for a signal is called with a single argument, the
notification message for the event. As with DVwin_async(), you may do
pretty much anything inside the handler, except call DVustack(),
DVostack(), and the various malloc() functions. The first two will
cause a crash, the latter simply won't work. You should also
avoid modifying the message passed to the handler, as any such
modifications will be visible to the next handler for the same
event on the same window.

DO NOT mix this function with the DVwin_async() function, as that
will cause unpredictable results.




  3 Responses to “Category : Alternate Operating Systems - Quarterdeck DesqView, CP/M, etc
Archive   : DVGLUE17.ZIP
Filename : DVGLUE.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/