Info
Content

EPOC16 Window Server Calls

This file wouldn't have appeared for much longer if it weren't for Dan Ramage, who sent Clive enough material to convince him to restart after many months of neglect.

Dan, if you're still about, we would really like the source code for your Damage graphics engine!

This page is dedicated to the memory of Felicia Hatunen. Most of Clive's original version of the document this was based on was written while he was travelling to and from a memorial service for her (in California). It seems fitting that such a memorial should remain.

There is a lot of missing and incomplete material in this file. By his own admission, there are a number of gaps in what Clive had (and we currently have), particularly the mapping of registers to C function arguments. Therefore this file contains more than the usual number of @ signs indicating missing material. Assistance in filling these gaps would be greatly appreciated.

Introduction

Processes in EPOC16 do not have direct access to the screen and keyboard. Instead, they send messages to a special process called the Window Server. This process then handles the screen and keyboard, arbitrating between the various requests - for example, it ensures that only the current foreground process gets keystrokes, and handles the case of different application windows overlapping.

Many calls to the Window Server are buffered; the individual commands are stored in a buffer, and then sent to the server in a batch. This is done whenever the buffer is full, by any command requiring a response from the server, whenever waiting for an event, and by the wFlush call. The calls that return a value but do not flush the command buffer are:
gTextCount, gFontInfo, and wCheckBitmapid.

If an error occurs when a buffered command is executed, all further commands are ignored until one that requires a response. This command is also ignored, and the error is returned instead.

Clients of the window server can be in the foreground or background. On machines with a small screen, only one client can be in the foreground, and it occupies the whole screen. On machines with a large screen, more than one client can be in the foreground or be visible at a time.

See the file SYSCALLS.1 for the notation used in this file. In the case of function 0x8D, bit 7 of the sub-function number is set to indicate that the function obtains a response from the server; this bit is ignored in ordering the functions in the following list of descriptions. Furthermore, in the case of Fn 0x8D Sub 0x7E and Sub 0xFF, there are several different functions depending on the value of AL.

If a call is marked "fails" then:

  • if it fails, the resulting behaviour depends on the error handling flag set by wDisableLeaves;
  • if no new value is shown for AX, it is set to 0 on success.

A common data structure is the "standard rectangle structure". This is defined here:

Offset Length Description
0 2 x coordinate of left edge of the rectangle
2 2 y coordinate of top edge of the rectangle
4 2 x coordinate of left edge plus width
6 2 y coordinate of top edge plus height

Graphics Contexts

Many window server calls are described as using a "graphics context". This is a data structure associated with a specific window or bitmap and stored in the window server itself. It determines various features about the call, such as the font used in text operations. At any time there is a "current GC"; calls labelled "cgc" use that to determine appropriate properties.

A graphics context is specified using a GC description block. This is a block of memory in the client laid out as follows:

Offset Length Description
0 1 Graphics mode (0=set, 1=clear, 2=invert)
1 1 Text mode (0=set, 1=clear, 2=invert, 4=copy with background)
2 1 Text style
3 1 Additional graphics options (v4 only)
4 2 Font or font group

Offset 2: Text styles

Bit Description
0 bold
1 underline
2 inverse
3 double height
4 monospaced
5 italic
6 subscript (v4 only, and only with appropriate font groups)
7 superscript (v4 only, and only with appropriate font groups)

Offset 3: Additional graphics options (v4 only)

Bit Description
0-1 0 = black plane, 1 = grey plane, 2 = both planes
2 double pixel mode, clear = normal

Wherever a font is required, one of the ROM-based fonts beginning at 0x4000 can be used. The value 0x4099 always means the system font.

GC description blocks are normally provided in association with a GC selector mask. This is a word which is used to determine which values are taken from the description block, as follows:

Bit Description
1 graphics mode
2 text mode
3 text style
4 font
5 bits 0 and 1 of additional graphics options (v4 only)
6 bit 2 of additional graphics options (v4 only)

When creating a new GC, values not taken from the description block are set to zero, except the font which is set to the system font.

Events

An event is a message sent from the window server to a client to inform it that something has happened that is not directly related to a function call; for example, that a key has been pressed when the client is the foreground client. The event is between 2 and @@ bytes long depending on its type. Offset 0 is always a word giving the event type.

In many types of event the words at offsets 2 and 4 have a standard meaning.

  • "window handle" (offset 2) - this is the value passed to wCreateWindow. It is not the same as the window identifier, and is commonly set to the address of a structure including the latter.
  • "connection handle" (offset 2) - @@@ the value specified to wConnect
  • "tick count" (offset 4) - the window server maintains this value, which it increments every tick (1/32 second).

Type 1: WM_KEY

Offset Length Description
0 2 type, set to 1
2 2 connection handle
4 2 tick count
6 2 keycode
8 1 keyboard modifiers and mouse state
9 1 unused
10 1 repeat count

Sent when a key is pressed and the client is the one connected to the keyboard (usually because it owns the frontmost foreground window). The keycode is defined by the key and modifiers. For example, the 'A' key will generate:

  • 0x0061 alone
  • 0x0041 if shift is pressed or caps lock is on
  • 0x0001 if control is pressed
  • 0x0261 if Psion or alt is pressed

The window server will handle control-plus-number combinations and generate a single event. @@@@ special cases

The modifiers are:

Bit Description
1 shift key pressed
2 control key pressed
3 Psion or alt key pressed
4 caps lock is on
5 num lock is on
6 Not used.
7 mouse button down

The repeat count is 1 for a single key press. If a key is held down and is auto-repeating faster than the client accepts new events, the repeat count will be set to the number of repeats since the last key event.

Type 2: WM_MOUSE

Offset Length Description
0 2 type, set to 2
2 2 window handle
4 2 tick count
6 1 1=release, 2=press, 3=motion
7 1 keyboard modifiers and mouse state
8 2 mouse position x coordinate
10 1 mouse position y coordinate

Sent when the mouse button is pressed or released, or the mouse moves and the appropriate window has requested motion events. The modifiers are as for WM_KEY, plus Bit 6:

Bit Description
1 shift key pressed
2 control key pressed
3 Psion or alt key pressed
4 caps lock is on
5 num lock is on
6 mouse position is outside the visible portion of the window
7 mouse button down

This can happen through grabs and mouse capture.

Type 3: WM_REDRAW

Offset Length Description
0 2 type, set to 3
2 2 window handle
4 2 tick count
6 2 left edge
8 2 top edge
10 2 @@@ right edge or width or what ?
12 2 @@@ bottom edge or height or what ?

Sent when no other events (except WM_USER_MSG) are pending and a window has an area that needs redrawing (an "update region"). The rectangle describes some portion (possibly all) of the update region.

Type 5: WM_BACKGROUND

Offset Length Description
0 2 type, set to 5

Sent to a client in the foreground when it moves to the background.

Type 6: WM_FOREGROUND

Offset Length Description
0 2 type, set to 6

Sent to a client in the background when it moves to the foreground.

Type 7: WM_RUBBER

Offset Length Description
0 2 type, set to 7
2 2 window handle
4 2 tick count
6 2 final status
8 8 standard rectangle structure giving the final size

Offset 6: Final Status

The final status can be:

Bit Description
0 the final rectangle is the same as the initial one
1 the rubber band moved but was not resized
2 the rubber band was resized
3 the rubber band was cancelled; the rectangle is undefined
4 the rubber band was not displayed because the parameters were wrong

Type 8: WM_USER_MSG

Offset Length Description
0 2 type, set to 8

Sent to a client following a call to wUserMsg if no other events are pending (and so can be used to check that condition).

Type 9: WM_ACTIVE

Offset Length Description
0 2 type, set to 9

