Class ImageContent

Represents an image element within the document.

Inheritance

System.Object

ContentElement

ImageContent

Implements

IWordImageObject

IronSoftware.Abstractions.Word.IImage

IronSoftware.Abstractions.Word.IWordDocumentObject

IronSoftware.Abstractions.IDocumentObject

System.ICloneable

IronSoftware.Abstractions.Word.IWordAbsolute

IronSoftware.Abstractions.IAbsolute

IronSoftware.Abstractions.IJsonSerializable

Inherited Members

ContentElement.Replace(IWordDocumentObject)

ContentElement.Remove()

ContentElement.GetIndex<T>()

ContentElement.Clone()

ContentElement.CloneObject()

ContentElement.Parent

ContentElement.Status

Namespace: IronWord.Models

Assembly: IronWord.dll

Syntax

public class ImageContent : ContentElement, IWordImageObject

A picture inside a Word document, its bytes, size, and placement, lives on ImageContent in C#. It is the image element the document model exposes when you read a document's pictures back, and it carries everything needed to inspect or reposition that picture. It implements IWordImageObject, so code that walks document content can handle it through that contract. It is the read-side counterpart of Image, the element a developer builds when authoring a new picture.

Reach an ImageContent by enumerating the images in an already-loaded document, or construct one from a file path, a Stream, or an IronSoftware.Drawing.AnyBitmap to insert a picture. Like every other element it derives from ContentElement, so it shares the common Index, Parent, and removal behavior of the document tree, and its Image property holds the underlying IAnyImage that backs it.

Size and place the picture with Width, Height, and Position (an ElementPosition), and read BoundingBox (a RectangleF) for its absolute rectangle on the page. The GetWidth(MeasurementUnit) and GetDistanceFromTop(MeasurementUnit) family return those measurements in inches, centimeters, or points. Type reports the ImageType, Name and Id identify the picture, ImageData exposes the Base64 bytes, and TextWrapBehavior, ZOrder, and ZPosition govern how it layers against the surrounding text. LoadFromFile(String) and LoadFromStream(Stream) replace the image data after construction, which lets the same element point at a different picture without rebuilding the surrounding content. Adjusting DistanceFromTop, DistanceFromLeft, and their siblings sets the gap the picture keeps from nearby text, so a caption or paragraph does not crowd the image once the document is saved.

var doc = new WordDocument("report.docx");
foreach (ImageContent picture in doc.ExtractImages())
{
    double widthInches = picture.GetWidth(MeasurementUnit.Inch);
    Console.WriteLine($"{picture.Name}: {widthInches} in");
}

The extract images how-to reads each picture, the add image how-to inserts one, and the add image example has a worked listing.

Constructors

ImageContent()

Initializes a new instance of the Image class.

Declaration

public ImageContent()

ImageContent(AnyBitmap)

Initializes a new instance of the Image class using an IronSoftware.Drawing.AnyBitmap object.

Declaration

public ImageContent(AnyBitmap anyBitmap)

Parameters

Type	Name	Description
IronSoftware.Drawing.AnyBitmap	anyBitmap	An IronSoftware.Drawing.AnyBitmap object representing the image data.

ImageContent(Stream)

Initializes a new instance of the Image class with the specified image data stream.

Declaration

public ImageContent(Stream imageStream)

Parameters

Type	Name	Description
System.IO.Stream	imageStream	The stream containing the image data.

ImageContent(String)

Initializes a new instance of the Image class with the specified image path.

Declaration

public ImageContent(string imagePath)

Parameters

Type	Name	Description
System.String	imagePath	The path to the image file.

Properties

BoundingBox

The bounding box of the image.

Declaration

public RectangleF BoundingBox { get; set; }

Property Value

Type	Description
System.Drawing.RectangleF

Remarks

The X and Y coordinates of the bounding box represent its absolute position on the page of a document.

DistanceFromBottom

Gets or sets the minimum distance from the bottom edge of the image and text, in points.

Declaration

public double DistanceFromBottom { get; set; }

