# Class Surround

java.lang.Object
uk.ac.starlink.ttools.plot2.Surround

public class Surround extends Object
Describes the area outside a rectangle reserved for annotations. A `Surround.Block` is attached to each side of the rectangle.

This does a somewhat similar job to `Insets`, but provides more detail about what's happening at the corners.

Since:
  7 Dec 2022
Author:
  Mark Taylor

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`Surround.Block`
Represents the space taken along one side of a rectangle.

## Field Summary

Fields
Modifier and Type
Field
Description
`Surround.Block`
`bottom`
`Surround.Block`
`left`
`Surround.Block`
`right`
`Surround.Block`
`top`

## Constructor Summary

Constructors
Constructor
Description
`Surround()`
Constructs a new Surround with no reserved space.
`Surround(Surround other)`
Clone constructor.
`Surround(Surround.Block top, Surround.Block left, Surround.Block bottom, Surround.Block right)`
Constructs a surround with provided blocks.

## Method Summary

Modifier and Type
Method
Description
`Surround`
`add(Surround other)`
Adds another surround to this one.
`boolean`
`addExternalRectangle(Rectangle inner, Rectangle addBox)`
Extends this surround by a given rectangle assumed to be attached to one of the edges of a supplied inner rectangle.
`static Surround`
`fromInsets(Insets insets)`
Creates a Surround from an Insets.
`Rectangle[]`
`getRegions(Rectangle inner)`
Returns an array of four rectangles giving the areas described by this object as applied to a given inner rectangle.
`Insets`
`toExtentInsets()`
Returns an Insets object representing only the space corresponding to the Extent parts of this Surround.
`Insets`
`toInsets()`
Returns an Insets object representing all the space reserved by this Surround.
`String`
`toString()`
`Surround`
`union(Surround other)`
Returns a new surround that represents the union of the areas represented by this one and a supplied one.

### Methods inherited from class Object

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

## Field Details

### top

public Surround.Block top

### left

public Surround.Block left

### bottom

public Surround.Block bottom

### right

public Surround.Block right

## Constructor Details

### Surround

public Surround()
Constructs a new Surround with no reserved space.

### Surround

public Surround(Surround other)
Clone constructor. Creates a deep copy of a template surround.

Parameters:
  `other` - template

### Surround

public Surround(Surround.Block top, Surround.Block left, Surround.Block bottom, Surround.Block right)
Constructs a surround with provided blocks.

Parameters:
  `top` - block for top side
  `left` - block for left side
  `bottom` - block for bottom side
  `right` - block for right side

## Method Details

### toInsets

public Insets toInsets()
Returns an Insets object representing all the space reserved by this Surround.

Returns:
  new Insets

### toExtentInsets

public Insets toExtentInsets()
Returns an Insets object representing only the space corresponding to the Extent parts of this Surround. The over- and under-hang regions are ignored.

Returns:
  new Insets

### getRegions

public Rectangle[] getRegions(Rectangle inner)
Returns an array of four rectangles giving the areas described by this object as applied to a given inner rectangle.

Parameters:
  `inner` - inner rectangle
Returns:
  rectangles for (top, left, bottom, right) blocks

### addExternalRectangle

public boolean addExternalRectangle(Rectangle inner, Rectangle addBox)
Extends this surround by a given rectangle assumed to be attached to one of the edges of a supplied inner rectangle. Attached to an edge means that it does not overlap with the inner rectangle, but that it is not entirely contained in one of the external "corner zones" defined by the inner rectangle. If it is not attached to an edge in this sense, no action will be taken, and the return value will be false.

Parameters:
  `inner` - inner rectangle
  `addBox` - external box to add to this surround
Returns:
  true iff the supplied box was a suitable external rectangle, indicating that an extension may have been made

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### add

public Surround add(Surround other)
Adds another surround to this one. Block extents are stacked, but under and over regions are set to the larger value.

Parameters:
  `other` - surround to add to this one
Returns:
  new surround

### union

public Surround union(Surround other)
Returns a new surround that represents the union of the areas represented by this one and a supplied one.

Parameters:
  `other` - other surround
Returns:
  new surround

### fromInsets

public static Surround fromInsets(Insets insets)
Creates a Surround from an Insets. The resulting blocks have extents, but no under or over parts.

Parameters:
  `insets` - insets object
Returns:
  new Surround