More information needed.

Type 11: WM_CANCELLED

Offset Length Description
0 2 type, set to 11

Sent to a client following a call to wCancelGetEvent.

Type 12: WM_KEYBOARD_STATE_CHANGE

Sent to the system shell only.

Type 13: WM_RUBBER_BAND_INIT

Offset Length Description
0 2 type, set to 13
2 2 window handle
4 2 tick count
6 1 set to 2
7 1 keyboard modifiers and mouse state
8 2 mouse position x coordinate
10 2 mouse position y coordinate

Sent to a client on a button press when the window is configured so that pressing a mouse button starts rubber banding. The window server will suspend all mouse and keyboard processing for all clients until this client calls wRubberBand. If rubber banding is not desired, the cancel flag can be used in the call.

Type 14: WM_DEICONISE

Offset Length Description
0 2 type, set to 14

Sent to an iconised client when it moves to the foreground.

Type 15: WM_ATTACHED

Offset Length Description
0 2 type, set to 15
2 2 Unknown
4 2 tick count
6 2 attached client

Sent to a client when another client has attached itself on top. Note that the notifier process attaches itself to a client when that client uses the p_notify system call.

Type 16: WM_DETACHED

Offset Length Description
0 2 type, set to 16

Sent to a client when a previously attached client detaches itself.

Type 17: WM_COMMAND v3.5

Offset Length Description
0 2 type, set to 17

Sent to a client that is the target of a wSendCommand call, and indicates that wGetCommand should be called.

Type 18: WM_TASK_KEY

Series 3 only.

Offset Length Description
0 2 type, set to 18
2 2 connection handle
4 2 tick count
6 2 application key code @@@
8 2 modifiers ? @@@
10 2 repeat count ? @@@

@@@@

Type 19: WM_TASK_UPDATE v3.5

Offset Length Description
0 2 type, set to 19

Sent to the shell process if any process terminates, whether or not a client of the window server.

Type 20: WM_ON v3.5

Offset Length Description
0 2 type, set to 20

Sent to a client when the machine is switched on and the client has either called wInformOnAll, or has called wInformOn and is in the foreground.

Type 21: WM_ESCAPE

Offset Length Description
0 2 type, set to 21

@@@@

Sent on if key events are not selected using wGetEventSpecial. The event is sent when the ESC key is pressed; all pending keystrokes are thrown away.

Type 22: WM_DATE_CHANGED v4

Offset Length Description
0 2 type, set to 22

Sent to any client which is not in Series 3t compatibility mode and is in the foreground, whenever either the date changes, or the machine is switched on on a different date to when it was switched off.

System calls

Function 0x8D

Sub-function 0x00: wEndRedraw

Ends redrawing, as started by wBeginRedrawWin or related calls.

Sub-function 0x01: wEraseTextCursor

Makes the text cursor invisible.

Sub-function 0x02: wReleaseMouse

Cancels any call to wCaptureMouse.

Sub-function 0x03: gFreeTempGC

Destroys the temporary graphics context, and makes the remembered current graphics context be current again.

Sub-function 0x04: wCancel

@@@

Sub-function 0x85: wDisconnect

@@@

Sub-function 0x06: wDetachClient

Detaches the client from any process it is attached to (see wAttachToClient) and moves it to the back.

Sub-function 0x07: wCleanUp

Returns the window server to a standard state. This frees any temporary graphics context, ends any redraws taking place, and invalidates any window that has an attached graphics context.

Sub-function 0x08: wAttachToForegroundClient

Attaches the client to the current foreground client, if different. See wAttachToClient for details.

Sub-function 0x09: wUserMsg

Instructs the window server to send the client a WM_USER_MSG event when there are no other events to deliver. Only one such event can be pending for a client.

Sub-function 0x8A: wStartCompute

Inform the window server that the client is about to start intensive computation, and its priority should be set to 112 (background) even if it is in the foreground. Ignored if the client has not selected server-controlled priority handling (see wSetPriorityControl).

Sub-function 0x8B: wEndCompute

Cancel the effect of wStartCompute; if the client is in the foreground,  sets its priority back to 128 (foreground). Ignored if the client has not selected server-controlled priority handling.

Sub-function 0x8C: wClientInfo fails

Register Description
BX ID of process to be checked

Output: AX: -> information about the process

Returns information about a process:

Bit 0: set if the process is connected the window server
Bit 1: returns the setting specified at connection time
Bit 2: the client is system modal
Bit 7: server-controlled priority handing is active

If the process is not a client of the window server, the call may return zero or may fail.

Sub-function 0x0D: wCloseWindowTree

Register Description
BX Window ID

Destroys the window and all its descendants.

Sub-function 0x8E: wInquireWindow

Register Description
BX Window ID
SI Address of 14 byte information block (see wCreateWindow)

The first 10 bytes of the block are set to the flags, position, and size of the specified window. The last 4 bytes of the block are set to unspecified values.

Sub-function 0x0F: wCaptureMouse

Register Description
BX Window ID

Captures the mouse within the window and its descendants. It will cancel any active capture in another window.

Sub-function 0x10:wBeginRedrawWin

Register Description
BX Window ID

Validate the window for redrawing. Validation causes all pixels to be set or cleared if the background mode is 1 or 2 (this applies to black and grey separately), and all future drawing is clipped to the update region (which is set to the entire window in this case). Normal drawing resumes when wEndRedraw is called.

Sub-function 0x11: wFree

Register Description
BX Identifier

Destroy an object and free all the related resources. The identifier can be any of:

  • bitmap file handle
  • bitmap identifier (will also destroy any associated graphics context)
  • bitmap sequence identifier
  • clock identifier
  • font identifier
  • graphics context
  • mouse icon identifier
  • sprite identifier

Sub-function 0x12: wMakeInvisible

Register Description
BX Window ID

The window is marked as invisible; a window will not appear on the screen if it or any of its ancestors is invisible.

Sub-function 0x93: wAttachtoClient fails

Register Description
BX ID of process to attach to

Attaches the current process to the specified one. This will cause its windows to stay just in front of those of the client it is attached to. Applies only on large screen servers.

Sub-function 0x14: wInitialiseWindowTree

Register Description
BX Window ID

The specified window and its descendants are initialized. This may only be done once for any given window, and must be done before it is first drawn on.

Sub-function 0x15: wInvalidateWin

Register Description
BX Window ID

Add the entire window to its own update region. This will cause a redraw event, which can be used to trigger redrawing of the window.

Sub-function 0x16: wValidateWin

Register Description
BX Window ID

Validate the window (causing all pixels to be set or cleared if the background mode is 1 or 2 - this applies to black and grey separately), and the update region is deleted.

Sub-function 0x17: wMakeVisible

Register Description
BX Window ID

Cancels wMakeInvisible on the window.

Sub-function 0x18: wClientIconised

Register Description
BX action (0 = deiconise, 1 = iconise)

Iconises or deiconises the current process. Iconisation only works on large screen systems.

Sub-function 0x19: wClientPosition

Register Description
BX Position
CX Process ID

Move the specified process (zero means the current process) to the given position in the window server task list. Position 0 is the front of the list; any position greater than or equal to the number of processes attached to the window server puts the process at the very back of the list.

Sub-function 0x9A: wInquireWindowOffset fails

Register Description
BX ID of window A (0 = screen)
CX ID of window B
SI address of a 4 byte buffer

The buffer is filled in with the position of window B relative to window A:

Offset 0 (word): x offset

Offset 2 (word): y offset

Sub-function 0x1B: wWindowPosition

Register Description
BX Window ID
CX position (0 = front)

Moves the window to the specified position within the sibling list (the list of windows with the same parent).

