TH WINDOW 2
SH NAME
Screen, allocscreen, publicscreen, freescreen, allocwindow, bottomwindow, bottomnwindows, topwindow, topnwindows, originwindow \- window management
SH SYNOPSIS
nf
B
#include <u.h>
B
#include <libc.h>
B
#include <draw.h>
PP
ft L
nf
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;
fi
ta \w'\fLScreen* 'u
PP
B
Screen* allocscreen(Image *image, Image *fill, int public)
PP
B
Screen* publicscreen(Display *d, int id, ulong chan)
PP
B
int     freescreen(Screen *s)
PP
B
Image*  allocwindow(Screen *s, Rectangle r, int ref, int val)
PP
B
void    bottomwindow(Image *w)
PP
B
void    bottomnwindows(Image **wp, int nw)
PP
B
void    topwindow(Image *w)
PP
B
void    topnwindows(Image **wp, int nw)
PP
B
int     originwindow(Image *w, Point log, Point scr)
PP
ft L
nf
enum
{
       /* refresh methods */
       Refbackup       = 0,
       Refnone         = 1,
       Refmesg         = 2
};
fi
ft P
SH DESCRIPTION
Windows are represented as
B 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.
PP
To create windows, it is first necessary to allocate a
B Screen
data structure to gather them together.
A
B Screen
turns an arbitrary image into something that may have windows upon it.
It is created by
BR allocscreen ,
which takes an
I image
upon which to place the windows (typically
BR display->image ),
a
I 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
B publicscreen
with the
B Display
pointer and the
I id
of the published
BR 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.
B Freescreen
releases a
BR Screen ,
although it may not actually disappear from view until all the windows upon it have also been deallocated.
PP
Unlike
BR allocwindow ,
B allocscreen
does
I not
initialize the appearance of the
BR Screen .
PP
Windows are created by
BR allocwindow ,
which takes a pointer to the
B Screen
upon which to create the window, a rectangle
I r
defining its geometry, an integer pixel value
I val
to color the window initially, and a refresh method
BR ref .
The refresh methods are
BR Refbackup ,
which provides backing store and is the method used by
IR rio (1)
for its clients;
BR 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
BR Refmesg ,
which causes messages to be delivered to the owner of the window
when it needs to be repainted.
B Refmesg
is not fully implemented.
PP
The result of
B allocwindow
is an
B Image
pointer that may be treated like any other image.
In particular, it is freed by calling
B freeimage
(see
IR allocimage (2)).
The following functions, however, apply only to windows, not regular images.
PP
B Bottomwindow
pushes window
I w
to the bottom of the stack of windows on its
BR Screen ,
perhaps obscuring it.
B Topwindow
pulls window
I w
to the top, making it fully visible on its
BR Screen .
(This
B Screen
may itself be within a window that is not fully visible;
B topwindow
will not affect the stacking of this parent window.)
B Bottomnwindows
and
B Topnwindows
are analogous, but push or pull a group of
I nw
windows listed in the array
IR wp .
The order within
IR wp
is unaffected.
PP
Each window is created as an
B Image
whose
B Rectangle
B r
corresponds to the rectangle given to
B allocwindow
when it was created.  Thus, a newly created window
I w
resides on its
B Screen->image
at
IB w ->r
and has internal coordinates
IB w ->r .
Both these may be changed by a call to
BR originwindow .
The two
B Point
arguments to
B originwindow
define the upper left corner of the logical coordinate system
RI ( log )
and screen position
RI ( scr ).
Their usage is shown in the Examples section.
PP
IR Rio (1)
creates its client windows with backing store,
BR Refbackup .
The graphics initialization routine,
B initdraw
(see
IR graphics (2)),
builds a
B Screen
upon this, and then allocates upon that another window indented
to protect the border.  That window is created
BR Refnone ,
since the backing store created by
B rio
protects its contents.  That window is the one known in the
library by the global name
B screen
(a historic but confusing choice).
SH EXAMPLES
To move a window to the upper left corner of the display,
EX
       originwindow(w, w->r.min, Pt(0, 0));
EE
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,
EX
       originwindow(w, Pt(0, 0), w->r.min);
EE
After this is done,
B 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.
SH SOURCE
B /sys/src/libdraw
SH SEE ALSO
IR graphics (2),
IR draw (2),
IR cachechars (2),
IR draw (3)
SH BUGS
The refresh method
B Refmesg
should be finished.

You are viewing proxied material from sdf.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.