|
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
BUGS
| |
The refresh method Refmesg should be finished.
|
|
|
