Window handling library

This library is for handling windows on screen. It handles both the routines to use windows (like glass teletype displays), as the routines which are needed for controlling the pointer. Because they are mainly used in conjunction with the pointer, the event handling routines are also contained here (there was no better place to put them).

This library only implements a limited set of low level calls. For higher level calls to handle proper drawing and for a window manager for writing applications, use PROforma and ProWesS.

This library should not be important for most applications (unless you do not use ProWesS). However by using this library instead of ProWesS it is often possible to write more lightweight programs.

All windows have a default timeout associated with them. The default timeout is shared by all the jobs which use the window. When the Window was passed as command line parameter (in the shape of a Channel - which is in fact the same), it is adviceable to set the default timeout to a suitable value (as this will not be done if the window was opened without using syslib). When a window is opened with one of the WINOpen routines, the default timeout is set to FOREVER.

The windowing routines sometimes refer to an outline. An outline is always associated with a window. Each job may have several windows with an outline. The outline which was opened first (counting restarts when all windows are closed) is called the primary window. All the windows which are owned by a job have to fit inside the outline for the primary window. As an aside, the area below an outline is saved when the outline is assigned, and the outline is restored when the window is closed. Only windows which have an outline can use the pointer (and are called well behaved).

The supported drawing routines are very limited. It is intended that all actual drawing is always done in WindowArea objects, which are then displayed in the window.

init
WINOpen
Open a window. This call only needs the size. It doesn't set the outline.
WINOpenFull
Open a window, including setting of the outline, shadow, border, paper, strip, ink. All data is extracted from a structure.
WINClose
Close a window.
WINMode
get the window mode which can be assumed on WINOpen.
input/output
WINGet
Get a character. The cursor is displayed while waiting.
WINPut
Print a character at current cursor position.
WINPutString
Print string at current cursor position (a newline is appended).
WINTest
Test for pending input.
timeout
WINTimeOutGet
Get the current timeout value for the given window.
WINTimeOutSet
Set the timeout value to use for the given window.
window handling
WINWindow
Set new window size and position, inside outline !
WINBorder
Set border width and colour. This reduces the size of the window by the border width. The OS automatically uses double border width horizontally.
WINRedefine
Redefine both window and border. This is a combination of WINWindow and WINBorder.
WINPaper
Set the paper colour.
WINStrip
Set the strip colour.
WINInk
Set the ink colour
WINUnderline
Set the underline status
WINOverwrite
Set the overwrite status
WINScroll
Scroll window (vertical scroll).
WINScrollTop
Scroll top of window (above cursor line).
WINScrollBottom
Scroll bottom of window (below cursor line).
WINPan
Pan window (horizontal scroll).
WINPanLine
Pan cursor line.
WINPanRight
Pan right hand end of cursor line (including cursor position).
WINClear
Clear all of window.
WINClearTop
Clear top of window.
WINClearBottom
Clear bottom of window (below cursor line).
WINClearLine
Clear cursor line.
WINClearRight
Clear right hand end of cursor line (including cursor position).
cursor
WINCursorEnable
Make a cursor visible.
WINCursorDisable
Hide cursor.
WINNewLine
Move cursor to next line.
WINColumnPrev
Move cursor to previous column.
WINColumnNext
Move cursor to next column.
WINRowPrev
Move cursor to previous row.
WINRowNext
Move cursor to next row.
WINAtCursor
Position cursor at cursor coordinates.
WINAtColumn
Position cursor, column only (in current cursor line).
WINAtPixel
Position cursor at pixel position.
WINInfoPixel
Get pixel position of cursor and window size.
WINInfoCursor
Get cursor position of cursor and window size (no of cursor lines and columns).
WINCursorSize
Set size of cursor (or font size).
WINPendingNewLine
Do possible pending newline.
pointer routines
WINLimits
Get window limits, which is the area which bounds the outline.
WINOutline
Set outline and shadow for window.
WINMove
Move window to another position.
WINSubWindows
Define the subwindows, used for sprite definitions.
WINPointerRead
Read pointer. Ths functions uses an explicit timeout !
WINPointerPositionSet
Set pointer position.
WINPointerPositionGet
Get pointer position.
WINPointerLimits
Set the area to which the pointer should be confined. This command is cancelled when the current key press is released. This command is normally used while dragging to limit the region in which the pointer is allowed to move.
Window area handling
WINAreaAllocate
Allocate a window area.
WINAreaRelease
Release a window area.
WINAreaSave
Save part of window in a window area.
WINAreaRestore
Restore part of window from window area.
drawing routines
WINBlock
Draw a rectangular block in a window.
WINSprite
Draw a sprite.
event handling
WINEventSend
Send a software generated event to a job.
This routine can generate several events at one
err=WINEventSend(job, EVENT_LEVEL1|EVENT_LEVEL5);
WINEventWait
Wait for software generated events. The timeout for this call is explicit. The job will only wait for software events, and not for user generated events, thus a pointer is not being displayed.
Error err;
WindowEvent events;

events=EVENT_LEVEL1|EVENT_LEVEL4;
err=WINEventWait(timeout, &events);
if (err==ERR_NC)
    /* handle timeout event */
if (events&EVENT_LEVEL1)
    /* do your thing */
if (events&EVENT_LEVEL4)
    /* do your thing */
standard sprites
SPRITE_ARROW
arrow (different from default pointer)
SPRITE_HAND
hand sprite
SPRITE_LEFT
arrow pointing left
SPRITE_MOVE
standard WMAN move sprite
SPRITE_SIZE
standard WMAN resize sprite
SPRITE_SLEEP
Zzz sprite
SPRITE_WAKE
lightning bolt, standard WMAN wake item
SPRITE_NULL
empty sprite

PROGS, Professional & Graphical Software
last edited February 7, 1996