Sub-function 0x1C: wScrollRect

Register Description
BX Window ID
CX address of a standard rectangle structure
DX address of offset structure

The pixels defined by the rectangle are copied to a new rectangle offset by the indicated distance. The offset structure is:

Offset 0 (word): x offset of new rectangle
Offset 2 (word): y offset of new rectangle

Copying does not go outside the window, and does not appear in areas obscured by other windows or in "invalid" areas waiting for update.

Sub-function 0x1D: wRubberBand

Register Description
BX ID of window to be sent the WM_RUBBER event
CX ID of window limiting the rubber band (0 = whole screen)
DX address of an information block

Starts rubber banding, with the rubber band limited to the specified window or allowed to roam over the screen. When the user completes the rubber banding, a WM_RUBBER event is sent to the window given. The information block is:

Offset 0 to 7: standard rectangle structure giving the initial rectangle
Offset 8 to 15: standard rectangle structure giving the inner bounds
Offset 16 to 23: standard rectangle structure giving the outer bounds
Offset 24 (word): flags
Offset 26 (word): minimum width
Offset 28 (word): minimum height
Offset 30 (word): maximum width
Offset 32 (word): maximum height
Offset 34 (word): x grid snap value
Offset 36 (word): y grid snap value

@@@@@@@@

A window can be set so that pressing a mouse button starts rubber banding. In this case, the press event is sent as a WM_RUBBER_BAND_INIT event instead. The client must call wRubberBand (use the @@@@@@ flag to cancel rubber banding if necessary).

Sub-function 0x1E: gCopyRect cgc

Register Description
BX Standard rectangle structure
CX address of point definition block
DX mode (see gFillPattern)

Copies a rectangular block from one part of a bitmap to another (the current graphics context should refer to a bitmap). The top left corner of the rectangle is copied to the point given by the definition block:

Offset 0 (word): x
Offset 2 (word): y

Sub-function 0x9F: gPeekBit

Register Description
BX Window ID
CX address of point definition block
DX number of pixels
SI address of buffer

Copies a horizontal row of pixels into the buffer. The point definition block gives the first pixel to be copied:

Offset 0 (word): x

Offset 2 (word): y

The pixels are packed 8 per byte of the buffer, in LSB-first order ?@@@@@@
In version 4, the grey plane can be used by setting bit 15 of BX.

Sub-function 0x20: gDrawPolyLine cgc

Register Description
BX x coordinate of start point
CX y coordinate of start point
DX address of poly-line control block

Draws a sequence of lines according to the control block, which has the format:

Offset 0 (word): number of line segments (N)
Offsets 2 to 5: line segment 1 control block
Offsets 6 to 9: line segment 2 control block
...
where the block is 4N+2 bytes long. The control block for segment M has the format:


Offset 4M-2 (word): 2 times x offset, plus 0 for draw or 1 for don't draw
Offset 4M (word): y offset

Each control block causes a line to be drawn, or not drawn, from the previous end point (or the start point, for the first control block) to a new point specified as a relative offset. In version 2 of the window server there is a limit of 61 control blocks.

Sub-function 0x21: gFillPattern cgc

Register Description
BX standard rectangle structure
CX bitmap (0x4000 = chequered 1 and 0 pixels)
DX mode

Fills the specified rectangle with copies of the bitmap. The mode can be:

0 = set each pixel where the bitmap has a 1 pixel
1 = clear each pixel where the bitmap has a 1 pixel
2 = invert each pixel where the bitmap has a 1 pixel
4 = copy the bitmap to the rectangle

In version 3 and above, CX can also be a window with black plane redraw method 3, indicating that the backup bitmap of that window is to be used. In version 4, if both planes have redraw method 3, the appropriate plane is used for each selected plane in the target window or bitmap.

Sub-function 0x22: gCreateTempGC

Register Description
BX Window or bitmap
CX GC selector mask
DX GC description block

Creates a new temporary graphics context associated with the window or bitmap, and makes it the current GC. The previous current GC is remembered. While a temporary graphics context exists, the following calls are forbidden:

gCreateGC
gCreateTempGC
gSetGC (unless modifying the temporary graphics context)
wBeginRedrawGC
wBeginRedrawWinGC
wFree for any graphics context

Sub-function 0xA3: gCreateGC fails

Register Description
BX Window ID or bitmap
CX GC selector mask
DX GC description block

Output: AX: -> graphics context identifier

Creates a new graphics context associated with the window or bitmap, and makes it the current GC.

Sub-function 0x24: gSetGC

Register Description
BX graphics context (for v3 and above, 0=current GC)
CX GC selector mask
DX GC description block

Makes the specified graphics context current, and modifies those properties specified in the selector mask.

Sub-function 0x25: wSetWindow

Register Description
BX window to change
CX flags
DX address of a block of information about the window

Changes various properties of a window. The flags are as follows:

Bits 2 to 6, 8, and 10: set the indicated property to the corresponding bit of the flags within the information block
Bit 12: if set, move and resize the window
Bit 13: if set, change the pointer symbol
Bit 14: if set, change the background method

New values are taken from the information block, which is as for wCreateWindow.

Sub-function 0x26: wBeginRedrawWinGC

Register Description
BX Window ID
CX Unknown
DX GC selector mask
DI address of a GC description block

Validate the window for redrawing (see wBeginRedrawWin) but using a temporary graphics context which will be destroyed by wEndRedraw.

Sub-function 0x27: gDrawLine cgc

Register Description
BX x coordinate of first end
CX y coordinate of first end
DX x coordinate of second end
DI y coordinate of second end

Draws a line between the two locations. If horizontal or vertical, the line includes the end with the lower coordinates. If diagonal, the line includes all pixels intersected by the diagonal of a rectangle including the top and left edges but not the bottom and right edges. Note that, in all cases, the order of the two ends does not affect the line drawn.

Sub-function 0x28: gPrintText cgc

Register Description
BX x coordinate of starting point
CX y coordinate of baseline
DX (text) string
DI length of string (maximum 246)

Prints the string at the indicated location. Characters not found in the font will be treated as if they were the highest character code.

Sub-function 0x29: gCopyBit cgc

Register Description
BX address of point definition block
CX bitmap identifier or window identifier
DX standard rectangle structure
DI mode (see gFillPattern)

Copies a rectangular block from a bitmap or a backed-up window (see gSaveBit). The top left corner of the rectangle is copied to the point given by the definition block:

Offset 0 (word): x
Offset 2 (word): y

The function cannot copy from a bitmap to itself. If the destination is in grey plane mode, the grey plane of the source is used if there is one. If the destination is in both planes mode, a single plane source is copied to both planes, and a double plane source has each plane copied to the corresponding plane.

Sub-function 0xAA: wCreateWindow fails

Register Description
BX parent window (0 = parent is the entire screen)
CX flags
DX address of a block of information about the window
DI handle for the new window (must not be zero)

Output: AX: -> new window identifier

Creates a new window which is a child of the specified window, and gives it the indicated id and handle (note that the two are not the same, and the former is used in other calls except where explicitly stated otherwise). The window cannot be drawn to until wInitialiseWindowTree has initialised it. The flags are:

Bits 0 to 11: if set, use the corresponding bit from the flags word of the information block; if clear, bits 1, 2, 7, 8, and 9 are
cleared, the remainder are inherited from the parent window.

Bit 12: set = use coordinates and size, clear = covers entire parent
Bit 13: set = use pointer symbol in information block, clear = use parent's
Bit 14: set = new background method, clear = same method as parent

The information block contains the following:

