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

Output of file : README.DOC contained in archive : APICSAMP.ZIP
DESQview API C Sampler, Copyright (c) 1989 Quarterdeck Office Systems.

Quarterdeck Office Systems
150 Pico Boulevard Santa Monica, CA 90405
(213) 392-9851 Fax (213) 399-3802

DESQview API C Library

The DESQview API (Application Program Interface) C Library is a set
of over 200 functions that gives your C program full access to the

Using the C Library a program can ask the DESQview API to:

o display information in windows and change the color, dimensions,
position, and ordering of windows on the screen,

o handle all keyboard and mouse input to menus and forms,

o schedule processing after a certain time interval or at a certain
time of day,

o spawn subtasks for performing background operations such as printing,
recalculating, and communicating,

o communicate between the various tasks in the system,

o disable, limit, or enhance the standard DESQview user interface.

The DESQview API C Library consists of over 200 functions divided
into groups according to the type of object they manipulate. These
objects include: applications, fields, keyboards, mailboxes, objectqs,
panels, pointers, timers, tasks, and windows. The groupings correspond
closely to the organization of the DESQview API Reference Manual, a copy
of which is included with the C Library.

DESQview API C Library functions are divided into 12 logical groups.
Every function in a group has the same 4 character prefix, usually
indicating the type of object the function operates on. The groups are:

Prefix Group
------ -----
api_ General Functions
app_ Application (parent task) Management Functions
fld_ Field Management Functions
key_ Keyboard Management Functions
mal_ Mailbox Management Functions
obq_ Objectq Management Functions
pan_ Panel Management Functions
ptr_ Pointer Management Functions
qry_ Query Functions
tim_ Timer Management Functions
tsk_ Task Management Functions
win_ Window Management Functions

The DESQview API C Library supports the Microsoft C, Lattice C, Borland
Turbo C and Metaware High C compilers for all memory models. Source code
for the C Library is included so that the library can be converted for use
with other compilers if needed.

DESQview API C Interfaces

Listed below are the DESQview API C interfaces available with the
DESQview API C Library.

General Functions

api_beginc begin critical region
api_cancel cancel current Window Mgr operation
api_endc end critical region
api_exit exit API interface
api_freebit disconnect 2nd level interrupt handler
api_getbit define 2nd level interrupt handler
api_getcrit get critical region nesting level
api_getmem get system memory buffer
api_init initialize API interface
api_isobj determine if a given handle is valid
api_justify enable/disable automatic justification of window
api_kmouse turn keyboard mouse on and off
api_level define API revision level required by application
api_objtype determine the object type of a given handle
api_pause give other tasks a chance to run
api_poke display debug information/bottomline of screen
api_putmem return system memory buffer
api_pushkey push key into input stream
api_setbit schedule 2nd level interrupt handler
api_shadow get task's logical window buffer& start shadowing
api_sound make a sound
api_update redraw portion of logical window and stop shadowing

Application Management Functions

app_foreonly indicate whether a task can run in background
app_free free an application and its window
app_goback force an application into background
app_gofore force an application into foreground
app_hide hide all windows of an application
app_new create a new application in the current process
app_number get current applications SWITCH number
app_show display all windows of an application
app_start start a new application in a new process
app_suspend suspend & hide all application's tasks

Field Management Functions

fld_altmode set Alternate field processing mode
fld_attr fill a field with a given attribute
fld_char fill a field with a given character
fld_clear clear a field
fld_cursor move cursor to a field
fld_entry change field table entry
fld_header change field table header
fld_marker define selected field marker character
fld_point move pointer to given position in field
fld_protattr set Protected Attributes field processing mode
fld_reset reset selected and modified bits
fld_scroll scroll a field
fld_swrite write a string into a field
fld_type change the type of a field
fld_write write characters into a field

Keyboard Management Functions

key_addto set keyboard behavior flags
key_close disconnect keyboard from its window
key_erase discard pending keyboard input
key_free free a keyboard object
key_getc wait for next key (keystroke mode)
key_getflags get keyboard control flags
key_getpri get objectq priority level of keyboard
key_me get current tasks keyboard handle
key_new create a new keyboard object
key_of get handle of a given task's keyboard
key_open attach keyboard to a given window
key_read read input from keyboard
key_setesc define function to filter keys in field mode
key_setflags replace keyboard control flags
key_setpri set objectq priority level of keyboard
key_sizeof get # keyboard messages pending
key_status get status of last keyboard message
key_subfrom clear keyboard behavior flags
key_write write data to keyboard

Mailbox Management Functions