Property Value

Type	Description
System.Double

DistanceFromLeft

Gets or sets the minimum distance from the left edge of the image and text, in points.

Declaration

public double DistanceFromLeft { get; set; }

Property Value

Type	Description
System.Double

DistanceFromRight

Gets or sets the minimum distance from the right edge of the image and text, in points.

Declaration

public double DistanceFromRight { get; set; }

Property Value

Type	Description
System.Double

DistanceFromTop

Gets or sets the minimum distance between the top edge of the image and text, in points.

Declaration

public double DistanceFromTop { get; set; }

Property Value

Type	Description
System.Double

Height

Gets or sets the height of the image in pixels measured in points (1 inch = 72 points).

Declaration

public double Height { get; set; }

Property Value

Type	Description
System.Double

HorizontalRelativePositionOrigin

The horizontal relative position origin for the image.

Declaration

public HorizontalRelativePositionOrigin HorizontalRelativePositionOrigin { get; set; }

Property Value

Type	Description
IronSoftware.Abstractions.Word.HorizontalRelativePositionOrigin

Id

Gets or sets a unique identifier for the image.

Declaration

public uint Id { get; set; }

Property Value

Type	Description
System.UInt32

Image

Declaration

public IAnyImage Image { get; set; }

Property Value

Type	Description
IronSoftware.Abstractions.IAnyImage

ImageData

Gets or sets the Base64-encoded image data.

Declaration

public string ImageData { get; }

Property Value

Type	Description
System.String

Index

Gets the index of this image within the parent's list of children.

Declaration

public int Index { get; set; }

Property Value

Type	Description
System.Int32

Name

Gets or sets the name of the image file, if applicable.

Declaration

public string Name { get; set; }

Property Value

Type	Description
System.String

Position

Gets or sets the position of the image within the document measured in points (1 inch = 72 points).

Declaration

public ElementPosition Position { get; set; }

Property Value

Type	Description
ElementPosition

TextWrapBehavior

Declaration

public ITextWrapBehavior TextWrapBehavior { get; set; }

Property Value

Type	Description
IronSoftware.Abstractions.Word.ITextWrapBehavior

Type

Gets or sets the image format.

Declaration

public ImageType Type { get; set; }

Property Value

Type	Description
ImageType

VerticalRelativePositionOrigin

The vertical relative position origin for the image.

Declaration

public VerticalRelativePositionOrigin VerticalRelativePositionOrigin { get; set; }

Property Value

Type	Description
IronSoftware.Abstractions.Word.VerticalRelativePositionOrigin

Width

Gets or sets the width of the image in points (1 inch = 72 points).

Declaration

public double Width { get; set; }

Property Value

Type	Description
System.Double

ZOrder

Declaration

public RelativeZOrder ZOrder { get; set; }

Property Value

Type	Description
IronSoftware.Abstractions.RelativeZOrder

ZPosition

Declaration

public long ZPosition { get; set; }

Property Value

Type	Description
System.Int64

Methods

GetDistanceFromBottom(MeasurementUnit)

Get the minimum distance from the bottom edge of the image and text.

Declaration

