Rectangle

This object type is a native type in HiseScript and represents a two dimensional rectangle. The functionality was "inspired" (read stolen) from the JUCE class and is a helpful tool for all UI tasks.

Note that most methods create and return a new rectangle object which makes it unsuitable for any realtime thread operations, but that should not be a serious limitation as 99% of the use cases will be within paint routines or other UI related functions.

Until now, the representation of rectangles in HiseScript was a plain ol' JS array with four elements ([x, y, width, height] ). This was fine (and for backwards compatibility you can still use JS arrays to represent rectangles), but there are a few advantages of having a dedicated type for rectangles:

1. better debugging: print in one line, inspect multiple rectangles with the rectangle viewer
2. inbuilt methods for common tasks like scaling, translating and slicing rectangles

You can create a Rectangle using the inbuild function Rectangle() . This function accepts a variety of arguments to create a rectangle:

// creates an empty rectangle
var r0  = Rectangle();                   

// accepts a JS array and converts it to a Rectangle
var r1  = Rectangle([x, y, w, h]);       

// creates a rectangle at the origin position [0, 0] 
var r2a = Rectangle(width, height);      

// creates a rectangle from two points.
var r2b = Rectangle([x1, y1], [x2, y2]); 

// creates a rectangle with the given dimensions.
var r4  = Rectangle(x, y, w, h);

The rectangle can then be used / modified like a JS array but has some additional QOL methods:

Panel1.setPaintRoutine(function(g)
{
	// Create a rectangle
	var rect = Rectangle(100, 100);
	
	// Access / change members
	Console.print(rect[0]); // use the [0, 1, 2, 3] indexes like before
	Console.print(rect.x); // or use x, y, width, height
	
	rect.width = 90;
	
	// Pass that object into API calls that expect a rectangle
	g.fillRect(rect.reduced(10));
});

Note that for backwards compatibility, HISE will still use the JS arrays for all methods or callbacks that return a rectangle (eg. ScriptComponent.getLocalBounds() or the obj.area property in LAF functions). In order to change that you can enable the preprocessor HISE_USE_SCRIPT_RECTANGLE_OBJECT=1 , then it will return a Rectangle object for the full experience.

Inspect rectangles using sampling

A neat feature of the Rectangle class is that it allows you to quickly inspect the rectangles using a sampling session. These are the steps you have to take:

1. Enable sampling for a scope using the .sample("id") scoped statement
2. Use Console.sample() to add data points
3. Click on the inspect icon next to the .sample() scoped statement to open the rectangle viewer.

{
	.sample("withAspectRatioLike");
	
	var r = Rectangle(20, 10, 300, 300);
	var other = Rectangle(500, 80, 100, 50);
	
	Console.sample("target", r);
	Console.sample("other", other);	
	Console.sample("fitted", r.withAspectRatioLike(other));
}

If you now click on the icon at the top, it will open a popup that shows all items of the sampling session, in this case three rectangles that are a perfect visualisation of what the withAspectRatioLike method is doing:

Class methods

assign

Override this method and assign the new value to the given id. Edit on GitHub

Rectangle.assign( String id,  var newValue) override

constrainedWithin

Tries to fit this rectangle within a target area, returning the result.

Rectangle.constrainedWithin(var targetArea)

This function moves the rectangle into the given target area while keeping the size the same. This is useful if you eg. want to display a text at the hover position but make sure that the entire text is visible when you hover at the edges.

{
	.sample("constrainedWithin");
	
	var textPos = Rectangle(200, 20);
	var bounds = Rectangle(100, 100, 400, 300);
	
	Console.sample("bounds", bounds);
	Console.sample("textBounds", textPos);
	Console.sample("fitted", textPos.constrainedWithin(bounds));
}

Result:

contains

Returns true if this other rectangle is completely inside this one. Edit on GitHub

Rectangle.contains(var otherRectOrPoint)

expanded

Returns a rectangle that is larger than this one by a given amount. Edit on GitHub

Rectangle.expanded(double x, double optionalY)

getIntersection

