RiverSoftAVG Products Help

Zoom Window Out
Larger Text | Smaller Text
Hide Page Header
Show Expanding Text
Printable Version
Send Mail Feedback
Save Permalink URL

Navigation: Code Documentation > RSVclCommon > RSGraphics > Classes

TRSPathData Class

TRSPathData represents a series of connected curves and lines.

Note
Unlike the Delphi TPathData class, TRSPathData works with both FMX and VCL and may be drawn to either libraries' TCanvas. The TRSPathData class provides much more robust parsing of data strings than TPathData to fulfill the SVG specification for paths. Finally, there are many additional methods in TRSPathData compared to TPathData (for example, AddPolygon).

Use TRSPathData to build graphic shapes by connecting a series of curves and lines. TRSPathData can be drawn and filled on objects that have a TCanvas as a component. For VCL, call the DrawPath and FillPath methods. The TVclCanvasHelper also implements DrawPath and FillPath methods for VCL TCanvas.

TRSPathData maintains the coordinates of geometric shapes in world coordinate space in an array of RSGraphics.TRSPathPoint. Each saved point has a specific type, to identify the primitive shape it is defining. Complex shapes of a TRSPathData are composed of a sequence of primitive shapes like lines and curves. To access the array of TRSPathPoint, use Count and Points.

A TRSPathData can be initialized by setting the Data property, or by adding explicitly each new shape. TRSPathData has defined a way to add shapes explicitly. See the TRSPathData functions.

When a TRSPathData is constructed, each new added shape is appended to the end of the TRSPathData, by default. The start point of the new shape is the end point of the previous shape. To customize the start point of a new element to be added, use the MoveTo or MoveToRel method.

Namespace: RSGraphics

	Name	Description
	Count	Returns the number of points of the TRSPathData. Count gets the number of elements in the Points array.
	Data	Specifies the current TRSPathData by a sequence of characters. Data is a string composed of characters that indicate the type and the coordinates of the points of the primitive shapes for the current TRSPathData. Set Data to define and populate TRSPathData with primitive shapes. The syntax of path data is concise in order to allow for minimal file size and efficient downloads. Some of the ways that Data can be minimized for the size of path data are as follows: • All instructions are expressed as one character (e.g., a moveto is expressed as an M). • Superfluous white space and separators such as commas can be eliminated (e.g., "M 100 100 L 200 200" contains unnecessary spaces and could be expressed more compactly as "M100 100L200 200"). • The command letter can be eliminated on subsequent commands if the same command is used multiple times in a row (e.g., you can drop the second "L" in "M 100 200 L 200 100 L -100 -200" and use "M 100 200 L 200 100 -100 -200" instead). • Relative versions of all commands are available (uppercase means absolute coordinates, lowercase means relative coordinates). • Alternate forms of lineto are available to optimize the special cases of horizontal and vertical lines (absolute and relative). • Alternate forms of curve are available to optimize the special cases where some of the control points on the current segment can be determined automatically from the control points on the previous segment.

The path data syntax is a prefix notation (i.e., commands followed by parameters). The only allowable decimal point is a FULL STOP (".") character and no other delimiter characters are allowed. (For example, the following is an invalid numeric value in a path data stream: "13,000.56". Instead, say: "13000.56".)

For the relative versions of the commands, all coordinate values are relative to the current point at the start of the command.

The following table list the commands.

M (absolute) m (relative)

Start a new sub-path at the given (x,y) coordinate. M (uppercase) indicates that absolute coordinates will follow; m (lowercase) indicates that relative coordinates will follow. If a moveto is followed by multiple pairs of coordinates, the subsequent pairs are treated as implicit lineto commands. Hence, implicit lineto commands will be relative if the moveto is relative, and absolute if the moveto is absolute. If a relative moveto (m) appears as the first element of the path, then it is treated as a pair of absolute coordinates. In this case, subsequent pairs of coordinates are treated as relative even though the initial moveto is interpreted as an absolute moveto.

Z or z

Close the current subpath by drawing a straight line from the current point to current subpath's initial point. Since the Z and z commands take no parameters, they have an identical effect.

L (absolute) l (relative)

Add a line from the current point to the given (x,y) coordinate which becomes the new current point. L (uppercase) indicates that absolute coordinates will follow; l (lowercase) indicates that relative coordinates will follow. A number of coordinates pairs may be specified to draw a polyline. At the end of the command, the new current point is set to the final set of coordinates provided.

H (absolute) h (relative)

