Class: PictureShape

Sheets.Shapes.PictureShape

Hierarchy

• ShapeBase

  ↳ PictureShape

Table of contents

Constructors

• constructor

Methods

• allowMove
• allowResize
• allowRotate
• alt
• canPrint
• dynamicMove
• dynamicSize
• endColumn
• endColumnOffset
• endRow
• endRowOffset
• geometryType
• getFormula
• getOriginalHeight
• getOriginalWidth
• height
• hyperlink
• isLocked
• isSelected
• isVisible
• name
• pictureFormat
• rotate
• setFormula
• showHandle
• src
• startColumn
• startColumnOffset
• startRow
• startRowOffset
• style
• toImageSrc
• width
• x
• y

Constructors

constructor

• new PictureShape(worksheet, name, src, left?, top?, width?, height?)

Parameters

Name	Type	Description
worksheet	Worksheet	The host worksheet of the shape.
name	string	The name of the picture shape. If name is empty string, a unique name will be generated.
src	string	The src of the picture.
left?	number	-
top?	number	-
width?	number	-
height?	number	-

Overrides

ShapeBase.constructor

Methods

allowMove

▸ allowMove(value?): any

Gets or sets whether to disable moving the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var state = heart.allowMove();
heart.allowMove(!state);

Parameters

Name	Type	Description
value?	boolean	The setting for whether to disable moving the shape.

Returns

any

If no value is set, returns the setting for whether to disable moving the shape.

Inherited from

ShapeBase.allowMove

---

allowResize

▸ allowResize(value?): any

Gets or sets the resize mode of the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var state = heart.allowResize();
heart.allowResize(GC.Spread.Sheets.Shapes.ResizeMode.aspect);

Parameters

Name	Type	Description
value?	boolean | ResizeMode	The setting for whether to disable resizing the shape.

Returns

any

If no value is set, returns the setting for whether to disable resizing the shape.

Inherited from

ShapeBase.allowResize

---

allowRotate

▸ allowRotate(value?): any

Gets or sets whether to disable rotating the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var state = heart.allowRotate();
heart.allowRotate(!state);

Parameters

Name	Type	Description
value?	boolean	The setting for whether to disable rotating the shape.

Returns

any

If no value is set, returns the setting for whether to disable rotating the shape.

Inherited from

ShapeBase.allowRotate

---

alt

▸ alt(value?): any

Gets or sets the alternative text of the shape for screen readers.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
heart.alt("A heart shape");

Parameters

Name	Type
value?	string

Returns

any

The alternative text of the shape.

Inherited from

ShapeBase.alt

---

canPrint

▸ canPrint(value?): any

Gets or sets whether this shape is printable.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var state = heart.canPrint(); // Get whether the shape is printable, defaulat value is true.
workbook.print(); // The heart shape is printed.
heart.canPrint(false);
workbook.print(); // The heart shape is not printed.

Parameters

Name	Type
value?	boolean

Returns

any

If no value is set, returns whether this shape is printable.

Inherited from

ShapeBase.canPrint

---

dynamicMove

▸ dynamicMove(value?): any

Gets or sets whether the shape moves when hiding or showing, resizing, or moving rows or columns.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var state = heart.dynamicMove();
heart.dynamicMove(!state);

Parameters

Name	Type	Description
value?	boolean	The value indicates whether the shape moves when hiding or showing, resizing, or moving rows or columns.

Returns

any

If no value is set, returns whether this shape dynamically moves.

Inherited from

ShapeBase.dynamicMove

---

dynamicSize

▸ dynamicSize(value?): any

Gets or sets whether the size of the shape changes when hiding or showing, resizing, or moving rows or columns.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var state = heart.dynamicSize();
heart.dynamicSize(!state);

Parameters

Name	Type	Description
value?	boolean	The value indicates whether the size of the shape changes when hiding or showing, resizing, or moving rows or columns.

Returns

any

If no value is set, returns whether this shape dynamically changes size.

Inherited from

ShapeBase.dynamicSize

---

endColumn

▸ endColumn(value?): any

Gets or sets the end column index of the shape position.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.endColumn();
heart.endColumn(n + 1);

Parameters

Name	Type	Description
value?	number	The end column index of the shape position.

Returns

any

If no value is set, returns the end column index of the shape position.

Inherited from

ShapeBase.endColumn

---

endColumnOffset

▸ endColumnOffset(value?): any

Gets or sets the offset relative to the end column of the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.endColumnOffset();
heart.endColumnOffset(0);

Parameters

Name	Type	Description
value?	number	The offset relative to the end column of the shape.

Returns

any

If no value is set, returns the offset relative to the end column of the shape.

