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-manager implementation and possibly misbehaving
clients. It provides notification when clients arrive, make
window-manager requests, and leave. For each client, it pro-
vides a set of channels that mirror those found in
Page 1 Plan 9 (printed 12/22/24)
WMSRV(2) WMSRV(2)
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 man-
ager 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 ini-
tialise 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; communication on
this channel is used to establish a new client connection.
Join is used to receive notifications of new clients arriv-
ing. 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 conventionally 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 window (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
Page 2 Plan 9 (printed 12/22/24)
WMSRV(2) WMSRV(2)
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 outstanding 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 coordinate 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 window 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
Page 3 Plan 9 (printed 12/22/24)
WMSRV(2) WMSRV(2)
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 con-
nection requests.
SOURCE
/appl/lib/wmsrv.b
SEE ALSO
wm(1), draw-screen(2), wmlib(2), wmexport(1), wmclient(2),
tkclient(2),
Page 4 Plan 9 (printed 12/22/24)