PictureFillFormat Class

Namespace:
GemBox.Spreadsheet.Drawing
Assembly:
GemBox.Spreadsheet.dll

Represents a fill with a picture that can either be tiled (as a texture) or stretched to fill the available area. This fill is not supported for outlines, borders and underlines.

public sealed class PictureFillFormat : FillFormat
Public NotInheritable Class PictureFillFormat
    Inherits FillFormat
Inheritance:
System.Object
PictureFillFormat

Properties

CropBottom

Gets or sets the offset (inset if the value is positive or outset if the value is negative) of the bottom edge of the picture Source specified as a relative value (percentage of the picture source height, value of 1 is equal to 100% of the picture source height).

public double CropBottom { get; set; }
Public Property CropBottom As Double
Property Value
System.Double

The offset (inset if the value is positive or outset if the value is negative) of bottom top edge of the picture Source.

Remarks

To reverse the effect of extra stretching caused because cropped picture source is stretched, increment the StretchBottom by the CropBottom.

To inset the stretched picture source into the filling area you can either set the StretchBottom to a positive value or CropBottom to a negative value depending on which size you choose to use as a basis (StretchBottom uses filling area height as a basis and CropBottom uses picture source height as a basis).

To outset the stretched picture source outside of the filling area you can either set the StretchBottom to a negative value or CropBottom to a positive value depending on which size you choose to use as a basis (StretchBottom uses filling area height as a basis and CropBottom uses picture source height as a basis).

If the picture is tiled (TileAsTexture is true), then cropped parts of the picture source are covered by the adjacent tiles and all tiles consist of the non-cropped part of the picture source.

CropLeft

Gets or sets the offset (inset if the value is positive or outset if the value is negative) of the left edge of the picture Source specified as a relative value (percentage of the picture source width, value of 1 is equal to 100% of the picture source width).

public double CropLeft { get; set; }
Public Property CropLeft As Double
Property Value
System.Double

The offset (inset if the value is positive or outset if the value is negative) of the left edge of the picture Source.

Remarks

To reverse the effect of extra stretching caused because cropped picture source is stretched, increment the StretchLeft by the CropLeft.

To inset the stretched picture source into the filling area you can either set the StretchLeft to a positive value or CropLeft to a negative value depending on which size you choose to use as a basis (StretchLeft uses filling area width as a basis and CropLeft uses picture source width as a basis).

To outset the stretched picture source outside of the filling area you can either set the StretchLeft to a negative value or CropLeft to a positive value depending on which size you choose to use as a basis (StretchLeft uses filling area width as a basis and CropLeft uses picture source width as a basis).

If the picture is tiled (TileAsTexture is true), then cropped parts of the picture source are covered by the adjacent tiles and all tiles consist of the non-cropped part of the picture source.

CropRight

Gets or sets the offset (inset if the value is positive or outset if the value is negative) of the right edge of the picture Source specified as a relative value (percentage of the picture source width, value of 1 is equal to 100% of the picture source width).

public double CropRight { get; set; }
Public Property CropRight As Double
Property Value
System.Double

The offset (inset if the value is positive or outset if the value is negative) of the right edge of the picture Source.

Remarks

To reverse the effect of extra stretching caused because cropped picture source is stretched, increment the StretchRight by the CropRight.

To inset the stretched picture source into the filling area you can either set the StretchRight to a positive value or CropRight to a negative value depending on which size you choose to use as a basis (StretchRight uses filling area width as a basis and CropRight uses picture source width as a basis).

To outset the stretched picture source outside of the filling area you can either set the StretchRight to a negative value or CropRight to a positive value depending on which size you choose to use as a basis (StretchRight uses filling area width as a basis and CropRight uses picture source width as a basis).

If the picture is tiled (TileAsTexture is true), then cropped parts of the picture source are covered by the adjacent tiles and all tiles consist of the non-cropped part of the picture source.

CropTop

Gets or sets the offset (inset if the value is positive or outset if the value is negative) of the top edge of the picture Source specified as a relative value (percentage of the picture source height, value of 1 is equal to 100% of the picture source height).

public double CropTop { get; set; }
Public Property CropTop As Double
Property Value
System.Double

The offset (inset if the value is positive or outset if the value is negative) of the top edge of the picture Source.

Remarks