Offset 0 (word): flags
Bit 0: this window is input-only (and therefore invisible)
Bit 1: pressing a mouse button starts rubber-banding (see wRubberBand)
Bit 2: ignore the mouse when it is within this window
Bit 3: send mouse events when the mouse button is up
Bit 4: send mouse events when the mouse button is down
Bit 5: grab the mouse when its button is pressed
Bit 6: draw in double pixel mode (v4 only)
Bit 7: visible only when client is in foreground (large screen only)
Bit 8: send redraw events to windows with this bit set bfore those with it clear
Bit 9: do not send redraw events
Bit 10: activate the window if it receives a mouse click
Bit 11: rubber banding will terminate when the mouse button is released

Offset 2 (word): x coordinate within parent
Offset 4 (word): y coordinate within parent
Offset 6 (word): width
Offset 8 (word): height
Offset 10 (word): identifier of the pointer symbol, where relevant
Offset 12 (byte): background redraw method

Bits 0 and 1: black plane method (0 = do nothing, 1 = set pixels,
2 = clear pixels, 3 = keep an off-screen bitmap)
Bit 3: if set, attempts to draw on the black plane are ignored (v4 only)
Bits 4 and 5: grey plane method (0 = do nothing, 1 = set pixels,
2 = clear pixels, 3 = keep an off-screen bitmap)
Bit 7: if clear, attempts to draw on the grey plane are ignored

The choice of keeping an off-screen bitmap cannot be changed after the window has been created, while the other options can be changed using wSetWindow.

Sub-function 0x2B: wBeginRedrawGC

Register Description
BX window
CX address of a standard rectangle structure
DX graphics context fields to be set
DI address of a graphics context information block

Validate the window for redrawing (see wBeginRedrawWin) with the update region set to the indicated rectangle and using a temporary graphics context which will be destroyed by wEndRedraw (see wBeginRedrawWinGC).

Sub-function 0xAC: gPrintClipText cgc

Register Description
BX x coordinate of starting point
CX y coordinate of baseline
DX (text) string
DI length of string (maximum 244)
SI maximum number of pixels

Output: AX: -> number of characters printed

Prints the string at the indicated location as gPrintText, but only enough characters are printed to fit within the specified number of pixels.

Sub-function 0x2D: gPrintBoxText cgc

Register Description
BX address of a standard rectangle structure
SI distance from top of rectangle to baseline
AX alignment (1=right, 2=left, 4=centre)
CX margin
DX (text) string
DI length of string (maximum 236)

Clears the specified rectangle, then prints the string within it using text mode 0 (set pixels). The text is clipped to fit within the rectangle. The string is printed in the part of the rectangle excluding a margin area, whose position depends on the alignment:
left or right: CX must be >= 0, margin is on the same side, width is CX centre and CX >= 0: margin is on the left, width is CX centre and CX < 0: margin is on the right, width is -CX

Sub-function 0xAE: gOpenBit fails

Register Description
BX (cstr) filename
CX bitmap number (0 = first or only)
DX flags
SI address of an information block

Output: AX: -> bitmap identifier

Loads a specified bitmap from a file. The flags are:

Bit 0: set for a writeable bitmap, clear for a shared read-only bitmap
Bit 1: place the bitmap in a separate memory segment
Bit 2: write the segment name in the information block
Bit 3: must be clear

The information block is written to as follows:

Offset 0 (word): set to the width of the bitmap
Offset 2 (word): set to the height of the bitmap
Offset 4 to 17: set to the segment name (cstr), only if flag bit 2 is set

Sub-function 0xAF: gOpenMouseIcon fails

Register Description
BX (cstr) file name
CX number of icon within file

Output: AX: -> mouse icon identifier

Loads a specified mouse icon from a file.

Sub-function 0xB0: gOpenFont fails

Register Description
BX (cstr) filename

Output: AX: -> font identifier

Opens the specified font file.

Sub-function 0x31: gDrawBox cgc

Register Description
BX address of a standard rectangle structure

Draws a box of the appropriate size. Note that a box with width and height of 3 will have exactly one empty pixel inside it.

Sub-function 0xB2: wLoadDYL fails

Register Description
BX (cstr) DYL segment name

Output: AX: -> DYL identifier

Load a DYL into the window server. The DYL must already have been loaded into memory with @@@@@@@

More information needed.

Sub-function 0xB3: gCreateBit fails

Register Description
@@ flags
@@ address of an information block

Output: AX: -> bitmap identifier

Creates an uninitialized writeable bitmap. The flags are:

Bit 0: must be clear
Bit 1: place the bitmap in a separate memory segment
Bit 2: write the segment name in the information block
Bit 3: make the bitmap zero-sized

If the bitmap is zero-sized, nothing can be written to it; the size can be increased later. The information block is:

Offset 0 (word): width
Offset 2 (word): height
Offset 4 to 17: set to the segment name (cstr), only if flag bit 2 is set

Sub-function 0x34: wScrollWin

Register Description
BX window or bitmap
CX address of offset structure

Identical to wScrollRect with the rectangle structure set to (0, 0, width, height).

Sub-function 0x35: wDrawTextCursor

Register Description
BX window
CX address of text cursor information

As wTextCursor, but the properties byte is ignored and treated as zero.

Sub-function 0x36: wInvalidateRect

Register Description
BX window
CX address of a standard rectangle structure

Add the rectangle to the update region of the window. This will generate a redraw event if necessary.

Sub-function 0x37: wBeginRedraw

Register Description
BX window
CX address of a standard rectangle structure

Validate the window for redrawing (see wBeginRedrawWin) with the update region set to the rectangle.

Sub-function 0x38: wValidateRect

Register Description
BX window
CX address of a standard rectangle structure

Validate the indicated rectangle of the window (causing all pixels to be set or cleared if the background mode is 1 or 2 - this applies to black and grey separately), and remove that rectangle from the update region of the window.

Sub-function 0xB9: gSaveBit fails

Register Description
BX (cstr) filename
CX bitmap identifier, window identifier, or zero

Writes a bitmap to the named file. A window identifier must be for a window with a background redraw method of 3, in which case its off-screen bitmap is used. Zero for the bitmap causes the entire screen to be saved. If the window off-screen bitmap, or the screen, has a grey plane then a double-plane bitmap is written.

Sub-function 0x3A: gClrRect cgc

Register Description
BX standard rectangle structure
CX 0=set, 1=clear, 2=invert

Sets, clears, or inverts all pixels in the specified rectangle.

Sub-function 0x3B: wCallDYL

Register Description
BX DYL identifier
CX function number
DX number of bytes of data to be passed
DI address of data to be passed

Call a function in a DYL loaded into the window server that has no result.

Sub-function 0xBC: wCallDYLreply fails

Register Description
BX dyl identifier
CX function number
DX number of bytes of data to be passed
DI address of data to be passed
SI address of area to store a result in

Output: AX: -> result

Call a function in a DYL loaded into the window server that has a result. The main result is returned in AX (a negative value is a failure), and other data (depending on the function) may be written into the area pointed to by SI.

Sub-function 0xBD: wSetWinBitmap fails

Register Description
BX window
CX number of bitmaps (1 to 12)
DX address of a sequence of information blocks

Output: AX: -> sequence identifier

Attaches an animated sequence of bitmaps to the background of a window. Each time the background changes the client will be sent a redraw event unless an appropriate background mode has been selected. There must be an information block for each bitmap in the sequence; the blocks are immediately adjacent in memory. Each block has the form:

Offset 0 (word): bitmap identifier
Offset 2 (word): x coordinate of location in the window to display bitmap
Offset 4 (word): y coordinate of location in the window to display bitmap
Offsets 6 to 13: standard rectangle structure giving the part of the bitmap to be displayed
Offset 14 (byte): graphics mode used to copy bitmap (0=set, 1=clear, 2=invert, 4=copy with background)
Offset 15 (byte): plane to write to (0=white, 128=grey) (v4 only)
Offset 16 (long): delay in 0.1 seconds before next bitmap is shown