Returns the intersection of both rectangles (the largest rectangle that fits into both rectangles. Edit on GitHub

Rectangle.getIntersection(var otherRect)

getUnion

Returns the smallest rectangle that contains both this one and the one passed-in.

Rectangle.getUnion(var otherRect)

{
	.sample("getUnion");
	
	var r1 = Rectangle(10, 50, 90, 65);
	var r2 = Rectangle(300, 200, 10, 55);
	
	Console.sample("r1", r1);
	Console.sample("r2", r2);
	Console.sample("union", r1.getUnion(r2));
}

Result:

intersects

Returns true if any part of another rectangle overlaps this one. Edit on GitHub

Rectangle.intersects(var otherRect)

isEmpty

Returns true if the rectangle's width or height are zero or less. Edit on GitHub

Rectangle.isEmpty()

reduced

Returns a rectangle that is smaller than this one by a given amount.

Rectangle.reduced(double x, double optionalY)

This function can be called with either one or two arguments. If you call it with two arguments, it will be reduced with different X / Y values, if you call it with one argument, it will reduce all sides equally:

{
	.sample("reduced");
	
	var x = Rectangle(20, 20, 400, 200);
	
	Console.sample("before", x);
	Console.sample("afterTwoArgs", x.reduced(50, 20));
	Console.sample("afterOneArg", x.reduced(30));
}

removeFromBottom

Removes a strip from the bottom of this rectangle, reducing this rectangle by the specified amount and returning the section that was removed.

Rectangle.removeFromBottom(double numToRemove)

This function (and it's siblings removeFromLeft(), removeFromRight() and removeFromTop() are incredibly useful to divide a rectangle into different areas for layout purposes (eg. rendering a text label beyond a slider knob). Note that calling this method modifies the rectangle, slices off and returns the part.

{
	.sample("slicing");
	
	var r = Rectangle(20, 20, 500, 400);
	
	Console.sample("full", r);
	
	var top = r.removeFromTop(50);
	
	Console.sample("topLeft", top.removeFromLeft(50));
	Console.sample("top", top);
	Console.sample("remaining", r);
};

Result:

removeFromLeft

Removes a strip from the left of this rectangle, reducing this rectangle by the specified amount and returning the section that was removed. Edit on GitHub

Rectangle.removeFromLeft(double numToRemove)

removeFromRight

Removes a strip from the right of this rectangle, reducing this rectangle by the specified amount and returning the section that was removed. Edit on GitHub

Rectangle.removeFromRight(double numToRemove)

removeFromTop

Removes a strip from the top of this rectangle, reducing this rectangle by the specified amount and returning the section that was removed. Edit on GitHub

Rectangle.removeFromTop(double numToRemove)

scaled

Returns a rectangle with the position and size being scaled by the given factors. Edit on GitHub

Rectangle.scaled(double factorX, double optionalFactorY)

setCentre

Changes the position of the rectangle's centre (leaving its size unchanged). Edit on GitHub

Rectangle.setCentre(double centerX, double centerY)

setPosition

Changes the position of the rectangle's top-left corner (leaving its size unchanged). Edit on GitHub

Rectangle.setPosition(double x, double y)

setSize

Changes the rectangle's size, leaving the position of its top-left corner unchanged. Edit on GitHub

Rectangle.setSize(double width, double height)

toArray

Returns a standard JS array with the position [x, y, w, h]. Edit on GitHub

Rectangle.toArray()

translated

Returns a rectangle which is the same as this one moved by a given amount. Edit on GitHub

Rectangle.translated(double deltaX, double deltaY)

withAspectRatioLike

Returns the biggest rectangle that fits in this rectangle using the aspect ratio of the other rectangle.

Rectangle.withAspectRatioLike(var otherRect)

This method is useful if you have a path that you want to render somewhere while keeping it's aspect ratio the same.

{
	.sample("withAspectRatioLike");
	
	var r = Rectangle(20, 10, 300, 300]);
	var other = Rectangle(500, 80, 100, 50);
	
	Console.sample("target", r);
	Console.sample("other", other);	
	Console.sample("fitted", r.withAspectRatioLike(other));
}

Result:

withBottom

Returns a new rectangle with a different bottom edge position, but the same top edge as this one. Edit on GitHub

Rectangle.withBottom(double newBottom)

withBottomY

Returns a rectangle which has the same size and x-position as this one, but whose bottom edge has the given position. Edit on GitHub

Rectangle.withBottomY(double newBottomY)

withCentre

Returns a rectangle with the same size as this one, but a new centre position. Edit on GitHub

Rectangle.withCentre(double newWidth, double newHeight)

withHeight

Returns a rectangle which has the same position and width as this one, but with a different height. Edit on GitHub

Rectangle.withHeight(double newHeight)

withLeft

Returns a new rectangle with a different x position, but the same right-hand edge as this one. Edit on GitHub

Rectangle.withLeft(double newLeft)

withRight

Returns a new rectangle with a different right-hand edge position, but the same left-hand edge as this one. Edit on GitHub

Rectangle.withRight(double newRight)

withSize

Returns a rectangle with the same top-left position as this one, but a new size. Edit on GitHub

Rectangle.withSize(double newWidth, double newHeight)

withSizeKeepingCentre

Returns a rectangle with the same centre position as this one, but a new size.

Rectangle.withSizeKeepingCentre(double newWidth, double newHeight)

This is useful if you want to draw something with a centered alignment.

{
	.sample("withSizeKeepingCentre");
	
	var x = Rectangle(10, 10, 300, 300);
	
	Console.sample("bounds", x);
	Console.sample("smaller", x.withSizeKeepingCentre(50, 50));
}

withTrimmedBottom

Returns a version of this rectangle with the given amount removed from its bottom edge. Edit on GitHub

Rectangle.withTrimmedBottom(double amountToRemove)

withTrimmedLeft

Returns a version of this rectangle with the given amount removed from its left-hand edge. Edit on GitHub

Rectangle.withTrimmedLeft(double amountToRemove)

withTrimmedRight

Returns a version of this rectangle with the given amount removed from its right-hand edge. Edit on GitHub

Rectangle.withTrimmedRight(double amountToRemove)

withTrimmedTop

Returns a version of this rectangle with the given amount removed from its top edge. Edit on GitHub

Rectangle.withTrimmedTop(double amountToRemove)

withWidth

Returns a rectangle which has the same position and height as this one, but with a different width. Edit on GitHub

Rectangle.withWidth(double newWidth)

withX

Returns a rectangle which has the same size and y-position as this one, but with a different x-position. Edit on GitHub

Rectangle.withX(double newX)

withY

Returns a rectangle which has the same size and x-position as this one, but with a different y-position. Edit on GitHub

Rectangle.withY(double newY)