WINDOW(2)                                               WINDOW(2)

     NAME
          Screen, allocscreen, publicscreen, freescreen, allocwindow,
          bottomwindow, bottomnwindows, topwindow, topnwindows,
          originwindow - window management

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <draw.h>

          typedef
          struct Screen
          {
               Display   *display; /* display holding data */
               int       id;       /* id of system-held Screen */
               Image     *image;   /* unused; for reference only */
               Image     *fill;    /* color to paint behind windows */
          } Screen;

          Screen* allocscreen(Image *image, Image *fill, int public)

          Screen* publicscreen(Display *d, int id, ulong chan)

          int     freescreen(Screen *s)

          Image*  allocwindow(Screen *s, Rectangle r, int ref, ulong
          col)

          void    bottomwindow(Image *w)

          void    bottomnwindows(Image **wp, int nw)

          void    topwindow(Image *w)

          void    topnwindows(Image **wp, int nw)

          int     originwindow(Image *w, Point log, Point scr)

          enum
          {
                  /* refresh methods */
                  Refbackup= 0,
                  Refnone= 1,
                  Refmesg= 2
          };

     DESCRIPTION
          Windows are represented as Images and may be treated as reg-
          ular images for all drawing operations.  The routines dis-
          cussed here permit the creation, deletion, and shuffling of

     Page 1                       Plan 9             (printed 3/19/24)

     WINDOW(2)                                               WINDOW(2)

          windows, facilities that do not apply to regular images.

          To create windows, it is first necessary to allocate a
          Screen data structure to gather them together.  A Screen
          turns an arbitrary image into something that may have win-
          dows upon it.  It is created by allocscreen, which takes an
          image upon which to place the windows (typically
          display->image), a fill image to paint the background behind
          all the windows on the image, and a flag specifying whether
          the result should be publicly visible.  If it is public, an
          arbitrary other program connected to the same display may
          acquire a pointer to the same screen by calling publicscreen
          with the Display pointer and the id of the published Screen,
          as well as the expected channel descriptor, as a safety
          check.  It will usually require some out-of-band coordina-
          tion for programs to share a screen profitably.  Freescreen
          releases a Screen, although it may not actually disappear
          from view until all the windows upon it have also been deal-
          located.

          Unlike allocwindow, allocscreen does not initialize the
          appearance of the Screen.

          Windows are created by allocwindow, which takes a pointer to
          the Screen upon which to create the window, a rectangle r
          defining its geometry, an integer pixel value col to color
          the window initially, and a refresh method ref.  The refresh
          methods are Refbackup, which provides backing store and is
          the method used by rio(1) for its clients; Refnone, which
          provides no refresh and is designed for temporary uses such
          as sweeping a display rectangle, for windows that are com-
          pletely covered by other windows, and for windows that are
          already protected by backing store; and Refmesg, which
          causes messages to be delivered to the owner of the window
          when it needs to be repainted.  Refmesg is not fully imple-
          mented.

          The result of allocwindow is an Image pointer that may be
          treated like any other image.  In particular, it is freed by
          calling freeimage (see allocimage(2)). The following func-
          tions, however, apply only to windows, not regular images.

          Bottomwindow pushes window w to the bottom of the stack of
          windows on its Screen, perhaps obscuring it.  Topwindow
          pulls window w to the top, making it fully visible on its
          Screen.  (This Screen may itself be within a window that is
          not fully visible; topwindow will not affect the stacking of
          this parent window.)  Bottomnwindows and Topnwindows are
          analogous, but push or pull a group of nw windows listed in
          the array wp. The order within wp is unaffected.

          Each window is created as an Image whose Rectangle r

     Page 2                       Plan 9             (printed 3/19/24)

     WINDOW(2)                                               WINDOW(2)

          corresponds to the rectangle given to allocwindow when it
          was created.  Thus, a newly created window w resides on its
          Screen->image at w->r and has internal coordinates w->r.
          Both these may be changed by a call to originwindow.  The
          two Point arguments to originwindow define the upper left
          corner of the logical coordinate system (log) and screen
          position (scr).  Their usage is shown in the Examples sec-
          tion.

          Rio(1) creates its client windows with backing store,
          Refbackup.  The graphics initialization routine, initdraw
          (see graphics(2)), builds a Screen upon this, and then allo-
          cates upon that another window indented to protect the bor-
          der.  That window is created Refnone, since the backing
          store created by rio protects its contents.  That window is
          the one known in the library by the global name screen (a
          historic but confusing choice).

     EXAMPLES
          To move a window to the upper left corner of the display,
                  originwindow(w, w->r.min, Pt(0, 0));
          To leave a window where it is on the screen but change its
          internal coordinate system so (0, 0) is the upper left cor-
          ner of the window,
                  originwindow(w, Pt(0, 0), w->r.min);
          After this is done, w->r is translated to the origin and
          there will be no way to discover the actual screen position
          of the window unless it is recorded separately.

     SOURCE
          /sys/src/libdraw

     SEE ALSO
          graphics(2), draw(2), cachechars(2), draw(3)

     BUGS
          The refresh method Refmesg should be finished.

     Page 3                       Plan 9             (printed 3/19/24)