---

NSRect

Overview

An NSRect object represents a rectangle. The elemental attributes of a rectangle are its origin (its starting x coordinate and y coordinate) and its size (width and height as measured from the origin). An NSRect with height or width of 0 or less is considered an “empty” rectangle. The methods of NSRect give you access to these values and to computed values, and they allow you to compare rectangles and perform various tests, such as determining whether a point falls in a rectangle. They also convert NSRects between string objects and AWT rectangles, and they yield new NSRects based on intersection, union, inset, offset, and other operations.

Tasks

Constructors

• NSRect

Accessing Elemental Values

• height
• origin
• size
• width
• x
• y

Accessing Computed Values

• maxX
• maxY
• midX
• midY

Testing and Comparing Rectangles

• containsPoint
• equals
• hashCode
• intersectsRect
• isEmpty
• isEqualToRect
• isSubrectOfRect

Deriving Rectangles

• rectByInsettingRect
• rectByIntersectingRect
• rectByMakingIntegral
• rectByOffsettingRect
• rectByUnioningRect
• sliceRect

Transforming NSRects

• fromString
• toString
• toAWTRectangle

Copying

• clone

Static Methods

fromString

public static NSRect fromString(String rectAsString)

Discussion

Creates an NSRect from the string rectAsString, which must be of the form “{{x, y}, {w, h}}”, where x is a float representation of the origin x coordinate, y is a float representation of the origin y coordinate, w is a float representation of the width, and h is a float representation of the height. Throws an IllegalArgumentException if the string is improperly formatted.

See Also

• toString

Instance Methods

clone

Creates and returns a copy of the receiver.

public Object clone()

containsPoint

Returns whether the receiver contains the point aPoint.

public boolean containsPoint(NSPoint aPoint, boolean isFlipped)

Discussion

If isFlipped is true, the measurements occur in a flipped coordinate system (where the y axis extends down instead of up). If aPoint occurs inside or coincides with the receiver’s x axis or y axis and falls within the opposite edges of the rectangle, it is considered to be contained by the rectangle.

See Also

• intersectsRect
• isSubrectOfRect

equals

Returns whether otherObject is an NSRect and is equal in origin and size to the receiver.

public boolean equals(Object otherObject)

See Also

• isEqualToRect

hashCode

Provides an appropriate hash code useful for storing the receiver in any hash-based data structure.

public int hashCode()

Discussion

This value is the sum of the receiver’s origin x coordinate, its origin y coordinate, half of its width, and half of its height, rounded to the nearest integer.

height

Returns the height dimension of the receiver.

public float height()

See Also

• maxY
• midY
• size
• width

intersectsRect

Returns whether the receiver intersects rectangle aRect.

public boolean intersectsRect(NSRect aRect)

Discussion

Alignment of outer edges is not considered an intersection. Returns false if either NSRect is an empty rectangle.

See Also

• containsPoint
• isSubrectOfRect
• rectByIntersectingRect

isEmpty

Returns whether either dimension (width or height) of the receiver is 0.

public boolean isEmpty()

isEqualToRect

Returns whether the NSRect aRect is equal in origin and size to the receiver.

public boolean isEqualToRect(NSRect aRect)

See Also

• equals

isSubrectOfRect

Returns whether the receiver is entirely enclosed by rectangle aRect.

public boolean isSubrectOfRect(NSRect aRect)

Discussion

Coincidence of x axes and y axes or the edges opposite the x axis or y axis are acceptable. Returns false if either NSRect is an empty rectangle. By reversing receiver and argument, you can use this method as a virtual “containsRect”.

See Also

• containsPoint
• intersectsRect

maxX

Returns the farthest extent of the receiver along the x axis in the current coordinate system; or, to put it another way, the x coordinate value of the receiver’s right edge.

public float maxX()

Discussion

This value is the sum of the receiver’s origin x coordinate and its width.

See Also

• maxY

maxY

Returns the farthest extent of the receiver along the y axis in the current coordinate system; or, to put it another way, the y coordinate value of the receiver’s top edge (or bottom, if the coordinate system is flipped).

