Class Picture

GoDiagram®
v10.0.12
by Northwoods Software®

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

Inheritance
object
GraphObject
Picture
Namespace: Northwoods.Go
Assembly: Northwoods.GoDiagram.WinForms.dll
Syntax
public class Picture : GraphObject, IHasContextMenu, IHasToolTip
Remarks

You can specify what to show by either setting the Source URL property to a URL string or the Element property to an ImageElement.

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

A created Picture:

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

Constructors

Picture()

Constructs a picture that shows nothing until the Source or Element is specified. It is also common to specify the 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.

Declaration
public Picture()

Picture(string)

Constructs a picture with the given Source. It is also common to specify the 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.

Declaration
public Picture(string src)
Parameters
Type Name Description
string src

Properties

Element

Gets or sets the Picture's ImageElement that provides some kind of visual image.

Declaration
public ImageElement Element { get; set; }
Property Value
Type Description
ImageElement
Remarks

The default value is null. Setting this does not set the Source attribute and that attribute may be unknowable.

Typically, this property will be used when one has access to a platform-specific image. The image can be used to construct an ImageElement for the particular platform.

ErrorFunction

Gets or sets the function to call if an image set by Source fails to load.

Declaration
public Action<Picture, object> ErrorFunction { get; set; }
Property Value
Type Description
Action<Picture, object>
Remarks

The arguments to this function are this Picture and the ImageElement's "error" (onerror) 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 Also

Flip

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

Declaration
public Flip Flip { get; set; }
Property Value
Type Description
Flip
Remarks

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

ImageAlignment

Gets or sets the Spot to align the source image to, when the source image is smaller than the Picture.

Declaration
public Spot ImageAlignment { get; set; }
Property Value
Type Description
Spot
Remarks

This is only relevant when the ImageStretch property value is not Fill.

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

See Also

ImageStretch

Gets or sets how the Picture's image is stretched within its bounding box.

Declaration
public ImageStretch ImageStretch { get; set; }
Property Value
Type Description
ImageStretch
Remarks

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

See Also

NaturalBounds

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.

Declaration
public override Rect NaturalBounds { get; }
Property Value
Type Description
Rect
Overrides

Source

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

Declaration
public string Source { get; set; }
Property Value
Type Description
string
Remarks

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

Whether the URI resolves to a proper ImageElement will depend on the platform and what sort of formats are accepted. See the ImageElement class for platform-specific information.

To avoid remeasuring and rearranging Parts as images load asynchronously, be sure to set the DesiredSize (or Width and Height) to fixed values.

SourceRect

Gets or sets the rectangular area of the source image that this picture should display.

Declaration
public Rect SourceRect { get; set; }
Property Value
Type Description
Rect
Remarks

This is only common with sprite maps and image tables.

The default value is Rect(NaN, NaN, NaN, NaN), which means the whole source image should be used.

SuccessFunction

Gets or sets the function to call when an image set by Source loads successfully.

Declaration
public Action<Picture, object> SuccessFunction { get; set; }
Property Value
Type Description
Action<Picture, object>
Remarks

The arguments to this function are this Picture and the ImageElement'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 Also

Methods

Redraw()

Redraws a Picture, which can be useful if the backing Element has changed.

Declaration
public void Redraw()
Remarks

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.

ReloadSource()

Attempts to reload a Source image.

Declaration
public void ReloadSource()
Remarks

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.

Implements