Adds a horizontal line from the current point (cpx, cpy) to (x, cpy). H (uppercase) indicates that absolute coordinates will follow; h (lowercase) indicates that relative coordinates will follow. Multiple x values can be provided (although usually this doesn't make sense). At the end of the command, the new current point becomes (x, cpy) for the final value of x.

V (absolute) v (relative)

Adds a vertical line from the current point (cpx, cpy) to (cpx, y). V (uppercase) indicates that absolute coordinates will follow; v (lowercase) indicates that relative coordinates will follow. Multiple y values can be provided (although usually this doesn't make sense). At the end of the command, the new current point becomes (cpx, y) for the final value of y.

C (absolute) c (relative)

Adds a cubic Bézier curve from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve. C (uppercase) indicates that absolute coordinates will follow; c (lowercase) indicates that relative coordinates will follow. Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier.

S (absolute) s (relative)

Adds a cubic Bézier curve from the current point to (x,y). The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not an C, c, S or s, assume the first control point is coincident with the current point.) (x2,y2) is the second control point (i.e., the control point at the end of the curve). S (uppercase) indicates that absolute coordinates will follow; s (lowercase) indicates that relative coordinates will follow. Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier.

Q (absolute) q (relative)

Adds a quadratic Bézier curve from the current point to (x,y) using (x1,y1) as the control point. Q (uppercase) indicates that absolute coordinates will follow; q (lowercase) indicates that relative coordinates will follow. Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier.

T (absolute) t (relative)

Creates a quadratic Bézier curve from the current point to (x,y). The control point is assumed to be the reflection of the control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not a Q, q, T or t, assume the control point is coincident with the current point.) T (uppercase) indicates that absolute coordinates will follow; t (lowercase) indicates that relative coordinates will follow. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier.

A (absolute) a (relative)

Creates an elliptical arc from the current point to (x, y). The size and orientation of the ellipse are defined by two radii (rx, ry) and an x-axis-rotation, which indicates how the ellipse as a whole is rotated relative to the current coordinate system. The center (cx, cy) of the ellipse is calculated automatically to satisfy the constraints imposed by the other parameters. large-arc-flag and sweep-flag contribute to the automatic calculations and help determine how the arc is drawn.

public property

Distances

Returns the distance to every point in the path

Note
It is recommended to Flatten the path before calling this property.

published property

FillMode

Specifies how to fill areas that are formed when the path intersects itself.

Note
This property is ignored in FMX.

published property

FormatStr

Defines a floating point format string for writing out the path points.

Use the FormatStr property to control the size of the Data string.

public property

OnChanged

Occurs when the path data has changed.

Write an OnChanged event handler to respond to path changes.

public property

Points[Integer]

Specifies the points from the current TRSPathData and their types.

Points gets the point and its type, specified by the index in the array of points of the TRSPathData. Use Points to access the internal array of TRSPathPoint of the TRSPathData.

public property

Polygons

Returns the polygons (array of points) that make up the path.

Note
It is recommended to Flatten the path before calling this property.

protected property

UpdateCount

Tracks the number of times BeginUpdate has been called without a corresponding EndUpdate call.

Top

	Name	Description
	AddArc(TRSPoint,TRSPoint,Single,Single)	Appends an arc to the current TRSPathData as the part of an ellipse contour. The Center parameter specifies the center of the parent ellipse. The coordinates of the Radius parameter specify the semi-axes of the parent ellipse: • Radius.x defines the x-semi-axis. • Radius.y defines the y-semi-axis.

StartAngle specifies the angle, in degrees, measured clockwise, from the x-axis to the line passing through the Center point of the ellipse and intersects the ellipse in the starting point of the arc.

SweepAngle specifies the angle, in degrees, measured clockwise, from the StartAngle parameter to the line passing through the Center point of the ellipse and intersects the ellipse in the ending point of the arc.

If there are previous lines or curves in the current TRSPathData, a line is added to connect the last point of the previous segment to the start point of the arc.

To move the start point of the arc, call MoveTo or MoveToRel before calling AddArc.

AddArc splits the arc in simple figures and adds to Points the points needed to represent them. The added points have different types.

To find the last point of the TRSPathData, call the LastPoint method.

protected method

AddArcSvg(TRSPoint,TRSPoint,Single,Boolean,Boolean,TRSPoint)

Represents method AddArcSvg(TRSPoint,TRSPoint,Single,Boolean,Boolean,TRSPoint).

public method

AddEllipse(TRSRect)

Appends an ellipse defined by a bounding rectangle structure to the current TRSPathData.

AddEllipse splits the ellipse in simple figures and adds to Points the points needed to represent them.