public float maxY()

Discussion

This value is the sum of the receiver’s origin y coordinate and its height.

See Also

• maxX

midX

Returns the extent of the receiver along the x axis halfway between its origin x coordinate and the x coordinate of its right edge.

public float midX()

See Also

• midY

midY

Returns the extent of the receiver along the y axis halfway between its origin y coordinate and the y coordinate of its upper edge (or bottom edge, if used in a flipped coordinate system).

public float midY()

See Also

• midX

origin

Returns the origin of the receiver, the point from which the dimensions of the receiver are measured.

public NSPoint origin()

See Also

• x
• y

rectByInsettingRect

Returns an NSRect that is the result of insetting the receiver horizInset units horizontally and vertInset units vertically from all edges.

public NSRect rectByInsettingRect(float horizInset, float vertInset)

See Also

• rectByOffsettingRect

rectByIntersectingRect

Returns an NSRect that is the result of the intersection of the receiver with otherRect.

public NSRect rectByIntersectingRect(NSRect otherRect)

Discussion

Returns ZeroRect if either receiver or otherRect is an empty rectangle or the two NSRects do not intersect at all.

See Also

• rectByUnioningRect

rectByMakingIntegral

Returns an NSRect that is the result of rounding down the receiver’s x coordinate and y coordinate to the nearest integer and rounding up the receiver’s height and width to the nearest integer.

public NSRect rectByMakingIntegral()

Discussion

The resulting rectangle thus completely encloses the original. Returns ZeroRect if the receiver is an empty rectangle.

See Also

• toAWTRectangle

rectByOffsettingRect

Returns an NSRect that is the result of offsetting the receiver horizInset units horizontally and vertInset units vertically.

public NSRect rectByOffsettingRect(float horizOffset, float vertOffset)

Discussion

This method affects the origin only, while rectByInsettingRect affects all edges.

rectByUnioningRect

Returns an NSRect that is the result of the union of the receiver with otherRect, which is a rectangle that contains the two NSRects combined.

public NSRect rectByUnioningRect(NSRect otherRect)

Discussion

Returns ZeroRect if both receiver and otherRect are empty rectangles. If one of the two rectangles, the receiver and otherRect, is an empty rectangle, a copy of the other rectangle is returned.

See Also

• rectByIntersectingRect

size

Returns the size of the receiver.

public NSSize size()

Discussion

The NSSize object encapsulates the width and height of the receiver.

See Also

• height
• origin
• width

sliceRect

Makes two smaller rectangles from the receiver and returns them by modifying two mutable rectangles passed in as arguments.

public void sliceRect(float thickness, int edge, NSMutableRect rect1, NSMutableRect rect2)

Discussion

One of these NSMutableRects has the width or height thickness as determined by the constant edge. One modified rectangle is returned in rect1 and the other in rect2; which rectangle goes where is also determined by edge. Here is a summary of how the edge constant and the other arguments interact:

If thickness is greater than the width or height of the receiver (as determined by edge), it is made the same width or height as the receiver. This method does not affect the receiver.

toAWTRectangle

Returns the receiver as a AWT Rectangle object.

public java.awt.Rectangle toAWTRectangle()

Discussion

This method calls rectByMakingIntegral to round the receiver’s float values to appropriate integers.

See Also

• toString

toString

Returns the receiver as converted to a string object.

public String toString()

Discussion

The string has the form of “{{x, y}, {w, h}}”, where x is the origin x coordinate, y is the origin y coordinate, w is the width, and h is the height.

See Also

• fromString

width

Returns the width of the receiver.

public float width()

See Also

• height
• size

x

Returns the origin x coordinate of the receiver.

public float x()

See Also

• origin
• y

y

Returns the origin y coordinate of the receiver.

public float y()

See Also

• origin
• x

Constants

NSRect provides the following constant as a convenience; you can use it to compare values returned by many NSRect methods:

The following constants can be used to specify window edges:

---