19.3 Grafts

A
graft
is a special sheet that is directly connected to a display server. Typically, a graft is the CLIM sheet that represents the root window of the display. There may be several grafts that are all attached to the same root window but that have differing coordinate systems.

To display a sheet on a display, it must have a graft as an ancestor. In addition, the sheet and all of its ancestors must be enabled, including the graft. In general, a sheet becomes grafted when it (or one of its ancestors) is adopted by a graft.

sheet-grafted-p [Generic Function]

Arguments: sheet

Summary: Returns
t
if any of the sheet's ancestors is a graft; otherwise, it returns
nil
.

Summary: Finds a graft that represents the display device on the port
port
that also matches the other supplied parameters. If no such graft exists, a new graft is constructed and returned.
find-graft
is called automatically by
make-application-frame
.

If
server-path
is supplied,
find-graft
finds a graft whose port provides a connection to the window server addressed by
server-path
.

It is an error to provide both
port
and
server-path
in a call to
find-graft
.

orientation
specifies the orientation of the graft's coordinate system. It is one of:

:default
--a coordinate system with its origin is in the upper left hand corner of the display device with
y
increasing from top to bottom and
x
increasing from left to right.

:graphics
--a coordinate system with its origin in the lower left hand corner of the display device with
y
increasing from bottom to top and
x
increasing from left to right.

units
specifies the units of the coordinate system and defaults to
:device
, which means the device units of the host window system (such as pixels). Other supported values include
:inches
,
:millimeters
, and
:screen-sized
, which means that one unit in each direction is the width and height of the display device.

graft [Generic Function]

Arguments: object

Summary: Returns the graft currently associated with
object
.
graft
is defined for all sheet classes (including streams that support the CLIM graphics protocol), mediums, and application frames. For degrafted sheets or other objects that aren't currently associated with a particular graft,
graft
will return
nil
.

map-over-grafts [Function]

Arguments: function port

Summary: Invokes
function
on each existing graft associated with the port
port
.
function
is a function of one argument, the graft; it has dynamic extent.

with-graft-locked [Macro]

Arguments: graft
&body
body

Summary: Executes
body
after grabbing a lock associated with the graft
graft
, which may be a graft or any object on which the function
graft
works. If
object
currently has no graft,
body
will be executed without locking.

body
may have zero or more declarations as its first forms.

graft-orientation [Generic Function]

Arguments: graft

Summary: Returns the orientation of the graft
graft
's coordinate system. The returned value is either
:default
or
:graphics
; see the
orientation
argument to
find-graft
.

graft-units [Generic Function]

Arguments: graft

Summary: Returns the units of
graft
's coordinate system, which will be one of
:device
,
:inches
,
:millimeters
, or
:screen-sized
; see the
units
argument to
find-graft
.

graft-width [Generic Function]

Arguments: graft
&key
(units
:device
)

graft-height [Generic Function]

Arguments: graft
&key
(units
:device
)

Summary: Returns the width and height of
graft
(and by extension the associated host window) in the units indicated.
units
may be any of
:device
,
:inches
,
:millimeters
, or
:screen-sized
; see the
units
argument to
find-graft
. Note that if a
unit
of
:screen-sized
is specified, both of these functions will return a value of
1
.

graft-pixels-per-millimeter [Function]

Arguments: graft

graft-pixels-per-inch [Function]

Arguments: graft

Summary: Returns the number of pixels per millimeter or inch of
graft
. These are only for convenience; you can write similar functions with
graft-width
or
graft-height
.