To find the end point of the TRSPathData, call the LastPoint method.

public method

AddPathOutline(TRSPathData,Single)

Adds a crude outline around the input path to the current path.

Note
Note that this routine ignores joins and miters so it is very crude and is mostly useful for detection of mouse along outline.

public method

AddPolygon(TPoints)

Overloaded. Adds the polygon to the current path.

public method

AddPolygon(TRSPoints)

Overloaded. Adds the polygon to the current path.

public method

AddPolygons(TPointPolygons)

Overloaded. Adds the array of polygons to the current path.

public method

AddPolygons(TRSPolygons)

Overloaded. Adds the array of polygons to the current path.

public method

AddRectangle(TRSRect)

Overloaded. Adds a rectangle to the current TRSPathData.

public method

AddRectangle(TRSRect,Single,Single,TRSCorners,TRSCornerType)

Overloaded. Adds a rectangle with customized shapes of corners to the current TRSPathData.

AddRectangle splits the rectangle in simple figures and adds the points needed to represent them to the Points array. The added points have appropriate types to represent the figures.

To find the end point of the TRSPathData, call the LastPoint method.

protected method

AddRectangleForSegment(TRSPoint,TRSPoint,Single)

Represents method AddRectangleForSegment(TRSPoint,TRSPoint,Single).

public method

Append(String)

Overloaded. Appends the source path to the current path

public method

Append(TRSPathData)

Overloaded. Appends the source path to the current path

public method

ApplyMatrix(TRSMatrix)

Applies a transformation matrix to the current TRSPathData.

The transformation can translate, scale, or rotate the current TRSPathData.

public method

Assign(TPersistent)

Represents method Assign(TPersistent).

public method

BeginUpdate

Defers OnChanged events until EndUpdate is called.

BeginUpdate and EndUpdate work to defer OnChanged events while a path is being modified. Use the BeginUpdate method to defer OnChanged events until an equal number of EndUpdate methods have been called.

protected method

CalculateDistances

Calculates the distance to every point in the path. Returns the length of the path.

Note
It is recommended to Flatten the path before calling this method.

protected method

Change

Called when the path changes.

The Change method triggers an OnChanged event.

public method

Clear

Clears the current TRSPathData.

Clear removes all the figures from the current TRSPathData.

It clears the Points array.

public method

Clone

Creates a copy of the path data object.

Note
It is the responsibility of the calling routine to free the new TRSPathData object.

public method

ClosePath

Closes the current TRSPathData.

A closed path is a path for which the start point and the LastPoint coincide.

The start point of a TRSPathData is the first point in the Points array.

ClosePath adds the start point of the TRSPathData at the end of the Points array. The added point if of type ppClose.

public method

CurveTo(TRSPoint,TRSPoint,TRSPoint)

Appends a curve to the current TRSPathData.

The curve is defined by 4 points:

• A start point--the last point of the TPathData.

• Two control points, specified by the ControlPoint1 and ControlPoint2 parameters.

• An end point, specified by the EndPoint parameter.

CurveTo adds the control points and the end point of the curve to the Points array. The added points are of type ppCurveTo.

To move the start point of the curve, call the MoveTo or MoveToRel method before calling CurveTo.

To find the end point of the TRSPathData, call the LastPoint method.

public method

CurveToRel(TRSPoint,TRSPoint,TRSPoint)

Appends a curve to the current TRSPathData.

The curve is defined by 4 points that depend on the last point of the current TRSPathData.

The start point of the curve is the end point of the TRSPathData.

The ControlPoint1 and ControlPoint2 parameters' coordinates specify the distances to the end point of the current TRSPathData, on each axis, for each of the two control points of the curve.

The EndPoint parameter's coordinates specify the distances to the end point of the current TRSPathData, on each axis, for the end point of the curve.

CurveToRel adds the control points and the end point of the curve to the Points array. The coordinates for each added point are equal to the sum between the coordinates of the last point and the coordinates of the corresponding point specified by the parameters. The added points are of type ppCurveTo.

To move the start point of the curve, call the MoveTo or MoveToRel method before calling CurveToRel.

To find the end point of the TRSPathData, call the LastPoint method.

protected method

DefineProperties(TFiler)

Sets the virtual properties for reading and writing the path data stream.

DefineProperties overrides TPersistent.DefineProperties for reading and writing path data from or to a TStream object, respectively.

It creates a virtual property, Path, that can be treated as a property to read from or write data to the TRSPathData object. It first calls the TPersistent.DefineProperties inherited method.

protected method

DrawPath(TCanvas,Boolean,Single)

Overloaded. Draws or Fills the path to the canvas.

