Class: Shape

Constructor

new Shape(pathopt, strokeopt, backgroundopt, opacityopt, xopt, yopt)

Shape constructor.

Parameters:

Name	Type	Attributes	Default	Description
`path`	string	<optional>		Path consisting of points. It can be auto-generated by performing operations of one shape to another, such as add() or subtract().
`stroke`	Stroke	<optional>		A border of the shape.
`background`	string	<optional>		Color, gradient, image, and background options like in CSS.
`opacity`	number	<optional>	1	Opacity of the shape as a decimal between 0 and 1.
`x`	number	<optional>	0	Position of the shape from left edge.
`y`	number	<optional>	0	Position of the shape from the top.

Classes

Shape

Members

(readonly) parent :Window|Panel|undefined

Returns current parent component (Window or Panel), or undefined if the shape isn't added to any component.

Type:

Window | Panel | undefined

Methods

add(shape) → {this}

Adds another shape to this shape. Stroke of this shape is kept (stroke of another shape is disregarded).

Parameters:

Name	Type	Description
`shape`	Shape	Another shape object that would be added to this shape.

Returns:

Returns this shape for method chaining.

Type:: this

anchor(anchoropt) → {Object|this}

Sets or gets the anchor position relative to the shape, around which the shape can be rotated using the angle() method.

The default anchor is at the top-left corner of the shape's bounding rectangle (even for non-rectangular shapes).

Parameters:

Name	Type	Attributes	Description
`anchor`	Object	<optional>	Anchor point `{x, y}` around which the shape rotates when the angle is not 0.

Returns:

If called without arguments, returns the current anchor; otherwise, returns this shape for method chaining.

Type:: Object | this

angle(angleopt) → {number|this}

Gets or sets the rotation angle of the shape around its anchor.

Use the anchor() method to specify the anchor position relative to the shape.

The default anchor is set to the top-left corner of the shape's bounding rectangle (even for non-rectangular shapes).

Parameters:

Name	Type	Attributes	Description
`angle`	number	<optional>	Rotation angle in degrees. Values below 0 or above 360 are normalized to the range 0–360 using the modulus operator (%).

Returns:

If called without arguments, returns the current value; otherwise this shape is returned for method chaining.

Type:: number | this

background(backgroundopt) → {this|string}

Sets or gets the background of the shape.

The background value can be a string that contains a mixture of background color, image path (relative or absolute), base64 encoded image string, linear-gradient, radial-gradient, like in CSS in web browsers. Some features may not be supported though. Background settings like position, image stretching or repeating, opacity and more are supported.

See examples below.

Parameters:

Name	Type	Attributes	Description
`background`	string	<optional>	Background string. If omitted, returns the current value.

Returns:

If called without parameters, returns this shape instance; otherwise returns current background.

Type:: this | string

Example

shape.background("#FF000055 url(images/bg.png) center no-repeat opacity=0.6 10px 15px linear-gradient(#DDDDDD55, #F8F8F855 10%) / auto);
panel.background("url(data:image/png;base64,As8fE4fdt1r.....)")); // supports base64 encoded image string

intersect(shape) → {this}

Remove an area from this shape where this shape and provided shape don't intersect, leaving only area where these shapes do intersect. Stroke of this shape is kept (stroke of another shape is disregarded).

Parameters:

Name	Type	Description
`shape`	Shape	Another shape object.

Returns:

Returns this shape for method chaining.

Type:: this

intersects(shape) → {boolean|null}

Checks if this shape intersects (touches) with another shape. Both of these shapes must be added to the same component for this to work.

Parameters:

Name	Type	Description
`shape`	Shape	Intercepting shape

Returns:

Returns boolean on successful check or null if the check failed to be performed.

Type:: boolean | null

opacity(opacityopt) → {number|this}

Gets or sets the opacity (transparency) of the shape.

Parameters:

Name	Type	Attributes	Description
`opacity`	number	<optional>	Decimal value between 0 and 1 (inclusive).

Returns:

If called without arguments, returns the current opacity; otherwise, returns this shape for method chaining.

Type:: number | this

position(xopt, yopt) → {Object|this}

Sets or gets location of the shape relative to top-left corner of its parent component.

Parameters:

Name	Type	Attributes	Description
`x`	number \| Object	<optional>	X position integer or a position object (e.g., {x:10,y:40}).
`y`	number	<optional>	Y position integer.

Returns:

If called without arguments, current position object is returned; otherwise this shape is returned for method chaining.

Type:: Object | this

size(sizeopt) → {Object|this}

Returns the size of a shape. Does not set a new size. Some shapes override this function and size can be set for those shapes. (e.g. Rectangle, Ellipse) If the Shape is not added to a any UI Component, then null is returned.

Parameters:

Name	Type	Attributes	Description
`size`	Object	<optional>	New size object (x,y}, but only for shapes that allow setting new size, such as Rectangle or Ellipse.

Returns:

If called without parameters, returns current size, or null if the shape is not added to a component. When setting size, this shape instance is returned for method chaining.

Type:: Object | this

stroke(strokeopt) → {Stroke|this}

Sets or gets a Stroke of the shape.

Parameters:

Name	Type	Attributes	Description
`stroke`	Stroke	<optional>	Stroke object

Returns:

When called without parameters, current Stroke is returned; otherwise this Shape is returned for method chaining.

Type:: Stroke | this

subtract(shape) → {this}

Removes an area of a specified shape from this shape. Stroke of this shape is kept (stroke of another shape is disregarded).

Parameters:

Name	Type	Description
`shape`	Shape	Another shape object that would be subtracted from this shape.

Returns:

Returns this shape for method chaining.

Type:: this

toObject(includeopt) → {Shape}

Returns a JSON object that contains shape properties.

Parameters:

Name	Type	Attributes	Default	Description
`include`	string	<optional>	"all"	Specified what to include. "all" is default. Valid values are: "all", "stroke", "background", "points", "basic". Each shape that derives from this `Shape` class may also have it's own values.

Returns:

Returns this Shape for method chaining.

Type:: Shape

visible(visibleopt) → {boolean|Shape}

Sets or gets whether the shape is visible.

Parameters:

Name	Type	Attributes	Description
`visible`	boolean	<optional>	`true` to show, `false` to hide.

Returns:

When setting a value, this shape is returned; otherwise current value is returned.

Type:: boolean | Shape

x(xopt) → {number|this}

Sets or gets X position of the shape relative to left edge of its parent component.

Parameters:

Name	Type	Attributes	Description
`x`	number	<optional>	X position integer.

Returns:

If called without arguments, current X position is returned; otherwise this shape is returned for method chaining.

Type:: number | this

y(yopt) → {number|this}

Sets or gets Y position of the shape relative to top edge of its parent component (for Window parent component gets Y position from the top of content area).

Parameters:

Name	Type	Attributes	Description
`y`	number	<optional>	Y position integer.

Returns:

If called without arguments, current Y position is returned; otherwise this shape is returned for method chaining.

Type:: number | this

(static) fromObject(object) → {Shape}

Converts JSON object back to Shape. To convert Shape to object use Shape.toObject() function.

Parameters:

Name	Type	Description
`object`	object	An object that has properties to recreate a Shape object.

Returns:

Returns a new instance of Shape.

Type:: Shape