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