public method

DrawPath(TCanvas,Single)

Overloaded. Draws a path on the current TCanvas.

DrawPath draw a TRSPathData, with the current Stroke or Pen.

If the path is empty, DrawPath does nothing. In this case, DrawPath does not raise any errors.

public method

EndUpdate

Reenables OnChanged events after BeginUpdate has been called.

public method

FillPath(TCanvas,Single)

Overloaded. Fills a path on the current TCanvas.

FillPath fills a TRSPathData, with the current Stroke or Pen.

If the path is empty, FillPath does nothing. In this case, FillPath does not raise any errors.

public method

FitToRect(TRSRect)

Translates and scales the current TRSPathData to fit a specified rectangle area.

public method

Flatten(Single)

Converts each curve in the current TRSPathData into a sequence of connected line segments.

The Flatness parameter specifies the maximum permitted error between the curve and its flattened approximation. By default, it is 0.25. Reducing the flatness value will increase the number of line segments in the approximation.

public method

FlattenToPolygon(TRSPolygon,Single)

Converts the current TRSPathData into a sequence of connected line segments and returns the sequence as a TRSPolygon.

The Polygon parameter is the return variable. It is the result of the conversion.

Flatness is an optional parameter that specifies the maximum permitted error between the curve and its flattened approximation. By default, it is 0.25. Reducing the flatness value will increase the number of line segments in the approximation.

public method

GetBounds

Returns the bounding rectangle of the current TRSPathData. When the path is drawn, the rectangle returned by GetBounds is not affected by the thickness and style of the pen stroke.

public method

GetLength

Returns the length of the path.

Note
It is recommended to Flatten the path before calling this method.

public method

HLineTo(Single)

Appends a line to the current TRSPathData.

The line is defined by the end point of the TRSPathData and a point that depends on the specified parameter.

HLineTo adds the specified point to the Points array. The end point of the line is moved horizontally from the last point of the TPathData to the point with the x-coordinate equal to X. The added point is of type ppLineTo.

To move the start point of the line, call MoveTo or MoveToRel before calling HLineTo.

To find the last point of the TRSPathData, call the LastPoint method.

public method

HLineToRel(Single)

Appends a line to the current TRSPathData.

The line is defined by the end point of the TRSPathData and a point that depends on the specified parameter.

HLineToRel adds the specified point to the Points array. The The end point of the line is moved horizontally by a distance equal to X to the end point of the TRSPathData. The added point is of type ppLineTo.

To move the start point of the line, call MoveTo or MoveToRel before calling HLineToRel.

To find the last point of the TRSPathData, call the LastPoint method.

public method

IsEmpty

Return true if there are no points in the path

public method

LastPoint

Returns the end point of the current TRSPathData. LastPoint returns a TRSPoint.

public method

LineTo(TRSPoint)

Appends a line to the current TRSPathData.

The line is defined by the end point of the TRSPathData and a specified point.

To move the start point of the line, call MoveTo or MoveToRel before calling LineTo.

LineTo adds P to Points . The added point is of type ppLineTo.

To find the last point of the TRSPathData, call the LastPoint method.

public method

LineToRel(TRSPoint)

Appends a line to the current TRSPathData.

The line is defined by the end point of the TPathData and a point that depends on the point specified by the parameter.

To move the start point of the line, call MoveTo or MoveToRel before calling LineToRel.

LineToRel adds P to Points . Its coordinates are equal to the sum between the coordinates of the last point and the coordinates of P. The added point is of type ppLineTo.

To find the last point of the TRSPathData, call the LastPoint method.

public method

MoveTo(TRSPoint)

Adds a specified point to the end of the current TRSPathData.

Use MoveTo to customize the start point for a new element to be added to the current TRSPathData.

MoveTo adds the specified point to the Points array. The added point is of type ppMoveTo.

When a TRSPathData is drawn on a canvas, a MoveTo point and the previous point are not visibly connected (no line is drawn between them).

To find the last point of the TRSPathData, call the LastPoint method.

public method

MoveToRel(TRSPoint)

Adds a specified point to the end of the current TRSPathData.

Use MoveToRel to customize the start point for a new element to be added to the current TRSPathData.

MoveToRel adds the specified point to the Points array. Its coordinates are equal to the sum between the coordinates of the last point and the coordinates of P. The added point is of type ppMoveTo.

When a TRSPathData is drawn on a canvas, a MoveToRel point and the previous point are not visibly connected (no line is drawn between them).

To find the last point of the TRSPathData, call the LastPoint method.

public method

PointInPath(Single,Single)

