drawing | PiWeb Plot Extension API Reference

Introduction

All necessary classes for drawing are encapsulated in the piweb.drawing module. The plot extension will be rendered whenever something changes, e.g. a property value, its size or position. When this happens, the plot extension API will emit the render event, which has a DrawingContext object as its parameter.

import * as piweb from 'piweb';
import drawing = piweb.drawing;


piweb.events.on("render", render);

function render(context: drawing.DrawingContext) {
    ...
}

Be aware that all coordinates and values are interpreted as millimeters. PiWeb draws with a resolution of 96 DPI, so one millimeter is equal to 96 / 25.4 ~ 3.58 pixels, or one pixel is equal to 25.4 / 96 ~ 0.2646 millimeters. PiWeb will take care, that everything you draw is aligned to display coordinates, so nothing will look blurry.

Description objects

Most drawing classes implement a description interface named similar to the class. For example, the class Pen implements PenDescription. Description interfaces only consist of properties, so that they can be represented by object literals:

const penDescription = {
        brush: {
            type: 'solid',
            color: {r: 255, g: 0, b: 0}
        },
        thickness: 1.0
};

context.setPen( penDescription );

Most of the properties are even optional and thus don't have to be specified. Unspecified properties will assume a default value. It's often easier and much better readable to use an object literal compared to the constructor of the corresponding class:

const pen = new piweb.drawing.Pen(
        new piweb.drawing.SolidColorBrush(
            new piweb.drawing.Color(255, 0, 0, 255),
            1.0
        ),
        1.0,
        'flat',
        'flat',
        'bevel',
        new Array<number>(),
        0.0,
        'flat'
    );

Most functions directly accept literal objects. If nevertheless an instance of a class is required, it can be aquired by calling the static create method of the class. When doint this on an abstract class like Brush, an additional type parameter is required. You can also call the factory method on the derived class, e.g. SolidColorBrush.createSolidColorBrush.

const pen = piweb.drawing.Pen.create({
        brush: {
            type: 'solid',
            color: {r: 255, g: 0, b: 0}
        },
        thickness: 1.0
});

This should be preferred to using constructors.

Tips:

Colors and brushes can usually be specified as string (e.g. 'red' or '#FF0000').
Positions can usually be specified as arrays ([1.0, 1.0]) or as objects ({x: 1.0, y: 1.0}) or even as number, if both coordinates have the same value.

Index

Classes

Interfaces

Variables

Type aliases

ArcType

ArcType: "small" | "large"

BrushDescription

Can be used to initialize an instance of the Brush class.

BrushType

BrushType: "solid" | "linear" | "radial"

An enumeration to determine the type of a brush.

ColorDescription

ColorDescription: ColorObject | string

Can be used to initialize an instance of the Color class.

FillRule

FillRule: "evenOdd" | "nonzero"

Determines how overlapping geometries are filled.

evenOdd (default)

Fills the area that is overlapped by an odd number of geometries. *

nonZero

Fills the area that is overlapped by at least one geometry. *

FlowDirection

FlowDirection: "leftToRight" | "rightToLeft"

Determines if the text is arranged from the left to the right or from the right to the left. While this seems to be redundant with the HorizontalTextAlignment, the effect is clear when the text exceeds the size of the boundaries, and especially when ellipsis are used.

leftToRight (default)

Layouting starts at the left boundary.

rightToLeft

Layouting starts at the right boundary.

FontStretch

Used to condense or expand the font horizontally.

Identifier	Changed width/height ratio
`ultraCondensed`	50% of the default width/height ratio
`extraCondensed`	62.5% of the default width/height ratio
`condensed`	75% of the default width/height ratio
`semiCondensed`	87.5% of the default width/height ratio
`normal`	100% of the default width/height ratio
`semiExpanded`	112.5% of the default width/height ratio
`expanded`	125% of the default width/height ratio
`extraExpanded`	150% of the default width/height ratio
`ultraExpanded`	200% of the default width/height ratio

FontStyle

FontStyle: "normal" | "oblique" | "italic"

The font style can be used to display letters in a cursive way.

normal (default)

The text will be displayed as usual.

italic

Some fonts have a built in italic letter set, which can be used by specifying the italic font style.

oblique

For fonts which have no built in italic letter set, the oblique font style allows to apply a ShearTransform to the normal font to make it look cursive. The italic style will usually look more pleasing though.

FontWeight

The font weight is used to display letters bolder or thinner. Most fonts only support a subset of the following font weights.

Identifier	numeric value
`thin`	100
`extraLight`	200
`light`	300
`normal`	400
`medium`	500
`semiBold`	600
`bold`	700
`extraBold`	800
`black`	900
`extraBlack`	950

GeometryCombineMode

GeometryCombineMode: "union" | "intersect" | "xor" | "exclude"

Determines how two geometries are combined.

union (default)

The resulting geometry is the area that is overlapped by the first or second geometry or both.

intersect

The resulting geometry is the area that is overlapped by both geometries.

xor

The resulting geometry is the area that is overlapped by the first or second geometry, but not both.

exclude

The second geometry is subtracted from the first.

GeometryDescription

GeometryDescription: PureGeometryDescription | string | Geometry

Can be used to initialize a Geometry.

GeometryType

Determines the type of a geometry.

HorizontalAnchor

