9.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; these grafts may have differing coordinate systems. [annotate]

[graft, Concept← A Glossary]
[graft, Concept← A Glossary]
[graft, Concept← 9.3 Grafts, graft-pixels-per-millimeter]
[graft, Concept← 9.3 Grafts, graft-width]
[graft, Concept← 9.3 Grafts, graft-units]
[graft, Concept← 9.3 Grafts, graft-orientation]
[graft, Concept← 9.3 Grafts, with-graft-locked]
[graft, Concept← 6.1 Introduction]

To display a sheet on a display, it must have a graft for 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. [annotate]

sheet-grafted-p  sheet [Generic Function]

Returns true if any of the sheet's ancestors is a graft, otherwise returns false. [annotate]


find-graft  &key (server-path *default-server-path*) (port (find-port :server-path server-path)) (orientation :default) (units :device) [Function]

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. [annotate]

Note: I wonder how a new graft could be constructed, if either the combination of orientation and units is not supported by any graft of the port. Or even, if there cannot be any port found, because I passed say :server-path '(:acme)? [edit]-- Gilbert Baumann 2015-03-19 01:47Z

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

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

orientation specifies the orientation of the graft's coordinate system. Supported values are :default and :graphics, which have the meanings describe below: [annotate]

  • :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. [annotate]
  • :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. [annotate]

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. [annotate]

Minor issue: I don't know how much of this is obsolete. --- RSL [annotate]

Note: Given that application frames are adopted by a frame manager and not by a graft and the extra arguments like orientation and units are not part of FIND-FRAME-MANAGER [which implies that the defaults apply], I'd say that in practice those arguments are obsolete. From a pure Silica point of view however, they might not. However, even then I am very skeptical, since flipping over the y-axis is a dramatic change. Likewise changing the unit is dramatic. I think we are better off, by accepting that our unit is some approximation of printers points and live with that. [edit]-- Gilbert Baumann 2015-03-19 01:59Z


graft  object [Generic Function]

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. [annotate]


map-over-grafts  function port [Function]

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


with-graft-locked  (graft) &body body [Macro]

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. [annotate]

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


graft-orientation  graft [Generic Function]

Returns the orientation of the graft graft's coordinate system. The returned value will be either :default or :graphics. The meanings of these values are the same as described for the orientation argument to find-graft. [annotate]


graft-units  graft [Generic Function]

Returns the units of the graft graft's coordinate system. The returned value will be one of :device, :inches, :millimeters, or :screen-sized. The meanings of these values are the same as described for the units argument to find-graft. [annotate]


graft-width  graft &key (units :device) [Generic Function]
graft-height  graft &key (units :device) [Generic Function]

Returns the width and height of the graft graft (and by extension the associated host window) in the units indicated. Units may be any of :device, :inches, :millimeters, or :screen-sized. The meanings of these values are the same as described for the units argument to find-graft. Note if a unit of :screen-sized is specified, both of these functions will return a value of 1. [annotate]


graft-pixels-per-millimeter  graft [Function]
graft-pixels-per-inch  graft [Function]

Returns the number of pixels per millimeter or inch of the graft graft. These functions are provided as a convenience to programmers and can be easily written in terms of graft-width or graft-height. [annotate]

Minor issue: Do we want to support non-square pixels? If so, these functions aren't sufficient. --- Rao [annotate]


We add an extra &key argument :orientation that defaults to :horizontal.

The pixel aspect ratio may be easily determined with:

``` (defmethod graft-pixel-aspect-ratio ((graft graft)) (let ((x/inch (graft-pixels-per-inch graft :orientation :horizontal)) (y/inch (graft-pixels-per-inch graft :orientation :vertical))) (if (= x/inch y/inch) (values 1 1) (values x/inch y/inch)))) ```

[edit]-- DK 2022-04-19 14:06Z