To reverse the effect of extra stretching caused because cropped picture source is stretched, increment the StretchTop by the CropTop.

To inset the stretched picture source into the filling area you can either set the StretchTop to a positive value or CropTop to a negative value depending on which size you choose to use as a basis (StretchTop uses filling area height as a basis and CropTop uses picture source height as a basis).

To outset the stretched picture source outside of the filling area you can either set the StretchTop to a negative value or CropTop to a positive value depending on which size you choose to use as a basis (StretchTop uses filling area height as a basis and CropTop uses picture source height as a basis).

If the picture is tiled (TileAsTexture is true), then cropped parts of the picture source are covered by the adjacent tiles and all tiles consist of the non-cropped part of the picture source.

FillType

Gets the Picture value.

public override FillFormatType FillType { get; }
Public Overrides ReadOnly Property FillType As FillFormatType
Property Value
FillFormatType

The Picture value.

Overrides

RotateWithShape

Gets or sets a value indicating whether the fill should rotate with the shape.

Default value: true.

public bool RotateWithShape { get; set; }
Public Property RotateWithShape As Boolean
Property Value
System.Boolean

true if fill should rotate with the shape; otherwise, false.

Remarks

If set to true and a shape that has been filled with a picture is transformed with a rotation, then the fill will be transformed with the same rotation.

Source

Gets the picture source that has an associated content that is either embedded in or linked to the workbook file.

public PictureContent Source { get; }
Public ReadOnly Property Source As PictureContent
Property Value
PictureContent

The picture source that has an associated content that is either embedded in or linked to the workbook file.

StretchBottom

Gets or sets the offset (inset if the value is positive or outset if the value is negative) of the bottom edge of the stretched picture fill from the bottom edge of the filling area specified as a relative value (percentage of the filling area height, value of 1 is equal to 100% of the filling area height).

public double StretchBottom { get; set; }
Public Property StretchBottom As Double
Property Value
System.Double

The offset (inset if the value is positive or outset if the value is negative) of the bottom edge of the stretched picture fill from the bottom edge of the filling area.

StretchLeft

Gets or sets the offset (inset if the value is positive or outset if the value is negative) of the left edge of the stretched picture fill from the left edge of the filling area specified as a relative value (percentage of the filling area width, value of 1 is equal to 100% of the filling area width).

public double StretchLeft { get; set; }
Public Property StretchLeft As Double
Property Value
System.Double

The offset (inset if the value is positive or outset if the value is negative) of the left edge of the stretched picture fill from the left edge of the filling area.

StretchRight

Gets or sets the offset (inset if the value is positive or outset if the value is negative) of the right edge of the stretched picture fill from the right edge of the filling area specified as a relative value (percentage of the filling area width, value of 1 is equal to 100% of the filling area width).

public double StretchRight { get; set; }
Public Property StretchRight As Double
Property Value
System.Double

The offset (inset if the value is positive or outset if the value is negative) of the right edge of the stretched picture fill from the right edge of the filling area.

StretchTop

Gets or sets the offset (inset if the value is positive or outset if the value is negative) of the top edge of the stretched picture fill from the top edge of the filling area specified as a relative value (percentage of the filling area height, value of 1 is equal to 100% of the filling area height).

public double StretchTop { get; set; }
Public Property StretchTop As Double
Property Value
System.Double

The offset (inset if the value is positive or outset if the value is negative) of the top edge of the stretched picture fill from the top edge of the filling area.

TileAsTexture

Gets or sets a value indicating whether the fill should tile as a texture or stretch over the filling area.

public bool TileAsTexture { get; set; }
Public Property TileAsTexture As Boolean
Property Value
System.Boolean

true if fill should tile as a texture; otherwise, false to stretch it over the filling area.

TilingAlignment

Gets or sets a value indicating where to align the first tile with respect to the filling area.

Alignment happens after the scaling, but before the additional offset.

public RectangleAlignment TilingAlignment { get; set; }
Public Property TilingAlignment As RectangleAlignment
Property Value
RectangleAlignment

A value indicating where to align the first tile with respect to the filling area.

TilingMirrorType

Specifies the direction(s) in which to flip the source image while tiling.

Images may be flipped horizontally, vertically, or in both directions to fill the entire region.

