WMCLIENT(2)                                           WMCLIENT(2)

     NAME
          wmclient: makedrawcontext, window, snarfput, snarfget,
          cursorspec - window manager interface for Draw-based
          applications.

     SYNOPSIS
          include "tk.m";
          include "wmclient.m";
          wmclient := load Wmclient Wmclient->PATH;

          Resize,
          Hide,
          Help,
          OK,
          Popup,
          Plain:  con 1 << iota;

          Appl:   con Resize | Hide;

          init:             fn();
          makedrawcontext:  fn():  ref Draw->Context;
          window:           fn(ctxt: ref Draw->Context, title: string, buts: int): ref Window;
          snarfput:         fn(buf: string);
          snarfget:         fn(): string;
          cursorspec:       fn(img: ref Draw->Image): string;

          Window: adt{
               display:   ref Draw->Display;
               r:         Draw->Rect;
               image:     ref Draw->Image;
               displayr:  Draw->Rect;
               ctxt:      ref Draw->Wmcontext;
               bd:        int;
               focused:   int;
               ctl:       chan of string;

               startinput:  fn(w: self ref Window, devs: list of string);
               wmctl:       fn(w: self ref Window, request: string): string;
               settitle:    fn(w: self ref Window, name: string): string;
               reshape:     fn(w: self ref Window, r: Draw->Rect);
               onscreen:    fn(w: self ref Window, how: string);
               screenr:     fn(w: self ref Window, sr: Draw->Rect): Draw->Rect;
               imager:      fn(w: self ref Window, ir: Draw->Rect): Draw->Rect;
               pointer:     fn(w: self ref Window, p: Draw->Pointer): int;
          };

     DESCRIPTION
          The Wmclient module provides routines for making windows
          controlled by wm(1) containing an image that can be drawn on

     Page 1                       Plan 9            (printed 12/21/24)

     WMCLIENT(2)                                           WMCLIENT(2)

          with the routines described in draw-image(2).

          Init should be called once to initialise the internal state
          of wmclient.

          Makedrawcontext establishes an initial connection with the
          window manager, creating a new Draw context suitable for
          creating new windows. It is only necessary to call this if
          the application has not already been provided with a con-
          text.

          Window creates a new window through ctxt and returns it.
          Title gives a label that will be displayed in the title bar
          of the window; buts determines which buttons are created in
          the titlebar, a bitwise combination of the constants Resize,
          Help, OK, and Hide.  If Plain is given, the window is given
          no decoration at all.

          When a window, say w, is first created, its size has not
          been determined and its image is not yet allocated.
          W.reshape sets the requested rectangle for the window, (and
          requests a new image for the window if it has already been
          made visible), where r gives the requested rectangle of the
          new image, excluding window decoration, such as the title
          bar and the window border.

          An application can use w.imager to find out the usable rect-
          angle within screen rectangle ir when window decorations are
          taken into account.  W.screenr converts in the other direc-
          tion.  W.screenr contains the current rectangle of the
          screen containing the window.

          W.image holds the window's image when it has been success-
          fully created; w.ctxt holds the window manager context for
          the window, from which keyboard and mouse events can be
          received.  No such events will be received until
          w.startinput is called, with a list of devices (e.g.  ptr,
          kbd) to start input for.  W.settitle sets the title that is
          shown on the window's title bar; it can make the window's
          size (and therefore the window's image) change.

          W.ctl is a channel down which requests from the titlebar are
          sent.  Messages received on it should be processed by the
          application or passed to w.wmctl.  Requests are formatted as
          with quoted in string(2). The messages include:

     Page 2                       Plan 9            (printed 12/21/24)

     WMCLIENT(2)                                           WMCLIENT(2)

          exit The window should be closed.  W.wmctl will kill all
               processes in the current process group.

          !move x y
               The user has started to try to drag the window.  X and
               y give the location of the initial pointer click.

          !size mindx mindy
               The user wishes to resize the window.  Mindx and mindy
               give the minimum size acceptable for the window.

          help The help button has been clicked.

          ok   The OK  button has been clicked.

          hide The Hide button has been clicked.  W.wmctl will delete
               the window, and an entry will be shown on the toolbar.

          In order to function correctly, an application should pro-
          cess not only events from the title bar channel, but also
          events received from the window manager itself (via
          w.ctxt.ctl), and pointer and keyboard events received from
          the window manager (via top.ctxt.ptr and top.ctxt.kbd
          respectively).  Control events can be passed to w.wmctl;
          keyboard events can be processed by the application; pointer
          events should be passed to w.pointer for processing; if this
          returns zero, the application should process the pointer
          event, otherwise the event has been consumed by the title-
          bar.

          When created, the window is not visible; w.onscreen makes it
          visible, and possibly chooses a position and a size for it.
          How specifies what sort of placement is required for the
          window; it can be one of:

          place
               tries to choose a suitable place on the screen with
               respect to other windows; it may size the window as it
               feels appropriate. This the default (if how is nil).

          onscreen
               tries to keep the position and size the same as speci-
               fied on the window, adjusting them only to bring the

     Page 3                       Plan 9            (printed 12/21/24)

     WMCLIENT(2)                                           WMCLIENT(2)

               window fully on screen, and making sure that the window
               is no bigger than the entire display.

          exact
               does not change the specified size or position of the
               window unless absolutely necessary.

          max  makes the window take up the entire display.

          Snarfget and snarfput retrieve and replace the contents of
          the window manager's snarf buffer.

     FILES
          /chan/snarf  snarf buffer maintained by wm(1)

          /chan/wmctl  channel for interaction with wm(1)

     SOURCE
          /appl/lib/wmclient.b

     SEE ALSO
          wm(1), tk(2)

     Page 4                       Plan 9            (printed 12/21/24)