public double GetDistanceFromBottom(MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
MeasurementUnit	measurementUnit	The unit of measurement for the distance.

Returns

Type	Description
System.Double

GetDistanceFromLeft(MeasurementUnit)

Get the minimum distance between the left edge of the image and text.

Declaration

public double GetDistanceFromLeft(MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
MeasurementUnit	measurementUnit	The unit of measurement for the distance.

Returns

Type	Description
System.Double

GetDistanceFromRight(MeasurementUnit)

Get the minimum distance between the right edge of the image and text.

Declaration

public double GetDistanceFromRight(MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
MeasurementUnit	measurementUnit	The unit of measurement for the distance.

Returns

Type	Description
System.Double

GetDistanceFromTop(MeasurementUnit)

Get the minimum distance between the top edge of the image and text.

Declaration

public double GetDistanceFromTop(MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
MeasurementUnit	measurementUnit	The unit of measurement for the distance.

Returns

Type	Description
System.Double

GetHeight(MeasurementUnit)

Get image height.

Declaration

public double GetHeight(MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
MeasurementUnit	measurementUnit	The unit of measurement to return the value in.

Returns

Type	Description
System.Double	Image height in specified measurement unit.

GetWidth(MeasurementUnit)

Get image width.

Declaration

public double GetWidth(MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
MeasurementUnit	measurementUnit	The unit of measurement to return the value in.

Returns

Type	Description
System.Double	Image width in specified measurement unit.

LoadFromFile(String)

Loads an image from the specified file path.

Declaration

public void LoadFromFile(string imagePath)

Parameters

Type	Name	Description
System.String	imagePath	The file path of the image to be loaded.

Remarks

This method attempts to load an image from the specified file path. If the file is not found, a System.IO.FileNotFoundException is thrown. Any other exceptions during the loading process are wrapped in an ImageLoadException.

Exceptions

Type	Condition
System.IO.FileNotFoundException	Thrown if the specified image file is not found.
ImageLoadException	Thrown if there is an error loading the image.

LoadFromStream(Stream)

Loads an image from the stream.

Declaration

public void LoadFromStream(Stream stream)

Parameters

Type	Name	Description
System.IO.Stream	stream	The stream to be loaded.

Remarks

This method attempts to load an image from the specified file path. If the file is not found, a System.IO.FileNotFoundException is thrown. Any other exceptions during the loading process are wrapped in an ImageLoadException.

Exceptions

Type	Condition
ImageLoadException	Thrown if there is an error loading the image.

SetDistanceFromBottom(Double, MeasurementUnit)

Set the minimum distance between the bottom edge of the image and text.

Declaration

public void SetDistanceFromBottom(double distanceFromBottom, MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
System.Double	distanceFromBottom	The distance value.
MeasurementUnit	measurementUnit	The unit of measurement for the distance.

SetDistanceFromLeft(Double, MeasurementUnit)

Set the minimum distance between the left edge of the image and text.

Declaration

public void SetDistanceFromLeft(double distanceFromLeft, MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
System.Double	distanceFromLeft	The distance value.
MeasurementUnit	measurementUnit	The unit of measurement for the distance.

SetDistanceFromRight(Double, MeasurementUnit)

Set the minimum distance between the right edge of the image and text.

Declaration

public void SetDistanceFromRight(double distanceFromRight, MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
System.Double	distanceFromRight	The distance value.
MeasurementUnit	measurementUnit	The unit of measurement for the distance.

SetDistanceFromTop(Double, MeasurementUnit)

Set the minimum distance between the top edge of the image and text.

Declaration

public void SetDistanceFromTop(double distanceFromTop, MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
System.Double	distanceFromTop	The distance value.
MeasurementUnit	measurementUnit	The unit of measurement for the distance.

SetHeight(Double, MeasurementUnit)

Set image height.

Declaration

public void SetHeight(double height, MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
System.Double	height	The desired height for the image.
MeasurementUnit	measurementUnit	The unit of measurement for the height.

SetWidth(Double, MeasurementUnit)

Set image width.

Declaration

public void SetWidth(double width, MeasurementUnit measurementUnit)

Parameters

Type	Name	Description
System.Double	width	The desired width for the image.
MeasurementUnit	measurementUnit	The unit of measurement for the width.

ToJson()

Declaration

public string ToJson()

Returns

Type	Description
System.String

Implements

IWordImageObject

IronSoftware.Abstractions.Word.IImage

IronSoftware.Abstractions.Word.IWordDocumentObject

IronSoftware.Abstractions.IDocumentObject

System.ICloneable

IronSoftware.Abstractions.Word.IWordAbsolute

IronSoftware.Abstractions.IAbsolute

IronSoftware.Abstractions.IJsonSerializable

Inherited members

Replace(IWordDocumentObject)

Remove()

GetIndex<T>()

Clone()

CloneObject()

Parent

Status