Overloaded. Returns true if the point specified by X and Y is inside the path

public method

PointInPath(TRSPoint)

Overloaded. Returns true if the specified point is inside the path

public method

PointInPathOutline(Single,Single,Single)

Overloaded. Returns true if the point specified by X and Y is inside the path outline (i.e., the stroke of the path). The StrokeWidth specifies the width of the path outline.

public method

PointInPathOutline(TRSPoint,Single)

Overloaded. Returns true if the specified point is inside the path outline (i.e., the stroke of the path). The StrokeWidth specifies the width of the path outline.

public method

QuadCurveTo(TRSPoint,TRSPoint)

Appends a curve to the current TRSPathData.

The curve is defined by 4 points:

• A start point--the last point of the TPathData.

• Control point

• An end point, specified by the EndPoint parameter.

QuaveCurveTo adds the control points and the end point of the curve to the Points array. The added points are of type ppCurveTo.

To move the start point of the curve, call the MoveTo or MoveToRel method before calling QuadCurveTo.

To find the end point of the TRSPathData, call the LastPoint method.

protected method

ReadPath(TStream)

Reads TRSPathData from the virtual property Path (created by DefineProperties) when streaming from the TStream Stream.

public method

Scale(Single,Single)

Scales the current TRSPathData.

public method

SmoothCurveTo(TRSPoint,TRSPoint)

Appends a smooth curve to the current TRSPathData.

The smooth curve is defined by 4 points:

• A start point--the last point of the TPathData.

• Two control points. If Points has more than two items, the first control point coincides with the start point of the curve, otherwise it is equal to the second control point. The Control2 parameter specifies the second control point.

• An end point, specified by the EndPoint parameter.

SmoothCurveTo adds the control points and the end point of the curve to the Points array. The added points are of type ppCurveTo.

To move the start point of the curve, call the MoveTo or MoveToRel method before calling SmoothCurveTo.

To find the end point of the TRSPathData, call the LastPoint method.

public method

SmoothCurveToRel(TRSPoint,TRSPoint)

Appends a smooth curve to the current TRSPathData.

The smooth curve is defined by 4 points that depend on the last point of the current TRSPathData.

The start point of the curve is the end point of the TRSPathData.

If Points has more than 2 items, the first control point coincides with the start point, otherwise it is equal to the second control point.

The ControlPoint2 parameter's coordinates specify the distances to the last point of the current TRSPathData, on each axis, for the second control point of the curve.

The EndPoint parameter's coordinates specify the distances to the last point of the current TRSPathData, on each axis, for the end point of the curve.

SmoothCurveToRel adds the control points and the end point of the curve to the Points array. The coordinates for each point are equal to the sum between the coordinates of the last point of the current TRSPathData and the coordinates of the corresponding points specified by the parameters. The added points are of type ppCurveTo.

To move the start point of the curve, call the MoveTo or MoveToRel method before calling SmoothCurveToRel.

To find the end point of the TRSPathData, call the LastPoint method.

public method

SplitDataByLength(Integer,String)

Returns the string representation of the path data. The string representation is split every Len characters using the specified delimiter.

SplitDataByLength returns a string that can be multiple lines of no more than Len length.

public method

ToPolygons

Converts the path data into an array of polygons.

Note
It is recommended that Flatten is called before calling ToPolygons

public method

Translate(Single,Single)

Translates the current TRSPathData.

Translate moves the current TRSPathData for a specified distance on each axis.

public method

VLineTo(Single)

Appends a line to the current TRSPathData.

The line is defined by the end point of the TRSPathData and a point that depends on the specified parameter.

VLineTo adds the specified point to the Points array. The end point of the line is moved vertically from the last point of the TPathData to the point with the y-coordinate equal to Y. The added point is of type ppLineTo.

To move the start point of the line, call MoveTo or MoveToRel before calling VLineTo.

To find the last point of the TRSPathData, call the LastPoint method.

public method

VLineToRel(Single)

Appends a line to the current TRSPathData.

The line is defined by the end point of the TRSPathData and a point that depends on the specified parameter.

VLineToRel adds the specified point to the Points array. The The end point of the line is moved vertically by a distance equal to Y to the end point of the TRSPathData. The added point is of type ppLineTo.

To move the start point of the line, call MoveTo or MoveToRel before calling VLineToRel.

To find the last point of the TRSPathData, call the LastPoint method.

protected method

WritePath(TStream)

Writes TRSPathData to the virtual property Path (created by DefineProperties) when streaming to the TStream Stream.

Top

RiverSoftAVG Products Help

Reference