mal_addr return sender of last message
mal_addto send message by value with given status
mal_close close a mailbox
mal_erase erase all pending messages
mal_find find a mailbox by name
mal_free free a mailbox object
mal_getflags get mailbox control flags
mal_getpri get objectq priority level of mailbox
mal_lock lock access to a resource
mal_me get handle of MAILME mailbox
mal_name assign a global name to a mailbox
mal_new create a new mailbox
mal_of get handle of a given task's mailbox
mal_open open a mailbox
mal_read wait for next message
mal_setflags replace mailbox control flags
mal_setpri set objectq priority level of mailbox
mal_sizeof get # messages pending
mal_status get status of last message received
mal_subfrom send message by reference with given status
mal_unlock unlock access to a resource
mal_write send a message by value with status zero

Objectq Management Functions

obq_close close the task's objectq
obq_erase erase contents of the task's objectq
obq_open open the task's objectq
obj_read wait for any object to have input
obq_sizeof get # of objectq entries pending
obq_status determine if the task's objectq is open
obq_subfrom remove an object from the task's obectq

Panel Management Functions

pan_apply display a named panel & prepare for input
pan_close close a panel file
pan_dir get list of panels in the panel file
pan_free free a panel object
pan_new create a panel object
pan_open open a panel file
pan_sizeof get # panels in the panel file
pan_status get status of last pan_open or pan_apply

Pointer Management Functions

ptr_addto set pointer control flags
ptr_close close a pointer object
ptr_erase erase pending pointer messages
ptr_free free a pointer object
ptr_getflags get pointer control flags
ptr_getpri get objectq priority level of pointer
ptr_getscale get current scaling factors
ptr_new create a new pointer object
ptr_open open pointer and assign to a window
ptr_read wait for next pointer message
ptr_setflags replace pointer control flags
ptr_setpri set objectq priority level of pointer
ptr_setscale set current scaling factors
ptr_sizeof get # messages pending
ptr_status get button state from last message received
ptr_subfrom clear pointer control flags
ptr_write move the pointer to a given position

Query Functions

qry_atread TRUE if win_read and win_readn reads attributes
qry_attr get current output attribute
qry_color get physical attribute for given logical attribute
qry_ctrl TRUE if processing control codes
qry_cursor get current cursor position
qry_entry get field table entry
qry_field get contents of a field
qry_frame TRUE if the window has a frame
qry_frattr get current frame attribute
qry_header get field table header
qry_hidden TRUE if the window is hidden
qry_kmouse TRUE if using a keyboard mouse
qry_leave TRUE if leaving attribute untouched when writing
qry_lsize get size of logical window buffer
qry_logattr TRUE if using logical attributes
qry_origin get origin of physical window relative to logical
qry_position get position of physical window
qry_size get size of physical window
qry_title get window's title
qry_type get type of field

Timer Management Functions

tim_addto start a timer for a given interval
tim_close close a timer object
tim_erase stop a running timer
tim_free free a timer object
tim_getpri get objectq priority level of timer
tim_len get time remaining until timer expires
tim_new create a new timer object
tim_open open a timer object
tim_read wait for timer to expire
tim_setpri set objectq priority level of timer
tim_sizeof get time since a timer started running
tim_status determine if a timer is running
tim_write start a timer for a given time of day

Task Management Functions

tsk_free free a task and its window
tsk_geterror get error handling level of current task
tsk_me get handle of current task
tsk_new create a new task
tsk_pgmint software interrupt another task
tsk_post restart a task and post its Objectq
tsk_seterror set error handling level of current task
tsk_start restart a stopped task
tsk_stop temporarily stop a task

Window Management Functions

win_addto write characters and attributes to a window
win_adopt adopt a window
win_allow specify which DESQview commands are allowed for a window
win_async define asynchronous notify function
win_atread sets read mode to read either charaters or attributes
win_attach attach window to its parent task window
win_attr set current output attribute
win_blanks write blanks to a window
win_bottom make window bottommost in its application
win_buffer get pointer to window's logical window buffer
win_cancel cancel notification on a given event
win_color change logical attribute mapping
win_ctrl enable/disable interpretation of control characters
win_cursor move window's logical cursor
win_dflt change default notify window
win_disallow specify which DESQview commands are not allowed for a window
win_disperor display an error message window
win_eof TRUE if logical cursor is beyond end of window
win_erase clear window
win_frame enable/disable display of a window's frame
win_frattr define window frame attribute
win_free remove a window from the screen and free its handle
win_hcur display hardware cursor at logical cursor position
win_hide marks a window as hidden
win_leave leave existing attribute when writing to a window
win_len return width of logical window
win_locate return which window is visible at the given screen row/col
win_logattr use logical/physical attributes
win_lsize set windows logical dimensions
win_maxsize set windows maximum physical dimensions
win_me get current task's window handle
win_minsize set windows minimum physical dimensions
win_move move physical window
win_new create a new window
win_notify enable notification on a given event
win_nread read n characters from a window
win_open fill a window with a given character
win_origin define portion of logical window viewed in the physical window
win_orphan orphan a window
win_paste define window as current clipboard window
win_point jump mouse to logical cursor position
win_poswin position window relative to another window
win_printf write formatted data to a window
win_putc write a character/attribute pair to a window
win_read read rest of current line from window
win_redraw redraw a window
win_reorder reorder an applications windows
win_repattr write an attribute to a window n times
win_repchar write a character to a window n times
win_resize set physical dimensions of window
win_scroll scroll all or part of a window
win_sizeof get total number of characters in logical window
win_stream write a stream to a window
win_subfrom write attributes to a window
win_swrite write a zero terminated string to a window
win_title change a windows title
win_top make window topmost in application
win_topsys make window topmost in system
win_unhide marks a window as not hidden
win_write write characters to a window