Inherited from

ShapeBase.endColumnOffset

---

endRow

▸ endRow(value?): any

Gets or sets the end row index of the shape position.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.endRow();
heart.endRow(n + 2);

Parameters

Name	Type	Description
value?	number	The end row index of the shape position.

Returns

any

If no value is set, returns the end row index of the shape position.

Inherited from

ShapeBase.endRow

---

endRowOffset

▸ endRowOffset(value?): any

Gets or sets the offset relative to the end row of the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.endRowOffset();
heart.endRowOffset(0);

Parameters

Name	Type	Description
value?	number	The offset relative to the end row of the shape.

Returns

any

If no value is set, returns the offset relative to the end row of the shape.

Inherited from

ShapeBase.endRowOffset

---

geometryType

▸ geometryType(value?): void | AutoShapeType

Gets or sets the geometry type of the picture.

example

//This sample sets geometry type for the picture shape.
var shape = sheet.shapes.addPictureShape("Picture 1", "data:image/svg+xml;base64.....", 100, 50, 100, 100);
shape.geometryType(GC.Spread.Sheets.Shapes.AutoShapeType.oval);

Parameters

Name	Type
value?	AutoShapeType

Returns

void | AutoShapeType

If no value is set, returns the current geometry type of the picture.

---

getFormula

▸ getFormula(path): string

Gets the formula string from the shape by the path.

example

sheet.name("Sheet1");
sheet.setValue(0, 1, 150);
var shape1 = sheet.shapes.add("myShape1", GC.Spread.Sheets.Shapes.AutoShapeType.rectangle, 100, 100, 200, 200);
shape1.setFormula("x", "=Sheet1!B1");
shape1.getFormula("x");//returns "=Sheet1!B1"

Parameters

Name	Type	Description
path	string	The path which can accept a formula string, it could be one of "x", "y", "width", "height".

Returns

string

Returns the formula string from the shape by the path.

Inherited from

ShapeBase.getFormula

---

getOriginalHeight

▸ getOriginalHeight(): undefined | number

Gets the original height of the image.

example

sheet.bind(GC.Spread.Sheets.Events.ShapeChanged, function(s, e) {
    if (e.propertyName === "originalSize") {
        // Set the size of the picture shape to the original size of the image.
        e.shape.width(e.shape.getOriginalWidth());
        e.shape.height(e.shape.getOriginalHeight());
    }
});
var src = "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/Pjxzdmcgd2lkdGg9IjEwMCIgaGVpZ2h0PSIxMDAiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iYmx1ZSIvPjxwYXRoIGQ9Ik0xMCw1MCBRNDAsMzAgNTAsNTAgVDkwLDUwIiBmaWxsPSJub25lIiBzdHJva2U9Im9yYW5nZSIgc3Ryb2tlLXdpZHRoPSI1Ii8+PC9zdmc+";
var shape = sheet.shapes.addPictureShape("Picture 1", src, 100, 50, 200, 200);

Returns

undefined | number

returns original height of the image, if no image or the image did not finish loading, undefiend is returned.

---

getOriginalWidth

▸ getOriginalWidth(): undefined | number

Gets the original width of the image.

example

sheet.bind(GC.Spread.Sheets.Events.ShapeChanged, function(s, e) {
    if (e.propertyName === "originalSize") {
        // Set the size of the picture shape to the original size of the image.
        e.shape.width(e.shape.getOriginalWidth());
        e.shape.height(e.shape.getOriginalHeight());
    }
});
var src = "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/Pjxzdmcgd2lkdGg9IjEwMCIgaGVpZ2h0PSIxMDAiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iYmx1ZSIvPjxwYXRoIGQ9Ik0xMCw1MCBRNDAsMzAgNTAsNTAgVDkwLDUwIiBmaWxsPSJub25lIiBzdHJva2U9Im9yYW5nZSIgc3Ryb2tlLXdpZHRoPSI1Ii8+PC9zdmc+";
var shape = sheet.shapes.addPictureShape("Picture 1", src, 100, 50, 200, 200);

Returns

undefined | number

returns original width of the image, if no image or the image did not finish loading, undefiend is returned.

---

height

▸ height(value?): any

Gets or sets the height of the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.height();
heart.height(n + 50);

Parameters

Name	Type	Description
value?	string | number	The height of the shape specified by a number or formula (starts with =) can get a number value.

Returns

any

If no value is set, returns the height of the shape.

Inherited from

ShapeBase.height

---

hyperlink

▸ hyperlink(value?): void | IHyperlink

Gets or sets the hyperlink of the shape.

example