Sub-function 0x3E: wChangeWinBitmap

Register Description
BX bitmap sequence identifier
CX position of bitmap (0 to 11)
DX address of an information block

Replace the appropriate bitmap in a sequence (see wSetWinBitmap) with the new information in the block.

Sub-function 0xBF: wEscapeon

More information needed.

Sub-function 0x40

More information needed.

@@@ RConnect

Sub-function 0xC1: wEscapeoff

More information needed.

Sub-function 0xC2: wGetWindowPosition v3

@@@@ ???? [ was = GetPosition] fails

Register Description
BX window

Output: AX: -> position

Returns the position of the window in its sibling list (the windows with the same parent). Has the side effects of wCheckPoint.

Sub-function 0xC3: gSaveRect fails

Register Description
BX (cstr) filename
CX bitmap identifier, window identifier, or zero
DX standard rectangle structure

Saves a rectangle from a bitmap, backed-up window, or the screen (see gSaveBit for details).

Sub-function 0x44: wReassignRootWindow v3

Register Description
BX window (0 = screen)

All future calls within this client will treat the specified window as it it were the whole screen (e.g. this window will be the parent for those whose parent is specified as 0).

Sub-function 0xC5: wCaptureKey v3 fails

Register Description
BX keycode
CX modifier state
DX modifier mask

Captures certain key combinations; from now on, these key presses will be sent to this client whether or not it is in the foreground. The key combinations captured are those that will generate the specified keycode, and for which those modifiers given in DX have the value given in CX (all other bits in CX must be clear). For example, to only depend on the settings of shift and control:

Shift Control CX DX
Up Up 0 6
Up Down 4 6
Up Either 0 2
Down Up 2 6
Down Down 6 6
Down Either 2 2
Either Up 0 4
Either Down 4 4
Either Either 0 0

(if CX is not 0, nothing is captured)

However, it should be borne in mind that most modifier combinations affect the keycode as well. The call fails if the same combination is already captured; if two different combinations capture the same key, the client that made the earlier request receives the event.

Sub-function 0xC6: wCancelCaptureKey v3 fails

Register Description
BX keycode
CX modifier state
DX modifier mask

Cancels a call to wCaptureKey with identical arguments. The call fails if the client has not captured this combination.

Sub-function 0x47: wSystemModal v3

Register Description
BX position in task list (0 = front)

Makes the current client system modal and sets its position in the task list. Task switching only applies to clients that are in front of the frontmost system modal task.

Sub-function 0x48: wCancelSystemModal v3

Register Description
BX position in task list (0 = front)

Cancels a call to wSystemModal and re-positions the client.

Sub-function 0x49: gBorder v3 cgc

Register Description
BX border type

Draws a border just inside the window or bitmap of the current graphics context. The border type is:

Bit 0: if set, draw the border 1 pixel from the edge
Bit 1: set for 4 pixel corner, clear for 1 or 2 pixel corner
Bits 2 to 4: allowance for shadow

0 = no shadow
1 = remove (but leave space for) single width shadow
2 = remove (but leave space for) double width shadow
5 = draw single width shadow
6 = draw double width shadow

Bit 5: set for special top-of-menu border
Bit 6: set for 1 pixel corner, clear for 2 or 4 pixel corner
Bit 7: remove any arrow at top right, and repair the border
Bit 8: remove any arrow at bottom right, and repair the border
Bit 9: include an arrow at top right
Bit 10: include an arrow at bottom right

Sub-function 0x4A: gBorderRect v3 cgc

Register Description
BX standard rectangle structure
CX border type

Draws a border just inside the indicated rectangle. The border type is as for gBorder.

Sub-function 0x4B: gXPrintText v3 cgc

BX: x coordinate of starting point
CX: y coordinate of baseline
DX: (text) string
DI: length of string (maximum 244)
SI: embellishments

Prints the text, as gPrintText in mode 4 (copy with background), but with embellishments:

0 = none
1 = inverted
2 = inverted except the four corners
4 = underlined
8 = inverted and no descenders
9 = inverted except the four corners, and no descenders
12 = underlined and no descenders

Embellishments with "no descenders" stop on the row below the baseline, on the assumption that no characters in the string descend below that point.

Sub-function 0x4C: gInvObloid v3 cgc

BX: address of information block

Inverts all the pixels, except the four corner pixels, of the rectangle specified by the block:

Offset 0 (word): left edge
Offset 2 (word): top edge
Offset 4 (word): width
Offset 6 (word): height

Sub-function 0x4D: wEnablePauseKey v3

Allows the program to be paused by the user by pressing CTRL-S; this is initially turned on. When paused, the window server will not process any requests from the client (they will be held until the pause is released by pressing any key).

Sub-function 0xCE: wDisablePauseKey v3

Disallow the program from being paused by the use of CTRL-S.

Sub-function 0x4F: wsEnable

Turns on the permanent status window. This lies behind any other windows of this client and so, to be seen, all overlaying windows must be resized or moved.

Sub-function 0x50: wsDisable

Turns off the permanent status window.

Sub-function 0x51: wInformOn v3.5

Instructs the window server to send WM_ON events when the client is in the foreground.

Sub-function 0x52: wsUpdate

BX: reason (1 = name, 2 = time)

Updates the contents of the status window to reflect a change elsewhere. A reason of "name" means that the process name has changed; a reason of "time" indicates that the clock format has changed.

Sub-function 0xD3: wsCreateClock fails

AX: -> clock identifier
BX: window
CX: flags
DX: x coordinate
SI: difference in minutes between clock and system time @@@
DI: y coordinate

Creates a clock. See wsCreateClock2, which includes all the functionality of this call together with additional features.

Sub-function 0x54: wsSetClock

BX: clock identifier
CX: difference in minutes between clock and system time

Changes the difference between clock and system time for a clock.

Sub-function 0xD5: wSetBusyMsg

eBX: (cstr) text to be displayed
CX: location and delay:

Bits 0-5: delay in half seconds before displaying
Bit 6: 0 = top, 1 = bottom
Bit 7: 0 = left, 1 = right

Waits for the required time (during which another call can cancel the previous request) and then displays the text, flashing, in the indicated corner; the text remains until replaced or cancelled (by an empty string). Equivalent to the BUSY keyword. The text is limited to 20 characters.

Sub-function 0x56: wsDisableTemp

Disable the display of a temporary status window via the PSION-MENU keypress. This is a system-wide setting and is initially on.

Sub-function 0x57: wsEnableTemp

Enable the display of a temporary status window via the PSION-MENU keypress. This is a system-wide setting and is initially on.

Sub-function 0xD8: wSystem

BX: settings to be changed
CX: new values for settings

Changes settings within the window server (thus affecting all clients). For each bit that is set in BX, the property is set to the corresponding bit in CX. The meanings of the bits are:

Bit @: do not restart the shell (SYS$SHLL) when the window server terminates
Bit @: do not restart the notifier (SYS$NTFY) when the window server terminates (v4 only)
Bit @: attempt to become the notifier process [H4]
Bit @: if the window server is also the notifier, do not report processes which terminate abnormally
Bit @: send task update events to the shell when any process terminates [H4]
Bit @: test battery and display low battery warnings if necessary each time the machine is switched on [H4]
Bit @: report clients that are failing to respond to events [H4]
Bit @: disable low battery indicator in the status window [v4]
Bit @: disable SSD indicators in the status window [v4]
Bit @: disable link indicator in the status window [v4]
Bit @: disable caps lock indicator in the status window [v4]

