Class 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
    • Field Summary

      Fields 
      Modifier and Type Field Description
      long handle
      the OS resource for the Path (Warning: This field is platform dependent)
    • Constructor Summary

      Constructors 
      Constructor Description
      Path​(Device device)
      Constructs a new empty Path.
      Path​(Device device, PathData data)
      Constructs a new Path with the specified PathData.
      Path​(Device device, Path path, float flatness)
      Constructs a new Path that is a copy of path.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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​(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.
      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.
      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.
      String toString()
      Returns a string containing a concise, human-readable description of the receiver.
    • Field Detail

      • handle

        public long 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.

        Restriction:
        This field is not intended to be referenced by clients.
    • 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.

        You must dispose the path when it is no longer required.

        Parameters:
        device - the device on which to allocate the path
        Throws:
        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.

        You must dispose the path when it is no longer required.

        Parameters:
        device - the device on which to allocate the path
        path - the path to make a copy
        flatness - the flatness value
        Throws:
        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 specified PathData.

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

        You must dispose the path when it is no longer required.

        Parameters:
        device - the device on which to allocate the path
        data - the data for the path
        Throws:
        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 points wide by height + 1 points 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:
        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​(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:
        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:
        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
      • 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:
        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:
        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
      • 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 String toString()
        Returns a string containing a concise, human-readable description of the receiver.
        Overrides:
        toString in class Object
        Returns:
        a string representation of the receiver