var shape = sheet.shapes.add("myShape", GC.Spread.Sheets.Shapes.AutoShapeType.rectangle, 62 * 9, 0, 200, 200);
shape.hyperlink({url: "http://www.spreadjs.com", target: 0, tooltip: 'goes to SpreadJS'});

Parameters

Name	Type
value?	IHyperlink

Returns

void | IHyperlink

If no value is set, returns the current hyperlink settings of the shape.

Inherited from

ShapeBase.hyperlink

---

isLocked

▸ isLocked(value?): any

Gets or sets whether this shape is locked.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var state = heart.isLocked();
heart.isLocked(!state);

Parameters

Name	Type	Description
value?	boolean	The value that indicates whether this shape is locked.

Returns

any

If no value is set, returns whether this shape is locked.

Inherited from

ShapeBase.isLocked

---

isSelected

▸ isSelected(value?): any

Gets or sets whether this shape is selected.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var state = heart.isSelected();
heart.isSelected(!state);

Parameters

Name	Type	Description
value?	boolean	The value that indicates whether this shape is selected.

Returns

any

If no value is set, returns whether this shape is selected.

Inherited from

ShapeBase.isSelected

---

isVisible

▸ isVisible(value?): any

Gets or sets whether this shape is visible.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var state = heart.isVisible();
heart.isVisible(!state);

Parameters

Name	Type	Description
value?	boolean	The value that indicates whether this shape is visible.

Returns

any

If no value is set, returns whether this shape is visible.

Inherited from

ShapeBase.isVisible

---

name

▸ name(value?): any

Gets or sets the name of the shape.

example

var shape1 = sheet.shapes.add("myShape1", GC.Spread.Sheets.Shapes.AutoShapeType.rectangle, 62 * 9, 0, 200, 200);
var shape2 = sheet.shapes.add("myShape2", GC.Spread.Sheets.Shapes.AutoShapeType.rectangle, 20, 20, 200, 200);
var shape = sheet.shapes.group([shape1, shape2]);
shape.name("myGroupShape");
var shapeName = shape.name();

Parameters

Name	Type	Description
value?	string	The name of the shape.

Returns

any

If no value is set, returns the name of the shape.

Inherited from

ShapeBase.name

---

pictureFormat

▸ pictureFormat(value?): void | IPictureFormat

Gets or sets the format of the picture.

example

//This sample sets format for the picture shape.
var shape = sheet.shapes.addPictureShape("Picture 1", "data:image/svg+xml;base64.....", 100, 50, 100, 100);
shape.pictureFormat({ grayscale: true, crop: { left: 0.25, right: 0.25, top: 0.25, bottom: 0.25 }});

Parameters

Name	Type
value?	IPictureFormat

Returns

void | IPictureFormat

If no value is set, returns the current format of the picture.

---

rotate

▸ rotate(value?): number | void

Gets or sets the rotated angle of the picture shape (unit in degree).

example

var shape = sheet.shapes.addPictureShape("Picture 1", "data:image/svg+xml;base64.....", 100, 50, 100, 100);
var n = shape.rotate();
shape.rotate(n + 30);

Parameters

Name	Type	Description
value?	string | number	The rotated angle of the picture shape (unit in degree) specified by a number or formula (starts with =) can get a number value.

Returns

number | void

If no value is set, returns the rotated angle of the picture shape (unit in degree).

---

setFormula

▸ setFormula(path, formula): void

Sets the formula string to the shape by the path.

example

sheet.name("Sheet1");
sheet.setValue(0, 1, 150);
var shape1 = sheet.shapes.add("myShape1", GC.Spread.Sheets.Shapes.AutoShapeType.rectangle, 100, 100, 200, 200);
shape1.setFormula("x", "=Sheet1!B1");

Parameters

Name	Type	Description
path	string	The path which can accept a formula string, it could be one of "x", "y", "width", "height".
formula	string	The formula string.

Returns

void

Inherited from

ShapeBase.setFormula

---

showHandle

▸ showHandle(value?): any

Gets or sets whether to show handle of shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var state = heart.showHandle();
heart.showHandle(!state);

Parameters

Name	Type	Description
value?	boolean	The setting for whether to show handle of shape.

Returns

any

If no value is set, returns the setting for whether to show handle of shape.

Inherited from

ShapeBase.showHandle

---

src

▸ src(value?): string | void

Gets or sets the src of the picture.

example