DESQview API C Examples

Also included in the C Library is a C Examples diskette, containing
sample programs that show the basics of writing DESQview-specific
programs. Examples cover the creation of a simple pop-up menu, creation
of a complex menu (using timers and waiting on multiple events), tracking
of a mouse, subtask creation and termination, intertask communications
and named mailboxes, asynchronous notifies, and process creation.

The examples are presented roughly in order of increasing complexity. The
primary purpose of each is to show:

Example Shows
------- -----
hello a minimal DESQview-specific program
fruit a simple pop-up menu
point how to track the mouse
washer a complex menu, timers, and waiting on multiple events
snakes subtask creation and termination
server intertask communication and named mailboxes
request intertask communication and asynchronous notifies
examples process creation

The following are the opening comments for each example program:

* Name: HELLO
* Function: display 'hello world' in the task window
* Shows how to: 1. write a 'minimal' DESQview-specific program.
* 2. initialize and disable the C interfaces.
* 3. detect DESQview's presence.
* 4. enable DESQview extensions.
* 5. write to the default task window.

* Name: FRUIT
* Function: display a pop-up menu and report selections
* Shows how to: 1. create a new window and associated keyboard.
* 2. define the contents and fields for a menu.
* 3. move and display a window.
* 4. take input from a menu.

* Name: POINT
* Function: track the pointer as it passes through the window.
* Shows how to: 1. create and read a pointer object.
* 2. force the keyboard mouse ON, if applicable.
* 3. display single characters in a window.
* 4. jump the pointer.
* 5. change cursor position for a window.

* Name: WASHER
* Function: Emulate a washing machine control panel.
* Shows how to: 1. construct complex menus (dialogues) including
* select, input, output, and inactive fields.
* 2. change field types dynamically.
* 3. implement "radio button" select fields.
* 4. use a timer object to measure time intervals.
* 5. use an objectq to wait for multiple events.

* Name: SNAKES
* Function: display multiple "snakes" each controlled by a
* separate task.
* Shows how to: 1. create and terminate subtasks.
* 2. use mail to send initial data to a new task.
* 3. use a semaphore to control access to a
* resource, in this case the window.
* 4. read and write the window contents.

* Name: SERVER
* Function: This program provides a very simple file
* management service. It maintains a database
* consisting of arbitrary length text strings and
* allows the database to be queried for all
* records containing a specified substring.
* Queries are sent by mail from REQUEST windows.
* The results are returned to the REQUESTers
* mailbox.
* Shows how to: 1. use named mailboxes to detect multiple
* instances of the same program.
* 2. use named mailboxes to control access to
* public utilities.
* 3. send and receive mail.
* 4. use a timer object to display a running clock.
* 5. optimize a program by performing the equivalent of
* multiple C Library calls in one encoded stream.

* Function: Provides a front-end for the SERVER program.
* Takes a string entered by the user and sends
* requests to the SERVER to either add the string
* to the database or find all records that contain
* the string.
* Shows how to: 1. find a named mailbox.
* 2. read a key-at-a-time from the keyboard.
* 3. use an asynchronous notify function to
* detect attempts to close the window.

* Function: Display a menu listing the example programs and
* start an example as a new process when so requested.
* Shows how to: 1. read a DESQview Program Information File (DVP)
* from disk.
* 2. adjust the DVP to reflect the current drive and
* directory.
* 3. start a new process using the DVP.

Installing the C Examples

To install the example programs, copy all files from the diskette into any
directory of your choice and use the DESQview "Add a Program" feature to
add programs from that directory. Select the only option that you are
presented, the "C Examples" program. When you then open a "C Examples"
window, a menu will be presented that lets you run the other example

  3 Responses to “Category : Alternate Operating Systems - Quarterdeck DesqView, CP/M, etc
Archive   : APICSAMP.ZIP
Filename : README.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: