org.eclipse.swt.graphics

Class Path

java.lang.Object

org.eclipse.swt.graphics.Resource

org.eclipse.swt.graphics.Path

public class Path
extends Resource

Instances of this class represent paths through the two-dimensional coordinate system. Paths do not have to be continuous, and can be described using lines, rectangles, arcs, cubic or quadratic bezier curves, glyphs, or other paths.

Application code must explicitly invoke the Path.dispose() method to release the operating system resources managed by each instance when those instances are no longer required.

This class requires the operating system's advanced graphics subsystem which may not be available on some platforms.

Since:

3.1

See Also:

Path, Pattern snippets, SWT Example: GraphicsExample, Sample code and further information

Structure Diagram

Field Summary

Fields

Modifier and Type	Field and Description
(package private) PointF	currentPoint
int	handle the OS resource for the Path (Warning: This field is platform dependent) IMPORTANT: This field is not part of the SWT public API.
(package private) PointF	startPoint

Fields inherited from class org.eclipse.swt.graphics.Resource

device

Constructor Summary

Constructors

Constructor and Description
Path(Device device) Constructs a new empty Path.
Path(Device device, PathData data) Constructs a new Path with the specifed PathData.
Path(Device device, Path path, float flatness) Constructs a new Path that is a copy of path.

Method Summary

Methods

Modifier and Type	Method and Description
void	addArc(float x, float y, float width, float height, float startAngle, float arcAngle) Adds to the receiver a circular or elliptical arc that lies within the specified rectangular area.
void	addPath(Path path) Adds to the receiver the path described by the parameter.
void	addRectangle(float x, float y, float width, float height) Adds to the receiver the rectangle specified by x, y, width and height.
void	addString(java.lang.String string, float x, float y, Font font) Adds to the receiver the pattern of glyphs generated by drawing the given string using the given font starting at the point (x, y).
void	close() Closes the current sub path by adding to the receiver a line from the current point of the path back to the starting point of the sub path.
boolean	contains(float x, float y, GC gc, boolean outline) Returns true if the specified point is contained by the receiver and false otherwise.
void	cubicTo(float cx1, float cy1, float cx2, float cy2, float x, float y) Adds to the receiver a cubic bezier curve based on the parameters.
(package private) void	destroy()
void	getBounds(float[] bounds) Replaces the first four elements in the parameter with values that describe the smallest rectangle that will completely contain the receiver (i.e. the bounding box).
void	getCurrentPoint(float[] point) Replaces the first two elements in the parameter with values that describe the current point of the path.
PathData	getPathData() Returns a device independent representation of the receiver.
(package private) void	init(PathData data)
boolean	isDisposed() Returns true if the Path has been disposed, and false otherwise.
void	lineTo(float x, float y) Adds to the receiver a line from the current point to the point specified by (x, y).
void	moveTo(float x, float y) Sets the current point of the receiver to the point specified by (x, y).
void	quadTo(float cx, float cy, float x, float y) Adds to the receiver a quadratic curve based on the parameters.
java.lang.String	toString() Returns a string containing a concise, human-readable description of the receiver.

Methods inherited from class org.eclipse.swt.graphics.Resource

dispose, getDevice, init

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

handle

public int handle

the OS resource for the Path (Warning: This field is platform dependent)

IMPORTANT: This field is not part of the SWT public API. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms and should never be accessed from application code.

currentPoint

PointF currentPoint

startPoint

PointF startPoint

Constructor Detail

Path

public Path(Device device)

Constructs a new empty Path.

This operation requires the operating system's advanced graphics subsystem which may not be available on some platforms.

Parameters:

device - the device on which to allocate the path

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the device is null and there is no current device

SWTException -

• ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available

SWTError -

• ERROR_NO_HANDLES if a handle for the path could not be obtained

See Also:

Resource.dispose()

Path

public Path(Device device,
    Path path,
    float flatness)

Constructs a new Path that is a copy of path. If flatness is less than or equal to zero, an unflatten copy of the path is created. Otherwise, it specifies the maximum error between the path and its flatten copy. Smaller numbers give better approximation.

This operation requires the operating system's advanced graphics subsystem which may not be available on some platforms.

Parameters:

device - the device on which to allocate the path

path - the path to make a copy

flatness - the flatness value

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the device is null and there is no current device
• ERROR_NULL_ARGUMENT - if the path is null
• ERROR_INVALID_ARGUMENT - if the path has been disposed

SWTException -

• ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available

SWTError -

• ERROR_NO_HANDLES if a handle for the path could not be obtained

Since:

3.4

See Also:

Resource.dispose()

Path

public Path(Device device,
    PathData data)

Constructs a new Path with the specifed PathData.

This operation requires the operating system's advanced graphics subsystem which may not be available on some platforms.

Parameters:

device - the device on which to allocate the path

data - the data for the path

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the device is null and there is no current device
• ERROR_NULL_ARGUMENT - if the data is null

SWTException -

• ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available

SWTError -

• ERROR_NO_HANDLES if a handle for the path could not be obtained

Since:

3.4

See Also:

Resource.dispose()

Method Detail

addArc

public void addArc(float x,
          float y,
          float width,
          float height,
          float startAngle,
          float arcAngle)

Adds to the receiver a circular or elliptical arc that lies within the specified rectangular area.

The resulting arc begins at startAngle and extends for arcAngle degrees. Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

The center of the arc is the center of the rectangle whose origin is (x, y) and whose size is specified by the width and height arguments.

The resulting arc covers an area width + 1 pixels wide by height + 1 pixels tall.

Parameters:

x - the x coordinate of the upper-left corner of the arc

y - the y coordinate of the upper-left corner of the arc

width - the width of the arc

height - the height of the arc

startAngle - the beginning angle

arcAngle - the angular extent of the arc, relative to the start angle

Throws:

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

addPath

public void addPath(Path path)

Adds to the receiver the path described by the parameter.

Parameters:

path - the path to add to the receiver

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the parameter is null
• ERROR_INVALID_ARGUMENT - if the parameter has been disposed

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

addRectangle

public void addRectangle(float x,
                float y,
                float width,
                float height)

Adds to the receiver the rectangle specified by x, y, width and height.

Parameters:

x - the x coordinate of the rectangle to add

y - the y coordinate of the rectangle to add

width - the width of the rectangle to add

height - the height of the rectangle to add

Throws:

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

addString

public void addString(java.lang.String string,
             float x,
             float y,
             Font font)

Adds to the receiver the pattern of glyphs generated by drawing the given string using the given font starting at the point (x, y).

Parameters:

string - the text to use

x - the x coordinate of the starting point

y - the y coordinate of the starting point

font - the font to use

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the font is null
• ERROR_INVALID_ARGUMENT - if the font has been disposed

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

close

public void close()

Closes the current sub path by adding to the receiver a line from the current point of the path back to the starting point of the sub path.

Throws:

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

contains

public boolean contains(float x,
               float y,
               GC gc,
               boolean outline)

Returns true if the specified point is contained by the receiver and false otherwise.

If outline is true, the point (x, y) checked for containment in the receiver's outline. If outline is false, the point is checked to see if it is contained within the bounds of the (closed) area covered by the receiver.

Parameters:

x - the x coordinate of the point to test for containment

y - the y coordinate of the point to test for containment

gc - the GC to use when testing for containment

outline - controls whether to check the outline or contained area of the path

Returns:

true if the path contains the point and false otherwise

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the gc is null
• ERROR_INVALID_ARGUMENT - if the gc has been disposed

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

cubicTo

public void cubicTo(float cx1,
           float cy1,
           float cx2,
           float cy2,
           float x,
           float y)

Adds to the receiver a cubic bezier curve based on the parameters.

Parameters:

cx1 - the x coordinate of the first control point of the spline

cy1 - the y coordinate of the first control of the spline

cx2 - the x coordinate of the second control of the spline

cy2 - the y coordinate of the second control of the spline

x - the x coordinate of the end point of the spline

y - the y coordinate of the end point of the spline

Throws:

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

destroy

void destroy()

Overrides:

destroy in class Resource

getBounds

public void getBounds(float[] bounds)

Replaces the first four elements in the parameter with values that describe the smallest rectangle that will completely contain the receiver (i.e. the bounding box).

Parameters:

bounds - the array to hold the result

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the parameter is null
• ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the bounding box

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

getCurrentPoint

public void getCurrentPoint(float[] point)

Replaces the first two elements in the parameter with values that describe the current point of the path.

Parameters:

point - the array to hold the result

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the parameter is null
• ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the end point

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

getPathData

public PathData getPathData()

Returns a device independent representation of the receiver.

Returns:

the PathData for the receiver

Throws:

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

See Also:

PathData

lineTo

public void lineTo(float x,
          float y)

Adds to the receiver a line from the current point to the point specified by (x, y).

Parameters:

x - the x coordinate of the end of the line to add

y - the y coordinate of the end of the line to add

Throws:

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

init

void init(PathData data)

isDisposed

public boolean isDisposed()

Returns true if the Path has been disposed, and false otherwise.

This method gets the dispose state for the Path. When a Path has been disposed, it is an error to invoke any other method (except Resource.dispose()) using the Path.

Specified by:

isDisposed in class Resource

Returns:

true when the Path is disposed, and false otherwise

moveTo

public void moveTo(float x,
          float y)

Sets the current point of the receiver to the point specified by (x, y). Note that this starts a new sub path.

Parameters:

x - the x coordinate of the new end point

y - the y coordinate of the new end point

Throws:

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

quadTo

public void quadTo(float cx,
          float cy,
          float x,
          float y)

Adds to the receiver a quadratic curve based on the parameters.

Parameters:

cx - the x coordinate of the control point of the spline

cy - the y coordinate of the control point of the spline

x - the x coordinate of the end point of the spline

y - the y coordinate of the end point of the spline

Throws:

SWTException -

• ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

toString

public java.lang.String toString()

Returns a string containing a concise, human-readable description of the receiver.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the receiver