Subversion Repositories planix.SVN

.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.