window(3) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/window.html | 241 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 man/man3/window.html (limited to 'man/man3/window.html') diff --git a/man/man3/window.html b/man/man3/window.html new file mode 100644 index 00000000..83355bdd --- /dev/null +++ b/man/man3/window.html @@ -0,0 +1,241 @@ + +window(3) - Plan 9 from User Space + + + + +

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 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 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 coordination + 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 + 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 implemented. +
+ + 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 functions, 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 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 section. +
+ + 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 allocates upon that another + window indented to protect the border. 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 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
+ +
+ + /usr/local/plan9/src/libdraw + +
+

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

BUGS
+ +
+ + The refresh method Refmesg should be finished.
+ +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3