glenda.party
term% ls -F
term% cat index.txt
WINDOW(2)                     System Calls Manual                    WINDOW(2)



NAME
       Screen,  allocscreen, publicscreen, freescreen, allocwindow, bottomwin‐
       dow, bottomnwindows, topwindow, topnwindows, originwindow - window man‐
       agement

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

       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 regular images
       for all drawing operations.  The routines  discussed  here  permit  the
       creation,  deletion,  and  shuffling of 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 windows upon it.  It is created by  alloc‐
       screen, 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  con‐
       nected  to the same display may acquire a pointer to the same screen by
       calling publicscreen with the Display pointer and the id  of  the  pub‐
       lished  Screen, as well as the expected channel descriptor, as a safety
       check.  It will usually require some out-of-band coordination for  pro‐
       grams  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 deallocated.

       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 val 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 completely 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 functions, however, apply only  to  win‐
       dows, 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 corresponds to the
       rectangle given to allocwindow when it was created.  Thus, a newly cre‐
       ated  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 section.

       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 allocates upon that another window indented
       to protect the border.  That window is created Refnone, since the back‐
       ing store created by rio protects its contents.  That window is the one
       known in the library by the global name screen (a historic but  confus‐
       ing 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 corner 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.



                                                                     WINDOW(2)