public TileMirrorTypes TilingMirrorType { get; set; }
Public Property TilingMirrorType As TileMirrorTypes
Property Value
TileMirrorTypes

The direction(s) in which to flip the source image while tiling.

TilingMode

Gets or sets the value indicating how picture tiles are painted onto a chart element output area.

This property can be set only on ChartSeries and DataPoint elements of BarChart and ColumnChart.

Default value: Default.

public PictureTileMode TilingMode { get; set; }
Public Property TilingMode As PictureTileMode
Property Value
PictureTileMode

The value indicating how picture tiles are painted onto a chart element output area.

Remarks

If the TilingMode is Stack, then all other PictureFillFormat properties are ignored.

If the TilingMode is StackAndScale, then all PictureFillFormat properties except TilingStackUnit are ignored.

Exceptions
System.InvalidOperationException

Non-Default tiling mode can be set only on ChartSeries and DataPoint elements of BarChart and ColumnChart.

TilingOffsetX

Gets or sets the additional horizontal offset after tiling alignment.

public Length TilingOffsetX { get; set; }
Public Property TilingOffsetX As Length
Property Value
Length

The additional horizontal offset after tiling alignment.

TilingOffsetY

Gets or sets the additional vertical offset after tiling alignment.

public Length TilingOffsetY { get; set; }
Public Property TilingOffsetY As Length
Property Value
Length

The additional vertical offset after tiling alignment.

TilingScaleX

Gets or sets the horizontal tiling scale in range from 0 = 0% to 1 = 100%.

public double TilingScaleX { get; set; }
Public Property TilingScaleX As Double
Property Value
System.Double

The horizontal tiling scale.

TilingScaleY

Gets or sets the vertical tiling scale in range from 0 = 0% to 1 = 100%.

public double TilingScaleY { get; set; }
Public Property TilingScaleY As Double
Property Value
System.Double

The vertical tiling scale.

TilingStackUnit

Gets or sets the value to which picture tiles are scaled before being stacked if TilingMode is StackAndScale; otherwise, System.Double.NaN.

This property can be set only if TilingMode is StackAndScale.

Default value: 1 if TilingMode is StackAndScale; otherwise, System.Double.NaN.

public double TilingStackUnit { get; set; }
Public Property TilingStackUnit As Double
Property Value
System.Double

The value to which picture tiles are scaled before being stacked if TilingMode is StackAndScale; otherwise, System.Double.NaN.

Exceptions
System.InvalidOperationException

Methods

SetSource(Content)

Sets the picture source.

public PictureContent SetSource(Content content)
Public Function SetSource(content As Content) As PictureContent
Parameters
content
Content

The picture content that should be set.

Returns
PictureContent

An instance of a PictureContent class that represents the picture source that has been set.

Remarks

Use this overload if multiple PictureFillFormats should share the same picture source.

Exceptions
System.ArgumentNullException

content is null.

SetSource(Content, PictureCompressionType)

Sets the picture source.

public PictureContent SetSource(Content content, PictureCompressionType compressionType)
Public Function SetSource(content As Content, compressionType As PictureCompressionType) As PictureContent
Parameters
content
Content

The picture content that should be set.

compressionType
PictureCompressionType

Compression level that the generating application can use as a guidance when optimizing picture source size.

Returns
PictureContent

An instance of a PictureContent class that represents the picture source that has been set.

Remarks

Use this overload if multiple PictureFillFormats should share the same picture source but with different compression levels.

Exceptions
System.ArgumentNullException

content is null.

SetSource(Stream)

Sets the picture source.

public PictureContent SetSource(Stream stream)
Public Function SetSource(stream As Stream) As PictureContent
Parameters
stream
System.IO.Stream

Stream containing the picture source.

Returns
PictureContent

An instance of a PictureContent class that represents the picture source that has been set.

Remarks

Use this overload to automatically detect the picture content type from the decoded picture stream.

Exceptions
System.ArgumentNullException

stream is null.

System.ArgumentException

Picture stream encoding format is not supported.

SetSource(Stream, PictureContentType)

Sets the picture source.

public PictureContent SetSource(Stream stream, PictureContentType contentType)
Public Function SetSource(stream As Stream, contentType As PictureContentType) As PictureContent
Parameters
stream
System.IO.Stream

The picture source stream.

contentType
PictureContentType

Content type of the picture source.

