WMSRV(2)WMSRV(2)NAME
Wmsrv - core window-manager functionality and helper functions
SYNOPSIS
include "sys.m";
include "draw.m";
include "wmsrv.m";
wmsrv := load Wmsrv Wmsrv->PATH;
Client, Window: import wmsrv;
init: fn():
(chan of (string, chan of (string, ref Draw->Wmcontext)),
chan of (ref Client, chan of string),
chan of (ref Client, array of byte, Sys->Rwrite));
find: fn(p: Draw->Point): ref Client;
top: fn(): ref Client;
Window: adt {
tag: string;
r: Rect;
img: ref Image;
};
Client: adt {
kbd: chan of int;
ptr: chan of ref Draw->Pointer;
ctl: chan of string;
stop: chan of int;
images: chan of (ref Draw->Point, ref Draw->Image, chan of int);
flags: int;
wins: list of ref Window;
znext: cyclic ref Client;
id: int;
window: fn(c: self ref Client, tag: string): ref Window;
contains: fn(c: self ref Client, p: Draw->Point): int;
setimage: fn(c: self ref Client, tag: string, i: ref Draw->Image): int;
setorigin:fn(c: self ref Client, tag: string, o: Draw->Point): int;
top: fn(c: self ref Client);
bottom: fn(c: self ref Client);
remove: fn(w: self ref Client);
};
DESCRIPTION
Wmsrv acts as a kind of ``buffer'' module between an actual window-man‐
ager implementation and possibly misbehaving clients. It provides
notification when clients arrive, make window-manager requests, and
leave. For each client, it provides a set of channels that mirror those
found in Draw->Wmcontext, (see draw-context(2)), except that writing to
the Client's channels is guaranteed not to block. Each client holds
zero or more Windows, each of which is tagged with an identifying
string and which can hold the image of that window. A given client's
windows are layered in strict order, most recently created at the top.
Most clients will have only one window; others are generally used only
for ephemeral purposes, such as pop-up menus.
A Client, say c, holds some channels directly equivalent to their
Wmcontext namesakes: c.kbd c.ptr, and c.ctl. The behaviour of c.images
is described below. Wmsrv starts a new process to mediate interaction
between the window manager and its clients; sending a value on c.stop
causes this process to exit. C.wins gives the list of all the windows
associated with this client; c.flags is not used by wmsrv: it may be
used to store arbitrary information; c.id holds a unique identifier for
the client; it will be no larger than the largest number of clients
that have simultaneously existed; c.znext links clients together by
window depth (see top, below).
Init must be called before any other wmsrv function to initialise the
wmsrv module. It creates the virtual file /chan/wm, and returns a tuple
of channels, say (wm, join, rq). Wm is the channel that should be
passed to prospective clients in the Draw->Context structure; communi‐
cation on this channel is used to establish a new client connection.
Join is used to receive notifications of new clients arriving. The
tuple received on this channel, say (c, rc) holds the new client, and a
channel on which a reply should be sent acknowledging the new client.
If the string sent is non-empty, it represents an error message that
will be returned to the client, and the client will not be allowed to
join. c.ptr, c.kbd, and c.ctl are all direct equivalents of their
Wmcontext namesakes; the behaviour of c.images is described below. Rq
is used to receive requests made by clients to the window manager by
writing to the file /chan/wm. The tuple received on rq, say (c, data,
reply) holds the client that is making the request, the data that has
been sent, and a channel that can be used (as described in sys-
file2chan(2)) to return a reply to the request, The request is conven‐
tionally formatted as a utf8-encoded string, holding a list of tokens
quoted as described in quoted in string(2).
If the first character of a window-manager request is an exclamation
mark (!), it should be a request to change the image of a client's win‐
dow (or create a new window). In this case, the first three tokens
should be the name of the command (starting with an exclamation mark),
the tag of the window to which the request refers, and a tag used by
clients to match requests to replies. If such a request is allowed to
succeed, then clients expect that a new image will be sent to them.
The images channel in a client is used to do this (normally accessed
through the setimage and setorigin methods, see below). Sending a
tuple, say (o, i, rc) on images buffers an image to be returned to the
client. If o is non-nil, the request will change the physical origin
of i to o, otherwise i gives a new image (its logical origin must match
its physical origin). Only one such request is allowed to be outstand‐
ing at any one time; the channel passed in rc will yield the value -1
if the image from a previous request has not yet been consumed, in
which case the current request should be caused to fail.
Wmsrv can maintain a record of the current windows and their stacking
order relative to one other. Top returns a pointer to the client at
the top of the stack; the other clients can be accessed, in stacking
order, via their znext references. Find finds the top client that has
a window containing the point p. Wmsrv provides various Client methods
that may be used to help implement a window manager's interface:
c.window(tag)
Yield the Window, w, corresponding to tag, or nil if there is
none. Note that w.r holds the actual screen rectangle of the
image; the client is free to modify the image's logical coor‐
dinate system, so w.img.r cannot be relied upon to contain a
value with a meaningful origin.
c.contains(p)
Return non-zero if any of the client's windows contain the
point p.
c.setimage(tag, i)
Set the image associated with window tag to i. If this is in
response to a window manager request, i must be non-nil, and
wmsrv will arrange that the new image is sent to the client.
If this is not possible, then setimage will return -1. If i
is nil, no image will be sent to the client and the window
will be deleted.
c.setorigin(tag, o)
Similar to setimage, except that only the origin of the win‐
dow is changed. In order to enable clients to maintain their
own logical coordinate system, wmsrv first sends nil on the
Wmcontext.images channel, allowing the client to suspend
operations on the image momentarily; it then sends to same
channel, with its origin set to its actual screen origin.
The client is then free to set the logical origin again.
c.top() Raise the client's windows above the other clients' windows.
c.bottom()
Send the client's windows below the other clients' windows.
c.remove()
Remove the client and its windows from wmsrv's window stack.
FILES
/chan/wm Created by wmsrv using file2chan(2) to serve connection
requests.
SOURCE
/appl/lib/wmsrv.b
SEE ALSOwm(1), draw-screen(2), wmlib(2), wmexport(1), wmclient(2), tkclient(2),
WMSRV(2)
