bpd-canvas
v1.0.0
Published
Simple library for canvas opertations
Downloads
15
Readme
bpd-canvas
Simple assistant for canvas related processing.
Installation
Library comes in two version. The first one is bundled with UMD and is available as normal and minified JS file. Second option is ESM which comes with typings so it is also supporting Typescirpt
Common import
Use any CDN service that provides access to npm repositories
ESM
npm install bpd-canvas
Usage
Note: When using an UMD version then all classes arr available in bpdCanvas object attached to your global/window
Assistant
To create an assistant invoke CanvasAssistant with options:
const assistance = new CanvasAssistant(options)
where options is a AssistantOptions:
canvas
- !required - Canvas element. If not passed initializer will throw an exception.size
- CanvasObjectSize - optional - sets size of the canvasalpha
- boolean - optional - value of global alphadesynchronized
- boolean - optional - context optionuseGlobalSettings
- boolean - optional - context optionsettings
- IObjectProperties - optional - global settings for canvas elements
Available methods:
setGlobalObjectProperties
-(properties: IObjectProperties)
- sets global components settingsgetGlobalObjectProperties
- return reference to current global settingssetGlobalAlpha
-(value: number)
- sets global alpha value to contextsetImageSmoothing
-(enabled: boolean, quality?: ImageSmoothingQuality)
- set image smoothing and image smoothing qualitygetImageData
- invokes the same method from contextputImageData
-(imageData: ImageData, position: CanvasPoint, cutCoords?: CanvasObjectCoordinates)
- invokes original method from contextcreateImageData
-(width/data: number/ImageData, height?: number)
- invokes createImageData from context with data (ImageData) or creates blank image data with width and heightsave
- calls contextsave
restore
- calls contextrestore
setCanvasSize
-(size: CanvasObjectSize)
- sets canvas sizegetCanvasSize
- gets current canvas sizegetContext
- gets canvas contextclear
-(coords?)
- clears canvas area. If no coordinates is provided, whole canvas gets clearedcreatePattern
-(options: CanvasPatternDefinition)
- creates a patterncreateLinearGradient
-(options?: CanvasObjectCoordinates)
- creates linear gradient object asCanvasLinearGradientColor
Components (drawables)
All objects implement method draw()
that is used to draw it on the canvas.
Each drawable exposes (aside of draw
) some methods used to manage how they will after draw:
set
-(drawbleSetup)
- method is common for all drawables but argument differs depending on the drawable typesetSettings
-(settings: IObjectProperties)
- set style settings to drawablestroke
-(flag?)
- sets whether component shall draw stroke. Stroke gets disabled only when flag is falsefill
-(flag?)
- sets whether components shall be filled. Fill gets disabled when flag is set to falsegetKey
- returns id of the component
Rectangle
Creates instance of rectangle drawable. Draws a rectangular shape based on coordinates Setup object: CanvasObjectCoordinates
Flag
isFill
is enabled by default
Methods
setPosition
-(point: CanvasPoint)
- sets rectangle positionsetSize
-(size: CanvasObjectSize)
- sets rectangle size
Image
Creates instance of Image drawable that draws an image on the canvas Setup object: CanvasImageSetup
Text
Creates instance of text that will be drawn on on canvas Setup object: TextSetup
Methods
setFont
-(font: IStringable)
- sets font for displayed text. Use Font class to pass font settings.
Path
Draws path on canvas. Path always consists of path elements. Path elements are described in a separate section. Setup object: CanvasPoint
Methods
from
-(point)
- sets initial position of pathadd
-(...elements: IPathElement[])
- list of path elementsget
-(index)
- retrives path element from specific index in path childrendelete
-(index)
- deletes path child from specific indexinsertAt
-(index, ...elements)
- adds elements at specific index in the children listsetAt
-(index, element)
- replaces child at specific index in the children listclose
-(flag?)
- sets whether path shall be closed
Path elements
Path elements are used to build a Path.
All elements must implement method build
which is used by component CanvasPath to create an element.
All elements share some methods:
getKey
- retrvies an id of the path elementset
-(data)
- Sets setup data of the element. Type differs depending on element type
Line
Line is an path element that creates next lines.
Setup object: CanvasPoint[]
Examples
const line = new Line([{x: 1, y:1}, {x: 10, y: 10}])
const line2 = new Line().set([{x: 1, y:1}, {x: 10, y: 10}])
// with LineData
const data = new LineData({x: 1, y:1})
data.to({x: 10, y: 10}).to({x: 30, y:30}, {x: 50: y: 75});
const line3 = new Line(data.get());
Curve
Creates a curved line. Requires ending point, one control point (corner) and radius value.
Setup object: CurveOptions
Examples
const curve = new Curve({
end: {x: 10, y: 10},
corner: {x: 20, y:20},
radius: 10
})
// with CurveData
const data = new CurveData().to({x: 10, y: 10}).corner({x: 20, y: 20}).withRadius(10);
const curve2 = new Curve(data.get())
Arc
Creates an arc. It requires starting angle, ending angle and radius.
Setup object: ArcOptions
Example
// Creates a circle
const arc = new Arc({
startAngle: 0,
endAngle: Math.PI * 2,
radius: 10
})
// with ArcData
const data = new ArcData().setStartAngle(0).setEndAngle(Math.PI * 2).setRadius(10);
const arc2 = new Arc(data.get());
BezierCurve
Creates bezier curve. Requires two control points and ending point
Setup object: BezierCurveOptions
Examples
const bzCurve = new BezierCurve({
controlPoint: {x: 10, y: 20},
controlPoint2: {x:30, y: 50},
end: {x: 40, y: 40}
})
// with BezierCurveData
const data = new BezierCurveData().to({x: 40, y:40}).by({x: 10, y: 20}, {x: 30, y: 40});
const bzCurve2 = new BezierCurve(data.get());
QuadraticCurve
Creates quadratic curve. Requires a control point and ending point.
Setup object: QuadraticCurveOptions
Examples
const qCurve = new QuadraticCurve({
controlPoint: {x: 10, y: 20},
end: {x: 40, y: 40}
})
// with BezierCurveData
const data = new QuadraticCurveData().to({x: 40, y:40}).by({x: 10, y: 20});
const qCurve2 = new QuadraticCurve(data.get());
Ellipse
Creates an ellipse. It requires some elements properties:
- radiusX
- radiusY
- rotation (in radians)
- startAngle
- endAngle
Setup object: EllipseOptions
Examples
const ellipse = new Ellipse({
radiusX: 20,
radiusY: 20,
rotation: Math.PI / 4,
startAngle: 0,
endAngle: Math.PI * 2
})
// with EllipseData
const data = new EllipseData().setRadius(20).setAngles(0, Math.PI *2).setRotation(0);
// Note: Call setRadius(x, y) when you want to set different radius for each axis
const ellipse2 = new Ellipse(data.get());
Styles
CanvasLinearGradientColor
Creates instance of object styles that allows to build linear gradient
Methods
addColor
-(offset: number, color: IStringable)
- adds color definition at specific offsetremoveColor
-(offset)
- removes color definition from specific offsetclearColors
- clears color mapsetPosition
-(position)
setSize
-(size)
HslColor
Creates instance of style object building a HSL color
Methods
set
-(definition: HslColorDefinition)
- sets color definitonsetHue
-(value)
- hue value 0...360setSaturation
-(value)
- saturation value 0...100setLightness
-(value)
- lightness value 0...100setAlpha
-(value)
- lightness value 0...100/0...1
RgbColor
Creates instance of style object building a RGB color
Methods
set
-(color: RgbColorDefinition)
setRed
-(value)
- red value 0...255setGreen
-(value)
- green value 0...255setBlue
-(value)
- blue value 0...255setAlpha
-(value)
- alpha value 0...100fromHex
-(value: string)
- parses hex representation of color
Color
Creates instance of object style that accepts all kind of colors in string format
Methods
set
-(value: string)
Interfaces
CanvasObjectSize
width
- numberheight
- number
IObjectProperties
fillStyle
? - IObjectStyle;strokeWidth
? - number;isFill
? - boolean - internal flag to set whetherisStroke
? - boolean;font
? - IStringable;mitterLimit
? - number;lineCap
? - LineCap;lineJoin
? - LineJoin;lineDashOffset
? - number;lineDash
? - number[];textAlign
? - TextAlign;textBaseline
? - TextBaseline;shadowColor
? - IObjectStyle;shadowOffsetX
? - number;shadowOffsetY
? - number;shadowBlur
?: number;
IObjectStyle
toStyle
() - string | CanvasGradient | CanvasPattern
CanvasPoint
x
- numbery
- number
CanvasPatternDefinition
source
?: CanvasImageSourcerepeat
?: PatternRepetition
PatternRepetition
"repeat" | 'repeat-x' | 'repeat-y' | 'no-repeat'
CanvasObjectCoordinates
x
: numbery
: numberwidth
: numberheight
: number
HslColorDefinition
hue
?: numbersaturation
?: numberlightness
?: numberalpha
?: number
RgbColorDefinition
red
?: number;green
?: number;blue
?: number;alpha
?: number;
CanvasImageSetup
source
?: CanvasImageSourceposition
?: CanvasPointimageSlice
?: CanvasObjectCoordinatesdesitnationCoords
?: CanvasObjectCoordinates
TextSetup
text
?: string - text to be displayedposition
?: CanvasPoint - text position
CurveOptions
radius
?: numbercorner
?: CanvasPointend
?: CanvasPoint
BezierCurveOptions
controlPoint
?: CanvasPoint;controlPoint2
?: CanvasPoint;end
?: CanvasPoint;
QuadraticCurveOptions
controlPoint
?: CanvasPoint;end
?: CanvasPoint;
EllipseOptions
rotation
?: number;radiusX
?: number;radiusY
?: number;startAngle
?: number;endAngle
?: number;
ArcOptions
- startAngle: number;
- endAngle: number;
- radius: number;