Chapter 19 Ports, Grafts, and Mirrored Sheets

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.

find-graft [Function]
Arguments:
&key (port (find-port)) (server-path *default-server-path*) (orientation :default) (units :device)
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:

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.


CLIM 2.0 User's Guide - OCT 1998

Generated with Harlequin WebMaker