Those bits marked [H4] apply only to HC machines and version 4 of the server; Series 3t machines will act as if the bit is always set.

Those marked [v4] apply only in version 4. The initial values of all settings are taken from the $WS_FL environment variable.

Sub-function 0xD9: wGetProcessList v3.5

SI: address of a 44 byte buffer

The buffer is filled with a list of all the processes connected to the window server; the list is in front-to-back order, and is terminated by a zero word.

Sub-function 0xDA: wSendCommand v3.5 fails

BX: process
CX: address of the first byte of the data
DX: number of bytes of data (1 to 127)

Sends command data to the specified process. The process will receive a WM_COMMAND event, and should then call wGetCommand.

Sub-function 0xDB: wGetCommand v3.5 fails

SI: address of a 127 byte buffer

Reads the last command data sent by wSendCommand into the buffer. Only one pending command is held.

Sub-function 0x5C: wTextCursor

BX: window
CX: address of text cursor information

Make the text cursor visible if it is not, and move it to the window and location given. The information is:

Offset 0 (word): x coordinate of baseline
Offset 2 (word): y coordinate of left edge
Offset 4 (byte): height of cursor
Offset 5 (byte): distance from baseline to top of cursor
Offset 6 (byte): width
Offset 7 (byte): properties (v4 only)

Bit 0: clear=rectangle, set=rounded
Bit 1: clear=flashing, set=steady
Bit 2: clear=black, set=grey

The distance from baseline to cursor top is 2's complement signed. That is, 0 means the top is the baseline, 1 means it is the pixel above, 255 means the pixel below, and so on.

Sub-function 0xDD: wAppKeyHandler

@@@

Sub-function 0xDE: wInfoMsgCorner

eBX: (cstr) text to be displayed
CX: location:

Bit 6: 0 = top, 1 = bottom
Bit 7: 0 = left, 1 = right

Displays the text in the indicated corner for 2 to 2.5 seconds; an empty string clears any existing text. Equivalent to the GIPRINT keyword. The text is limited to 64 characters.

Sub-function 0x5F:gSetOpenAddress

BX: 0=cancel, 1=direct, 2=indirect long, 3=indirect word
CX: file offset low word ??? it's declared as ULONG
DX: file offset high word ??? it's declared as ULONG

Modifies the next call to any of:

gInitBit
gOpenBit
gOpenFont
gOpenFontIndex
gOpenMouseIcon

to change the place within the file that reading starts; this is used where the font, bitmap, or icon file is embedded in another file. The meaning of BX is:

0: equivalent to BX=1, CX=0, DX=0
1: DX/CX is the starting position within the file
2: DX/CX is the position within the file of a long giving the start point
3: DX/CX is the position within the file of a word giving the start point

Sub-function 0x60: wDrawButton cgc

BX: standard rectangle structure
CX: (cstr) string in button (maximum length 240)
DX: button state (0 = normal, 1 = pressed)
Draws a button containing a string.

Sub-function 0xE1: wSetTaskKey v3.5 fails

BX: keycode
CX: modifier state
DX: modifier mask

Causes the relevant keypresses (see wCaptureKey) to be treated as the "task key". The task key causes the current foreground task to be moved to the back of the list. There can be any number of task keys. On the HC and MC, the TASK key is preassigned as a task key; on the Series 3 SHIFT-SYSTEM is assigned by the shell process.

Sub-function 0xE2: wSetBackTaskKey v3.5 fails

BX: keycode
CX: modifiers
DX: modifier mask

Identical to wSetTaskKey, except that it sets a "reverse task key" which brings the rearmost process to the foreground. On the Series 3 SHIFT-PSION-SYSTEM is preassigned as the reverse task key.

Sub-function 0xE3: wCancelTaskKey v3.5 fails

BX: keycode
CX: modifiers
DX: modifier mask

Cancels a previous call to wSetTaskKey with the same arguments.

Sub-function 0xE4: wCancelBackTaskKey v3.5 fails

BX: keycode
CX: modifiers
DX: modifier mask

Cancels a previous call to wSetBackTaskKey with the same arguments.

Sub-function 0xE5

@@@ SwExt

Sub-function 0xE6: gOpenFontIndex v4 fails

AX: -> font identifier
@@: (cstr) filename
@@: font number within file (0 = first or only font)

Opens the specified font from a multiple-font file.

Sub-function 0xE7: gInitBit v4 fails

AX: -> bitmap file handle
@@: (cstr) filename
@@: address of a word

Opens a file containing one or more bitmaps, ready for gGetBit and gDrawBit. The word pointed to by @@ is set to the number of bitmaps in the file. Using this facility is more efficient than using gOpenBit several times.

Sub-function 0xE8: gGetBit v4 fails

@@: bitmap file handle
@@: bitmap number (0 = first or only)
@@: flags
@@: address of an information block

Loads a bitmap from the file given by the handle (which must have been returned by gInitBit). The other parameters are as for gOpenBit.

@@@@ Manual says returns 0. gOpenBit returns a bitmap identifier!


Sub-function 0xE9: gDrawBit v4 fails cgc

@@: address of point definition block
@@: bitmap file handle
@@: standard rectangle structure
@@: mode (see gFillPattern)
@@: bitmap number (0 = first or only)

Copies a rectangle from a bitmap in a file to the window or bitmap given by the current graphics context. Effectively does gGetBit, gCopyBit, and then wFree on the bitmap, only much more efficiently.


Sub-function 0xEA: gQueryBit v4 fails

@@: bitmap file handle
@@: bitmap number (0 = first or only)
@@: address of 4 byte buffer

The buffer is filled with the size of the specified bitmap:

Offset 0: width
Offset 2: height

Sub-function 0x6B: wsStatusWindow v4

BX: window format (0 = off, 1 = small, 2 = large, 3 = Series 3t)

Sets the format of the status window.

Sub-function 0x6C: wInformOnAll v4

