man(1) Manual page archive


     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

     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

     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

     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),