HorizontalAnchor: "origin" | "left" | "right" | "center"

Determines how the geometry aligns to the position horizontally.

origin (default)

The image will be drawn with the position as its coordinate origin.

left

The image will be drawn with the position on the left side.

center

The image will be drawn with the position at the center.

right

The geometry will be drawn with the position on the right side.

HorizontalImageAnchor

HorizontalImageAnchor: "left" | "right" | "center"

Determines how the image aligns to the position horizontally.

left (default)

The image will be drawn with the position on the left side.

center

The image will be drawn with the position at the center.

right

The image will be drawn with the position on the right side.

HorizontalTextAlignment

HorizontalTextAlignment: "left" | "right" | "center" | "justify"

Determines how text is arranged inside the bounding box that is defined by width and height. In case no bounding box is defined, the horizontal text alignment also determines the horizontal position of the text relative to the anchor.

left (default)

Aligns text to the left boundary.

right

Aligns text to the right boundary.

center

Aligns text centered between the left and the right boundaries.

justify

Increases the size of the whitespaces until the text fits between the left and right boundary.

HorizontalTextAnchor

HorizontalTextAnchor: "default" | "left" | "right" | "center"

Determines how the whole text is arranged horizontally relative to the text position.

default (default)

Arranges the text according the HorizontalTextAlignment and the specified size of the bounding box.

left

Places the anchor point on the left side of the bounding box.

right

Places the anchor point on the right side of the bounding box.

center

Places the anchor at the center of the bounding box.

LineCap

LineCap: "flat" | "round" | "square"

Determines the geometry at the start and/or end of a line.

flat

No extra geometry is added.

round

Adds a half circle with a diameter that is equal to the pens thickness.

square

Adds a half square with the side length of the pens thickness.

LineJoin

LineJoin: "bevel" | "miter" | "round"

Determines the geometry between two linear segments of a line.

bevel

Adds a triangle that connects the two non-overlapping points of the lines.

miter

Extends the outlines of the two lines until they cut each other, and fills the enclosed area.

round

Creates a circle around the cutting point with a diameter that is equal to the pens thickness.

PathSegmentDescription

Can be used to initialize a PathSegment.

PathSegmentType

An enumeration to determine the type of a path segment.

PixelFormat

PixelFormat: "rgb24" | "bgr24" | "bgra32" | "pbgra32" | "gray8"

The list of known pixel formats of PiWeb

PointDescription

PointDescription: PointObject | number[] | number

PureGeometryDescription

Can be used to initialize a Geometry.

SizeDescription

SizeDescription: SizeObject | number[] | number

SweepDirection

SweepDirection: "clockwise" | "counterclockwise"

An enumeration to determine the sweep direction of an arc segment.

see: ArcSegment

TextDecoration

TextDecoration: "underline" | "strikeThrough"

An enumeration for text rendering features.

underline

Renders a horizontal line at the bottom of the text.

strikeThrough

Renders a horizontal line at the vertical center of the text.

TextTrimming

TextTrimming: "none" | "characterEllipsis" | "wordEllipses"

Determines what happens when the text exceeds the size of the boundaries. In case no boundaries are defined, the text trimming has no effect. When the length of a text reaches the maxTextWidth, a line break will be inserted in case the maxTextHeight allows another line of text. If this is not the case, the text will be cut of, in the way the text trimming describes. A text like 'lorem ipsum' would be formatted like the following:

none (default)

The text will be trimmed at a whitespace if possible, otherwise in a word. No ellipsis are shown.

wordEllipsis

The text will be trimmed at a whitespace if possible, otherwise in a word, and ellipsis will be shown.

characterEllipsis

The text will be trimmed in a word, and ellipsis will be shown.

TransformDescription

Can be used to initialize an instance of the Transform class.

TransformationType

Determines the type of a transform.

VerticalAnchor

VerticalAnchor: "origin" | "top" | "bottom" | "center"

Determines how the geometry aligns to the position vertically.

origin (default)

The image will be drawn with the position as its coordinate origin.

top

The image will be drawn with the position on the top.

center

The image will be drawn with the position at the center.

bottom

The geometry will be drawn with the position on the bottom.

VerticalImageAnchor

VerticalImageAnchor: "top" | "bottom" | "center"

Determines how the image aligns to the position vertically.

top (default)

The image will be drawn with the position on the top.

center

The image will be drawn with the position at the center.

bottom

The image will be drawn with the position on the bottom.

VerticalTextAlignment

VerticalTextAlignment: "top" | "bottom" | "center"

Determines how text is arranged inside the bounding box that is defined by width and height. In case no bounding box is defined, the text vertical alignment also determines the vertical position of the text relative to the anchor.

top (default)

Aligns the text on the top of the bounding box.

bottom

Aligns the text on the bottom of the bounding box.

center

Aligns the text centered in the bounding box.

VerticalTextAnchor

VerticalTextAnchor: "default" | "top" | "bottom" | "center" | "baseline"

Determines how the whole text is arranged vertically relative to the text position.

top (default)

Places the anchor point on the top of the bounding box.

bottom

Places the anchor point on the bottom of the bounding box.

center

Places the anchor at the center of the bounding box.

baseline

Places the anchor at the height of the baseline of the first line of text. The baseline anchor looks most natural when aligning text to certain positions, e.g. the lines of a scale.