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 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 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, al‐
though 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 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 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 ar‐
ray 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 co‐
ordinates 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 co‐
ordinate 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)