Class Picture

Extends GraphObject. A Picture is a GraphObject that shows an image, video-frame, or Canvas element.

You can specify what to show by either setting the source URL property to a URL string or the element property to an HTMLImageElement, HTMLCanvasElement, or HTMLVideoElement.

If a source URL is set, the Picture will automatically create a corresponding HTMLImageElement and retain a reference to it in memory. If multiple Pictures specify the same source URL then they will all refer to the same HTMLImageElement.

Some created Pictures: 

var $ = go.GraphObject.make;  // for conciseness in defining GraphObjects

// A shape with the figure set to "example.png". It will show a gray area until the image is loaded:
$(go.Picture, { source: "example.png", background: "gray", width: 50, height: 50 })
// Alternatively:
$(go.Picture, "example.png", { background: "gray", width: 50, height: 50 })

If an element is not completely loaded during Diagram initialization, a redraw may occur, and if an image's size is not known before loading, the containing Part of this Picture may be resized, causing side effects such as layouts. This can be avoided by knowing the size of the image beforehand, and setting the Picture's GraphObject.desiredSize.

With some images (notably sprite sheets) only a portion of the image is expected to be drawn. The sourceRect property allows the programmer to specify a rectangular area of the source image that the Picture should display.

The imageStretch property allows an image to be resized inside of its bounding box. This property does not change the size of the Picture element, it only resizes or re-scales the image to fit (or not) in its bounds.

For examples of sizing and imageStretch, see the Introduction page on Pictures.

The errorFunction property allows one to set a function to call when a source fails to load. This is useful in instances where images cannot be guaranteed to work, such as with user specified input. The error function can set the source to a known good value, but care should be taken to avoid error infinite loops when doing so.

Constructor Summary Details

Name Description
Picture()

The constructor creates a picture that shows nothing until the source or element is specified.More... It is also common to specify the GraphObject.desiredSize to make sure that the picture's size is known before the image is loaded asynchronously, so that layouts do not need to be recomputed.

Properties Summary Details

Name, Value Type Description
element
{HTMLImageElement | HTMLVideoElement | HTMLCanvasElement}

Gets or sets the Picture's HTML element that provides some kind of visual image.More...

The default value is null. This can be a HTMLImageElement, HTMLVideoElement, or HTMLCanvasElement. If an image, this element must have its source (src) attribute defined. Setting this does not set the Picture.source attribute and that attribute may be unknowable.
errorFunction
{function(Picture, Event) | null}

Gets or sets the function to call if an image fails to load.More... The arguments to this function are this Picture and the HTMLImageElement's "error" (onerror) Event. The default value is null, meaning that no specific action occurs when there is an error loading an image.

See also:
imageAlignment
{Spot} 1.7

Gets or sets the Spot to align the source image to, when the source image is smaller than the Picture.More... This is only relevant when the imageStretch property value is not go.GraphObject.Fill.

This does not affect Picture coordinates or bounds, it only affects what is drawn within the given area. The default value is Spot.Center.

See also:
imageStretch
{EnumValue}

Gets or sets how the Picture's image is stretched within its bounding box.More... Some images will be a different aspect ratio than their given size or desiredSize. This property will never change the size of the Picture itself, only the size of the image that is drawn in the Picture's actualBounds.

See also:
naturalBounds
{Rect}

This read-only property returns the natural size of this picture as determined by its source's width and height.More... The value is initially NaN x NaN until the picture has been measured. It will use the element's naturalWidth and naturalHeight if available.

source
{string}

Gets or sets the Picture's source URL, which can be any valid image (png, jpg, gif, etc) URL.More...

The default value is the empty string, which specifies no image source. Setting this attribute creates an HTMLImageElement and sets the Picture.element attribute to that element. Setting the source of multiple Pictures to the same URL will cause only one HTMLImageElement to be created and shared. It is commonplace to either specify a constant URL or to data bind this property to some data property, perhaps using a conversion function in order to produce a proper URL.

To avoid remeasuring and rearranging Parts as images load asynchronously, be sure to set the GraphObject.desiredSize (or GraphObject.width and GraphObject.height) to fixed values

For cross-browser support of SVG sources additional care is needed. See the final section of the Introduction page on Pictures.
sourceCrossOrigin
{function(Picture):string|null} 1.5

Gets or sets a function that returns a value for image.crossOrigin.More...

The default value is null, which will not set a value for image.crossOrigin. Set this property to a function that returns "anonymous" or "use-credentials" if you want images to complete a cross-origin request. Example: 

   $(go.Picture,
     { width: 64, height: 64 },
     { sourceCrossOrigin: function(pict) { return "use-credentials"; } },
     new go.Binding("source", "path"))
sourceRect
{Rect}

Gets or sets the rectangular area of the source image that this picture should display.More... This is only common with sprite maps and image tables.

The value must be of type Rect. The default value is Rect(NaN, NaN, NaN, NaN), which means the whole source image should be used.
successFunction
{function(Picture, Event) | null} 1.7

Gets or sets the function to call when an image loads successfully.More... The arguments to this function are this Picture and the HTMLImageElement's "load" Event. The default value is null, meaning that no specific action occurs when an image finishes loading.

See also:
Properties borrowed from class GraphObject:
actionCancel, actionDown, actionMove, actionUp, actualBounds, alignment, alignmentFocus, angle, areaBackground, background, click, column, columnSpan, contextClick, contextMenu, cursor, Default, desiredSize, diagram, doubleClick, enabledChanged, Fill, fromEndSegmentLength, fromLinkable, fromLinkableDuplicates, fromLinkableSelfNode, fromMaxLinks, fromShortLength, fromSpot, height, Horizontal, isActionable, isPanelMain, layer, margin, maxSize, measuredBounds, minSize, mouseDragEnter, mouseDragLeave, mouseDrop, mouseEnter, mouseHold, mouseHover, mouseLeave, mouseOver, name, None, opacity, panel, part, pickable, portId, position, row, rowSpan, scale, segmentFraction, segmentIndex, segmentOffset, segmentOrientation, shadowVisible, stretch, toEndSegmentLength, toLinkable, toLinkableDuplicates, toLinkableSelfNode, toMaxLinks, toolTip, toShortLength, toSpot, Uniform, UniformToFill, Vertical, visible, width
Methods borrowed from class GraphObject:
bind, copy, getDocumentAngle, getDocumentPoint, getDocumentScale, getLocalPoint, isContainedBy, isEnabledObject, isVisibleObject, setProperties