WINDOW(3) WINDOW(3)
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, 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 reg-
ular images for all drawing operations. The routines dis-
cussed here permit the creation, deletion, and shuffling of
Page 1 Plan 9 (printed 11/18/24)
WINDOW(3) WINDOW(3)
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 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 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(3)). 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 11/18/24)
WINDOW(3) WINDOW(3)
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(3)), 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
/usr/local/plan9/src/libdraw
SEE ALSO
graphics(3), draw(3), cachechars(3), draw(3)
BUGS
The refresh method Refmesg should be finished.
Page 3 Plan 9 (printed 11/18/24)