@@: new state (0 = don't send, 1 = send)

Instructs the window server to send or not send WM_ON events.

Sub-function 0xED: wsCreateClock2 v4 fails

AX: -> clock identifier
BX: address of clock information
CX: (cstr) clock format for type 5 clocks, must be 0 for all others

Creates a clock, which will then tick automatically. The clock information has the following form:

Offset 0 (word): window
Offset 2 (word): clock type

0 = Series 3t small digital
1 = Series 3t medium variable (36 x 32 pixels)
2 = Series 3t large analogue (66 x 60 pixels)
3 = Series 3a medium variable (58 x 51 pixels)
4 = Series 3a large analogue (99 x 99 pixels)
5 = Formatted digital (v4 only)
6 = Series 3c/Siena medium variable
7 = Series 3c large analogue

Offset 4 (word): x coordinate of position
Offset 6 (word): y coordinate of position
Offset 8 (word): difference in minutes between clock and system time
Offset 10 (word): flags [apply only to the types in brackets]

Bit 4: display the date [0, 1, 3]
Bit 5: display seconds [0, 2, 3 (analogue), 4]
Bit 6: force analogue [1, 3]
Bit 7: force digital [1, 3]
Bit 8: add AM/PM indicator if system is in 12 hour mode [0, 1]
Bit 9: centre text within space added when bit 8 set [0]
Bit 10: add AM/PM indicator if system is in 12 hour mode [0, 1 (digital)]
Bit 10: @@@ CLOCK_WITH_DATE_EXTRA
Bit 11: use grey plane [0, 1, 2, 5?]
Bit 12: @@@ DBL_PLANE
Bit 13: right align [@@@]
Bit 14: @@@ SUMMER_TIME
Bit 15: enclose in a box [5]

Offset 12 (word): font (type 5 only)
Offset 14 (word): style (type 5 only)

Bit 0: bold
Bit 1: underline
Bit 2: inverse
Bit 3: double height
Bit 4: monospaced

Clock types described as "variable" can be either digital or analogue according to the system settings or additional bits. For type 5 clocks, the format string @@@

Sub-function 0xEE: wSetPriorityControl v4

BX: new state (0 = off, 1 = on)

Sets server-controlled priority handling. When on, the server will change the
priority of a process to 112 when it is in the background or has called
wStartCompute, and 128 when in the foreground. The client must not set its
own priority when this is on.

Sub-function 0xEF: gConfigureFonts v4 fails

AX: -> font group identifier
@@: number of fonts
@@: address of a sequence of information blocks

Creates a font group, which is a set of fonts intended for use in various styles (for example, roman, bold, italic, and bold-italic versions of a basic font would be combined to form a font group). There must be an information block for each font in the group; the blocks are immediately adjacent in memory. Each block has the form:

Offset 0 (word): font
Offset 2 (word): style of this font
Offset 4 (word): style to be applied to this font
Offset 6 (word): vertical adjustment

When using a font group and a style for output, the following process is used. The "best" block is set to the first block. The list of blocks is then scanned in order; whenever a block is found where all the styles in offset 2 are part of the required style and include all the styles in offset 2 of the best block, that block becomes the best block. When all blocks have been scanned, the font in offset 0 of the best block is selected, the styles in offset 2 are removed from those to be used, and then the styles in offset 4 are added. The resulting styles are applied to the font, and the text is moved vertically by the distance given in offset 6.

Sub-function 0xF0: wInquireStatusWindow v4

AX: -> current format (0 = off, 1 = small, 2 = large, 3 = Series 3t)
BX: format of interest (as for AX, or -1 for current format)
SI: address of 8 byte buffer

The buffer is filled in with the coordinates the status window would have if it had the indicated format; the current format is also returned.

The contents of the buffer are:

Offset 0 (word): x coordinate of left edge
Offset 2 (word): y coordinate of top edge
Offset 4 (word): width
Offset 6 (word): height

(When the window is off, it has zero width but full height, at the right hand edge of the screen.)

Sub-function 0xF1: wInquireCompatibility

AX: -> compatibility flag

Returns the state of the Compatibility mode. See wCompatibilityMode for details.


Sub-function 0xF2: gReadFontHeader v4 fails

AX: -> length of header actually read (up to 128)

@@: (cstr) filename
@@: font number within file (0 = first or only font)
@@: address of 128 byte buffer

The font header of the specified font is read into the buffer.

Sub-function 0xF3: gReadFontGroupHeader v4 fails

AX: -> length of header actually read (up to 126)

@@: (cstr) filename
@@: address of 128 byte buffer

The file must be a multiple font file. The number of fonts is placed in the word at offset 0 of the buffer, and the font group header is read into the rest of the buffer.

Sub-function 0xF4: wSetSystemFont v4 fails

@@: system font to be set
@@: font, font group, or internal font identifier
@@: text style (internal fonts only)

Changes the font in use for one of the four standard system fonts.

0 = Series 3a system font
1 = Series 3t compatibility system font
2 = Series 3a internal font
3 = Series 3t compatibility internal font

Sub-function 0xF5: wSetSprite v4 fails

@@: sprite identifier
@@: address of a position structure, or 0 to leave it in the same place
@@: number of bitmap set to change (0 = first set in the sequence)
@@: address of an information block, or 0 if all sets remain unchanged

Moves the sprite, or change a bitmap set, or both. The position structure and information block, if provided, have the same format as for wCreateSprite.


Sub-function 0xF6: wCreateSprite v4 fails

AX: -> sprite identifier

@@: window
@@: address of a position structure
@@: child window behaviour (0=sprite over windows, 1=sprite under windows)
@@: number of bitmap sets in the sprite
@@: address of a sequence of information blocks

Attaches an animated sequence of bitmap sets to a window as a sprite; the sprite will appear in front of everything else in the window. Only one window of a client may have a sprite at any time. The position structure gives the initial position of the sprite:

Offset 0 (word): x coordinate
Offset 2 (word): y coordinate

There must be an information block for each bitmap set in the sequence; the blocks are immediately adjacent in memory. Each block has the form:

Offset 0 (word): bitmap for black pixels to be set
Offset 2 (word): bitmap for black pixels to be cleared
Offset 4 (word): bitmap for black pixels to be inverted
Offset 6 (word): bitmap for grey pixels to be set
Offset 8 (word): bitmap for grey pixels to be cleared
Offset 10 (word): bitmap for grey pixels to be inverted
Offset 12 (word): x coordinate of bitmap position relative to the sprite
Offset 14 (word): y coordinate of bitmap position relative to the sprite
Offset 16 (long): delay in 0.1 seconds before next bitmap set is shown

Any of the bitmaps can be 0 to indicate that there is no such bitmap. All non-zero bitmaps must be the same size.

Sub-function 0xF7: wsSetList v4 fails

BX: number of strings in the new list (or -1 to show an icon)
eCX: an array of cstrs
DX: position in list to be selected (0 = first string, -1 = none)

Sets the "mode", or "diamond" list in the status window. CX should hold the address of an array of words, each of which holds the address of the start of a cstr. If BX is -1, the list is replaced by the application icon; in this case CX and DX are ignored.

Sub-function 0xF8: wsSelectList v4

BX: position in list to be selected (0 = first string, -1 = none)

Sets the position of the diamond in the status window.

Sub-function 0x79: gShadowText v4 cgc

@@: x coordinate of starting point
@@: y coordinate of baseline
@@: address of information block
@@: (text) string
@@: length of string (maximum 234)

Prints the text, ignoring the text mode, but applying shadow and lighting effects according to the information block:

Offset 0 (byte): body colour ) 0 = black, 1 = white
Offset 1 (byte): shadow colour ) 2 = grey, 3 = none
Offset 2 (byte): light colour ) 4 = dark grey, 5 = light grey
Offset 4 (word): link to shadow (0 = disconnected, 1 = connected)
Offset 6 (word): shadow effect width
Offset 8 (word): shadow effect height
Offset 10 (word): lighting effect width
Offset 12 (word): lighting effect height
Offset 14 (word): additional horizontal gap between characters

Sub-function 0x7A: gDrawObject v4 cgc

@@: object type
@@: standard rectangle structure
@@: flags

Draws a special object just inside the specified rectangle. Available object types are:

0 = 3-dimensional box

and the available flags are:

Bit 1: set for 4 pixel corner, clear for 1 or 2 pixel corner
Bit 3: double thickness
Bit 6: set for 1 pixel corner, clear for 2 or 4 pixel corner

Sub-function 0x7B: gBorder2 v4 cgc

@@: 0 = as gBorder, 1 = black/white/grey 3-D effect
@@: border type

Draws a border as gBorder, except that it can also generate a 3-D effect on screens with grey available. @@@ arrows are not documented as available

Sub-function 0x7C: gBorder2Rect v4 cgc

@@: 0 = as gBorderRect, 1 = black/white/grey 3-D effect
@@: standard rectangle structure
@@: border type

Draws a border as gBorderRect, except that it can also generate a 3-D effect on screens with grey available. @@@ arrows are not documented as available

Sub-function 0xFD: wCompatibilityMode

BX: new state (0 = off, 1 = on)
SI: *the same* pointer to a WSERV_SPEC structure as for wConnect @@@@

Changes the compatibility mode state. When the mode is off, drawing is done in the usual way. When it is on, drawing is done in double pixel mode on those machines that support it. The initial state is off.

Sub-function 0x7E AL 0x00: wDrawButton2 v4 cgc

