# Class Picture

GoJS® Diagramming Components
version 3.0.7
by Northwoods Software®

#### Hierarchy

- GraphObject
  - Picture

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.

An example Picture, within a Node template:

    // A picture with the source set to "example.png". It will show a gray area until the image is loaded:
    new 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.

#####
Index

### Constructors

constructor

### Accessors

element
errorFunction
flip
imageAlignment
imageStretch
naturalBounds
source
sourceCrossOrigin
sourceRect
successFunction

### Methods

redraw
reloadSource

#####
Inherited Index

### Accessors

GraphObject.actionCancel
GraphObject.actionDown
GraphObject.actionMove
GraphObject.actionUp
GraphObject.actualBounds
GraphObject.alignment
GraphObject.alignmentFocus
GraphObject.angle
GraphObject.background
GraphObject.click
GraphObject.column
GraphObject.columnSpan
GraphObject.contextClick
GraphObject.contextMenu
GraphObject.cursor
GraphObject.desiredSize
GraphObject.diagram
GraphObject.doubleClick
GraphObject.enabledChanged
GraphObject.fromEndSegmentLength
GraphObject.fromLinkable
GraphObject.fromLinkableDuplicates
GraphObject.fromLinkableSelfNode
GraphObject.fromMaxLinks
GraphObject.fromShortLength
GraphObject.fromSpot
GraphObject.height
GraphObject.isActionable
GraphObject.isPanelMain
GraphObject.layer
GraphObject.margin
GraphObject.maxSize
GraphObject.measuredBounds
GraphObject.minSize
GraphObject.mouseDragEnter
GraphObject.mouseDragLeave
GraphObject.mouseDrop
GraphObject.mouseEnter
GraphObject.mouseHold
GraphObject.mouseHover
GraphObject.mouseLeave
GraphObject.mouseOver
GraphObject.name
GraphObject.opacity
GraphObject.panel
GraphObject.part
GraphObject.pickable
GraphObject.portId
GraphObject.position
GraphObject.row
GraphObject.rowSpan
GraphObject.scale
GraphObject.segmentFraction
GraphObject.segmentIndex
GraphObject.segmentOffset
GraphObject.segmentOrientation
GraphObject.shadowVisible
GraphObject.stretch
GraphObject.toEndSegmentLength
GraphObject.toLinkable
GraphObject.toLinkableDuplicates
GraphObject.toLinkableSelfNode
GraphObject.toMaxLinks
GraphObject.toShortLength
GraphObject.toSpot
GraphObject.toolTip
GraphObject.visible
GraphObject.width

### Methods

GraphObject.apply
GraphObject.attach
GraphObject.bind
GraphObject.bindModel
GraphObject.bindObject
GraphObject.bindTwoWay
GraphObject.copy
GraphObject.findBindingPanel
GraphObject.getDocumentAngle
GraphObject.getDocumentBounds
GraphObject.getDocumentPoint
GraphObject.getDocumentScale
GraphObject.getLocalPoint
GraphObject.isContainedBy
GraphObject.isEnabledObject
GraphObject.isVisibleObject
GraphObject.set
GraphObject.setProperties
GraphObject.theme
GraphObject.themeData
GraphObject.themeModel
GraphObject.themeObject
GraphObject.trigger

## Constructors

### constructor

- new Picture(source?: string, init?: Partial<Picture>): Picture

- 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")

  #### Parameters

  - ##### `Optional` source: string

    Optionally set the Pictures's source.

  - ##### `Optional` init: Partial<Picture>

    Optional properties to initialize.

  #### Returns Picture

- new Picture(init?: Partial<Picture>): Picture

- 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. *

  #### Parameters

  - ##### `Optional` init: Partial<Picture>

    Optional properties to initialize.

  #### Returns Picture

## Accessors

### element
: HTMLCanvasElement | HTMLImageElement | HTMLVideoElement

- 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.

### errorFunction
: ((a: Picture, b: Event) => void)

- 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.

  `see`

  successFunction

### flip
: Flip

- Gets or sets how the Picture is displayed: Either normally or with a Horizontal or Vertical flip or both.

  Possible values are Flip.None, Flip.Horizontal, Flip.Vertical, or Flip.Both. The default is Flip.None.

  `since`

  2.0

### imageAlignment
: Spot

- 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.ImageStretch.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`

  imageStretch

### imageStretch
: ImageStretch

- 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 ImageStretch.Fill, ImageStretch.Uniform, ImageStretch.UniformToFill, and ImageStretch.None. The default is ImageStretch.Fill.

  `see`

  imageAlignment

### `Readonly` naturalBounds
: Rect

- 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.

### source
: string

- 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.

### sourceCrossOrigin
: ((a: Picture) => string)

- 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: pict => "use-credentials" },
           new go.Binding("source", "path"))

### sourceRect
: Rect

- 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.

### successFunction
: ((a: Picture, b: Event) => void)

- 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.

  `see`

  errorFunction

## Methods

### redraw

- redraw(): void

- 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.

  #### Returns void

  `since`

  2.1

### reloadSource

- reloadSource(): void

- 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.

  Because of browsers caching assets, you may additionally need to force a re-fetch of the Picture's source URL with a `fetch` call such as:

      fetch(thisPicture.source, { cache: 'reload', mode: 'no-cors' });

  This should normally be called within a transaction.

  #### Returns void

  `since`

  2.1

Copyright © 1998-2024 by Northwoods Software Corporation.