The constructor creates a Picture that shows nothing until the source or element is specified. 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.
Common usage:
new go.Picture("example_image_url.png", {
width: 100,
height: 50
})
Or:
// specify a different source for each node in the node data
new go.Picture({
width: 100,
height: 50
}).bind("source")
Optionally set the Pictures's source.
Optional properties to initialize.
The constructor creates a Picture that shows nothing until the source or element is specified. 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.
Optional properties to initialize.
Gets or sets the Picture's HTML element that provides some kind of visual image.
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.
If this property is set to an HTMLImageElement, and that element is not yet loaded before it is used, the Diagrams using that Element will not redraw on their own. You must call redraw after the image is finished loading if you wish for the Diagram to be updated immediately.
Gets or sets the function to call if an image set by source fails to load. The arguments to this function are this Picture and the HTMLImageElement's "error" Event.
This is called once per Picture, for every Picture that is using the same source that failed to load. This will never be called if the source is never set, and is not called with Pictures that use element instead.
The default value is null, meaning that no specific action occurs when there is an error loading an image.
Gets or sets how the Picture is displayed: Either normally or with a Horizontal or Vertical flip or both.
Possible values are GraphObject.None, GraphObject.FlipHorizontal, GraphObject.FlipVertical, or GraphObject.FlipBoth. The default is GraphObject.None.
Gets or sets the Spot to align the source image to, when the source image is smaller than the Picture. 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.
Gets or sets how the Picture's image is stretched within its bounding box. 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.
Possible values are GraphObject.Fill, GraphObject.Uniform, GraphObject.UniformToFill, and GraphObject.None. The default is GraphObject.Fill.
This read-only property returns the natural size of this picture as determined by its source's width and height.
The value is initially NaN x NaN until the picture has been measured.
It will use the element's naturalWidth and naturalHeight if available.
Gets or sets the Picture's source URL, which can be any valid image (png, jpg, gif, etc) URL.
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. When the element loads, this Picture may remeasure if no GraphObject.desiredSize was set, and Diagrams using the picture will redraw.
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.
Setting the source of multiple Pictures to the same URL will cause only one HTMLImageElement to be created and shared. Setting the source to the empty string will set Picture.element to null. 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.
For cross-browser support of SVG sources additional care is needed. See the final section of the Introduction page on Pictures.
Gets or sets a function that returns a value for image.crossOrigin.
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"))
Gets or sets the rectangular area of the source image that this picture should display. 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.
Gets or sets the function to call when an image set by source loads successfully. The arguments to this function are this Picture and the HTMLImageElement's "load" Event.
This is called once per Picture, for every Picture that is using the same source that loaded successfully. This will never be called if the source is never set, and is not called with Pictures that use element instead. It is even called for a Picture source that has already loaded, so that creating copies of a Picture with this property set will call it once for each newly created Picture.
The default value is null, meaning that no specific action occurs when an image finishes loading.
Redraws a Picture, which can be useful if the backing element is an HTML Canvas or HTML Video that has changed. This will not attempt to reload any image. If you need to do that, call reloadSource.
This does not need to be called within a transaction, and will not re-measure anything.
Attempts to reload a Picture.source image. This can be useful if the content on a server has changed, or was missing before. If a new image is loaded, this Picture may remeasure and/or redraw.
This should normally be called within a transaction.
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:
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.