@@: standard rectangle structure
@@: (cstr) string in button (maximum length 240)
@@: button type (0 = Series 3t, 1 = Series 3a)
@@: button state (0 = normal, 1 = pressed, 2 = deeply pressed)
Draws a button containing a string. Series 3a buttons require the window to have a grey plane. Series 3t buttons must not be deeply pressed.

Sub-function 0x7E AL 0x01

@@@ InformInactivity

Sub-function 0x7E AL 0x02: wDisableKeyClick v4

BX: 0 = enable, 1 = disable

Enables or disables key clicks for the current process.

Sub-function 0xFF AL 0x00: gInitMultiSave v4 fails

AX: -> multisave file handle

@@: (cstr) filename
@@: number of bitmaps

Creates a file capable of holding the specified number of bitmaps, for use with gSaveMultiBit and gSaveMultiRect.

Sub-function 0xFF AL 0x01: gSaveMultiBit v4 fails

@@: multisave file handle
@@: bitmap identifier, or zero for the whole screen

Saves the specified bitmap as the next bitmap in the multisave file created by gInitMultiSave. If the save fails, all further saves to the file will also fail (but the file must still be closed with gEndMultiSave).

Sub-function 0xFF AL 0x02: gSaveMultiRect v4 fails

@@: multisave file handle
@@: bitmap identifier, or zero for the whole screen
@@: address of a standard rectangle structure

Saves a rectangle from the specified bitmap as the next bitmap in the multisave file, as for gSaveMultiBit.

Sub-function 0xFF AL 0x03: gEndMultiSave v4 fails

@@: multisave file handle

Closes the multisave file, making it unavailable for further saves.

Sub-function 0xFF AL 0x04: gInquireChecksum v4

@@: bitmap identifier, window identifier, or zero
@@: address of a word

Checksums the specified bitmap and writes the checksum to the word pointed to by @@. A window identifier must be for a window with a background redraw method of 3, in which case its off-screen bitmap is used. Zero for the bitmap causes the entire screen to be checksumed.

Sub-function 0xFF AL 0x05: gCreateFontHeader

@@@@

Sub-function 0xFF AL 0x06: wSupportInfo v4

@@: address of a 32 byte buffer

The buffer is filled in with information about supported features:

Offset 0 (word): flags

Bit 0: set if grey is available
Bit 1: set if Series 3t compatibility mode is available

The remaining flag bits, and the rest of the buffer, is currently set to 0.

@@@@@@@@@

Sub-function 0x@@: wsScreenExt

@@: address of 8 byte buffer

The buffer is filled in with the size of the screen *excluding* the current status window. The format of the buffer is as for wInquireStatusWindow, which should be used for preference.

Function 0xD6

Sub-function 0x00: wConnect

Used to connect to the window server. All OPL programs, and all programs using the console device CON: are connected automatically and must not use this call.

Sub-function 0x01: gPlayback

@@: @@@@
@@@

Sub-function 0x02: gCloseMetafile

@@: @@@@
@@@

Sub-function 0x03: gRecordToMetafile

@@: @@@@
@@: @@@@
@@: @@@@
@@@

Sub-function 0x04: wFlush

Sends any buffered commands to the server.

Sub-function 0x05: wCloseDown

@@@

Sub-function 0x06: wSelect

@@: @@@@
@@@

Sub-function 0x07: wPanic

@@: @@@@
@@@

Sub-function 0x08: wGetEvent

@@: address of a 16 byte buffer
@@@@ This is async. How does the sync version work ? Is it vsync ?

This call may be made synchronously or asynchronously. If made synchronously, it waits until the window server sends an event to the process, and then copies the event into the buffer. If called asynchronously, it writes the value -46 into the word at offset 0 of the buffer and returns; when an event is sent from the window server, it is written to the buffer and the I/O semaphore is signalled. Further information about events is given below.

Sub-function 0x09: wDisconnect

Disconnects from the window server and frees all associated resources. All programs are automatically disconnected upon exit, so this call is generally not used by the programmer.

Sub-function 0x0A: wCheckPoint fails

Sends any buffered commands to the server (as wFlush) and reports any errors immediately (see wDisableLeaves).

Sub-function 0x0B: gTextWidth fails

AX: -> width in pixels
DX: font or font group
SI: style adjustments
DI: (text) string
CX: length of string

Returns the width in pixels of the specified string when displayed in the specified font and style adjustments. The latter are:

Bit 0: bold
Bit 1: underline
Bit 2: inverse
Bit 3: double height
Bit 4: monospaced
Bit 5: italic
Bit 8: subscript
Bit 9: superscript

Sub-function 0x0C: gFontInfo fails

DX: font or font group
CX: style adjustments (see gTextWidth)
DI: address of 32 byte buffer

Fills the buffer with information about the font modified by the style:

Offset 0 (word): minimum character code
Offset 2 (word): maximum character code
Offset 4 (word): height (affected by style)
Offset 6 (word): ascent (affected by style)
Offset 8 (word): descent (affected by style)
Offset 10 (word): width of a digit (affected by style)
Offset 12 (word): width of widest common character (affected by style)
Offset 14 (word): flags:

Bit 0: contains standard ASCII
Bit 1: contains IBM code page 850
Bit 2: looks bold
Bit 3: looks italic
Bit 4: has serifs
Bit 5: monospaced
Bit 6: has a "hang table" @@@@

Offset 16 to 31: name

The widest common character is usually an M or W, and is not necessarily the widest character in the font.

Sub-function 0x0D: wDisableLeaves

AX: -> previous value of the flag
@@: error handling flag

Sets the error handling mechanism used by the window server calls. If the flag is zero, then an error in a command calls the "leave" operation. If it is non-zero, calls that can fail return an error number in AX. The initial setting is zero; OPL programs should always make it non-zero.

Sub-function 0x0E: gCheckBitmapID v3 fails

@@: bitmap identifier

Succeeds (returning 0) if the bitmap identifier is valid. Fails otherwise.

Sub-function 0x0F

@@@ Alert

Sub-function 0x10

@@@ AlertCancel

Sub-function 0x11: gTextCount fails

AX: -> number of characters
DX: font or font group
SI: style adjustments (see gTextWidth)
DI: (text) string
CX: length of string
@@: address of a word holding the available width

AX is set to the length of the longest initial substring that will fit in the number of pixels stored in the word pointed to by @@ when displayed in the specified font and style adjustments (see gTextWidth). The word is altered to hold the number of pixels that would be left over.

Sub-function 0x12: gGetWidthTable fails

DX: font or font group
SI: style adjustments (see gTextWidth)
DI: address of a buffer

Fills the buffer with the widths of each character in the font as adjusted. The first byte of the buffer corresponds to the minimum character code, and the last byte to the maximum character code (see gFontInfo).

Sub-function 0x13: wGetEventSpecial v4

@@: address of a 16 byte buffer
@@: event type mask

Starts looking asynchronously for an event as wGetEvent, but only accepts events of specific types. @@@ what happens to the rest ? @@@ based on the event type mask:

Bit 0: key and task key events
Bit 1: redraw events
Bit 2: foreground, background, and power on events
Bit 3: mouse and rubber band events
Bit 4: all other events
Bit 15: escape events

Calling wGetEvent is equivalent to calling this function with a mask of 0x1F. Escape events are sent only if key events are not selected; in this case, if the ESC key is pressed, all pending keystrokes are thrown away and the client is sent an escape event.

Sub-function 0x14: wGetEventUpdate v4

@@: event type mask

If there is an asynchronous call to wGetEvent or wGetEventSpecial outstanding, it changes the mask specifying the events being looked for. If no call is outstanding, it has no effect.

No Comments
Back to top