Returns
PictureContent

An instance of a PictureContent class that represents the picture source that has been set.

Remarks

Use this overload to explicitly specify picture content type so that the picture stream doesn't have to be decoded to detect the picture content type.

Exceptions
System.ArgumentNullException

stream is null.

SetSource(Stream, String)

Sets the picture source.

public PictureContent SetSource(Stream stream, string contentType)
Public Function SetSource(stream As Stream, contentType As String) As PictureContent
Parameters
stream
System.IO.Stream

The picture source stream.

contentType
System.String

Content type (MIME type) of the picture source.

Returns
PictureContent

An instance of a PictureContent class that represents the picture source that has been set.

Remarks

Use this overload to explicitly specify picture content type that is not supported by the PictureContentType.

Exceptions
System.ArgumentNullException

stream is null.

System.ArgumentException

contentType is null or System.String.Empty.

SetSource(String, PictureContentType)

Sets the picture source.

public PictureContent SetSource(string picturePath, PictureContentType contentType)
Public Function SetSource(picturePath As String, contentType As PictureContentType) As PictureContent
Parameters
picturePath
System.String

Path to a picture source.

contentType
PictureContentType

Content type of the picture source.

Returns
PictureContent

An instance of a PictureContent class that represents the picture source that has been set.

Remarks

Use this overload to explicitly specify picture content type (for example, if picturePath doesn't specify a file extension).

Exceptions
System.ArgumentException

picturePath is null or System.String.Empty.

SetSource(String, Boolean)

Sets the picture source.

public PictureContent SetSource(string picturePath, bool isLink = false)
Public Function SetSource(picturePath As String, isLink As Boolean = False) As PictureContent
Parameters
picturePath
System.String

Path or link to a picture source.

isLink
System.Boolean

true if the picture is linked to the file in which ExcelFile instance is saved; otherwise, false.

Returns
PictureContent

An instance of a PictureContent class that represents the picture source that has been set.

Remarks

Use this overload to automatically detect the picture content type from the picturePath extension.

Parameter picturePath must contain supported extension (for example, ".png") if isLink is false, otherwise exception is thrown.

Exceptions
System.ArgumentException

picturePath is null or System.String.Empty or picturePath doesn't contain extension or extension is not supported.

SetSource(String, String)

Sets the picture source.

public PictureContent SetSource(string picturePath, string contentType)
Public Function SetSource(picturePath As String, contentType As String) As PictureContent
Parameters
picturePath
System.String

Path to a picture source.

contentType
System.String

Content type (MIME type) of the picture source.

Returns
PictureContent

An instance of a PictureContent class that represents the picture source that has been set.

Remarks

Use this overload to explicitly specify picture content type that is not supported by the PictureContentType.

Exceptions
System.ArgumentException

picturePath or contentType is null or System.String.Empty.

Inherited Methods

SetGradient(GradientFillType)

Sets the fill to the gradient fill.

(Inherited from FillFormat)

SetNone()

Sets the fill to none, thus making the area transparent.

(Inherited from FillFormat)

SetPattern(PatternFillType, DrawingColor, DrawingColor)

Sets the fill to the pattern fill.

(Inherited from FillFormat)

SetPicture(Content)

Sets the fill to the picture fill.

This method is not applicable on Fill property.

(Inherited from FillFormat)

SetPicture(System.IO.Stream)

Sets the fill to the picture fill.

This method is not applicable on Fill property.

(Inherited from FillFormat)

SetPicture(System.IO.Stream, PictureContentType)

Sets the fill to the picture fill.

This method is not applicable on Fill property.

(Inherited from FillFormat)

SetPicture(System.IO.Stream, System.String)

Sets the fill to the picture fill.

This method is not applicable on Fill property.

(Inherited from FillFormat)

SetPicture(System.String, System.Boolean)

Sets the fill to the picture fill.

This method is not applicable on Fill property.

(Inherited from FillFormat)

SetPicture(System.String, PictureContentType)

Sets the fill to the picture fill.

This method is not applicable on Fill property.

(Inherited from FillFormat)

SetPicture(System.String, System.String)

Sets the fill to the picture fill.

This method is not applicable on Fill property.

(Inherited from FillFormat)

SetSolid(DrawingColor)

Sets the fill to the solid fill.

(Inherited from FillFormat)