var dataURL = "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/Pjxzdmcgd2lkdGg9IjEwMCIgaGVpZ2h0PSIxMDAiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iYmx1ZSIvPjxwYXRoIGQ9Ik0xMCw1MCBRNDAsMzAgNTAsNTAgVDkwLDUwIiBmaWxsPSJub25lIiBzdHJva2U9Im9yYW5nZSIgc3Ryb2tlLXdpZHRoPSI1Ii8+PC9zdmc+";
var shape = sheet.shapes.addPictureShape("Picture 1", dataURL, 100, 50, 200, 200);
// get current image source, the src is equal to dataURL.
var src = shape.src();
// set new image source.
shape.src("data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/Pjxzdmcgd2lkdGg9IjEwMCIgaGVpZ2h0PSIxMDAiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iYmxhY2siLz48cGF0aCBkPSJNMTAsNTAgUTQwLDMwIDUwLDUwIFQ5MCw1MCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJvcmFuZ2UiIHN0cm9rZS13aWR0aD0iNSIvPjwvc3ZnPg==");

Parameters

Name	Type
value?	string

Returns

string | void

If no value is set, returns the current src of the picture.

---

startColumn

▸ startColumn(value?): any

Gets or sets the starting column index of the shape position.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.startColumn();
heart.startColumn(n + 2);

Parameters

Name	Type	Description
value?	number	The starting column index of the shape position.

Returns

any

If no value is set, returns the starting column index of the shape position.

Inherited from

ShapeBase.startColumn

---

startColumnOffset

▸ startColumnOffset(value?): any

Gets or sets the offset relative to the start column of the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.startColumnOffset();
heart.startColumnOffset(0);

Parameters

Name	Type	Description
value?	number	The offset relative to the start column of the shape.

Returns

any

If no value is set, returns the offset relative to the start column of the shape.

Inherited from

ShapeBase.startColumnOffset

---

startRow

▸ startRow(value?): any

Gets or sets the starting row index of the shape position.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.startRow();
heart.startRow(n + 2);

Parameters

Name	Type	Description
value?	number	The starting row index of the shape position.

Returns

any

If no value is set, returns the starting row index of the shape.

Inherited from

ShapeBase.startRow

---

startRowOffset

▸ startRowOffset(value?): any

Gets or sets the offset relative to the start row of the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.startRowOffset();
heart.startRowOffset(0);

Parameters

Name	Type	Description
value?	number	The offset relative to the start row of the shape.

Returns

any

If no value is set, returns the offset relative to the start row of the shape.

Inherited from

ShapeBase.startRowOffset

---

style

▸ style(value?): any

Gets or sets the style of the picture shape.

example

//This sample sets style for the shape.
var shape = sheet.shapes.addPictureShape("Picture 1", "data:image/svg+xml;base64.....", 100, 50, 100, 100);
var oldStyle = shape.style();
oldStyle.fill.color = "red";
oldStyle.line.color = "green";
oldStyle.line.lineStyle = GC.Spread.Sheets.Shapes.PresetLineDashStyle.dashDot;
oldStyle.line.width = 5;
oldStyle.line.capType = GC.Spread.Sheets.Shapes.LineCapStyle.square;
oldStyle.line.joinType = GC.Spread.Sheets.Shapes.LineJoinStyle.miter;
oldStyle.line.transparency = 0.5;
shape.style(oldStyle);

Parameters

Name	Type	Description
value?	ShapeStyle	The shape style.

Returns

any

If no value is set, returns the current style of the shape.

---

toImageSrc

▸ toImageSrc(): string

Get the shape Image src of type Base64 string.

example

let shapeImageSrc = sheet.shapes.all()[0].toImageSrc();

Returns

string

return the shape Image Base64 src string.

Inherited from

ShapeBase.toImageSrc

---

width

▸ width(value?): any

Gets or sets the width of the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.width();
heart.width(n + 50);

Parameters

Name	Type	Description
value?	string | number	The width of the shape specified by a number or formula (starts with =) can get a number value.

Returns

any

If no value is set, returns the width of the shape.

Inherited from

ShapeBase.width

---

x

▸ x(value?): any

Gets or sets the horizontal location of the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.x();
heart.x(n + 50);

Parameters

Name	Type	Description
value?	string | number	The horizontal location of the shape specified by a number or formula (starts with =) can get a number value.

Returns

any

If no value is set, returns the horizontal location of the shape.

Inherited from

ShapeBase.x

---

y

▸ y(value?): any

Gets or sets the vertical location of the shape.

example

var heart = sheet.shapes.add("Shape1", GC.Spread.Sheets.Shapes.AutoShapeType.heart, 100, 60, 200, 160);
var n = heart.y();
heart.y(n + 50);

Parameters

Name	Type	Description
value?	string | number	The vertical location of the shape specified by a number or formula (starts with =) can get a number value.

Returns

any

If no value is set, returns the vertical location of the shape.

Inherited from

ShapeBase.y