rectangletweak(
RECTANGLE
,
TRANSFORM
,
VALUE
)

The rectangletweak( function transforms a rectangle by changing its position and/or size.


Parameters

This function has three parameters:

rectangle – the original rectangle.

transform – the type of transformation to make to the rectangle. Available options are: x, y, top, left, right, bottom, height, width and size. Some of these options can be modified with a prefix of + or *, and/or with a suffix of fromcenter, frombottom or fromright. See the discussion below for additional details.

value – the value used for transforming the rectangle. Usually this is in points, but when the * prefix is used, it is a multiplication factor.


Description

This function transforms a rectangle by changing its position and/or size.

Note: For all of the examples below, we’ll assume that there is a variable called demoRect that contains a rectangle with co-ordinates of 100,200,300,400 (top, left, bottom, right).

local demoRect
demoRect = rectangle(100,200,300,400)

In all of the examples below, the resulting rectangles are displayed in the format top, left, bottom, right, the format generated by the rectanglestr( function.

RECTANGLE POSITION

This section describes how to change the position of the rectangle without changing its size. To position the rectangle at a certain horizontal location, use the x option.

rectangletweak(demoRect,"x",160) ☞ 100,160,300,360

To position the rectangle at a certain vertical location, use the y option.

rectangletweak(demoRect,"y",50) ☞ 50,200,250,400

Use the + prefix to shift the rectangle instead of positioning it in an absolute location. This example shifts the rectangle 25 points to the right.

rectangletweak(demoRect,"+x",25) ☞ 100,225,300,425

Use negative values to move the rectangle up or to the left. This example moves the rectangle up 25 points.

rectangletweak(demoRect,"+y",-25) ☞ 75,200,275,400

You can add multiple transform/value pairs to a single rectangle. This example moves the rectangle down 20 points and then 30 points to the right.

rectangletweak(demoRect,"+y",20,"+x",30) ☞ 120,230,320,430

When multiple transforms are provided they are performed as they encountered from left to right.

RECTANGLE EDGES

Use the top, left, right and bottom transforms to move edges of the rectangle independently. This example sets the top edge to 50 while leaving the other edges undisturbed, although the lengths of some sides will change.

rectangletweak(demoRect,"top",50) ☞ 50,200,300,400

Use the + prefix to shift the edge instead of positioning it in an absolute location. This example moves the right edge 15 points to the right while leaving the other edges undisturbed, although the lengths of some sides will change.

rectangletweak(demoRect,"+right",15) ☞ 100,200,300,415

RECTANGLE SIZE

Use the height, width and size transforms to change the size of the rectangle. These transforms leave the upper left corner of the rectangle in a fixed position while changing the size (but see below for other options). This example sets the width to 240 points.

rectangletweak(demoRect,"width",240) ☞ 100,200,300,440

Use the + prefix to modify the dimension instead of setting it to an absolute value. The first example increases the height by 20 points while leaving the top-left corner unmoved. The second example increases both the height and width by 20 points while leaving the top-left corner unmoved.

rectangletweak(demoRect,"+height",20) ☞ 100,200,320,400
rectangletweak(demoRect,"+size",20) ☞ 100,200,320,420

Adding the suffix fromcenter, frombottom or fromright to the transform name changes which edge of the rectangle remains fixed. This example sets the height to 75 by moving the top edge of the rectangle, leaving the bottom edge fixed.

rectangletweak(demoRect,"heightfrombottom",75) ☞ 225,200,300,400

You can combine the + prefix with these suffixes. The first example makes the rectangle 2 points narrower, while leaving the center at 300. The second example makes the rectangle 20 points taller and wider.

rectangletweak(demoRect,"+widthfromcenter",-2) ☞ 100,201,300,399
rectangletweak(demoRect,"+sizefromcenter",20) ☞ 90,190,310,410

Note: frombottom can only be used with height, fromright can only be used with width. fromcenter can be used with height, width or size

MULTIPLICATION FACTOR

Use the * prefix to modify any dimension by multiplication instead of addition. When this prefix is used, the value is a multiplication factor. Values greater than one will make the rectangle larger, values smaller than one will make it smaller. This example shrinks the rectangle to half its original size (but still centered on the same spot).

rectangletweak(demoRect,"*sizefromcenter",0.5) ☞ 150,250,250,350

This example makes the rectangle 20% wider, leaving the left edge fixed in position.

rectangletweak(demoRect,"*width",1.2) ☞ 100,200,300,440

LIMITS

The rectangletweak( function has additional transforms that can be applied to limit the final coordinates of the rectangle. Use minx, miny, maxx and maxy to limit the position of the rectangle. These transformations preserve the height and width of the rectangle but prevent the edges from going past the specified limits. In this example, the +x transform would normally push the left edge of the rectangle out to 40, but the minimum prevents it from going past 50.

rectangletweak(demoRect,"+x",-160,"minx",50) ☞ 100,50,300,250

The maxy and maxx limit how far down and to the right the bottom right corner of the rectangle can go. In this example the bottom edge would normally go to 500, but is limited to 450.

rectangletweak(demoRect,"+x",+200,"maxy",450) ☞ 250,200,450,400

Use minleft, mintop, maxright and maxbottom to limit the position of individual edges of the rectangle. Note: These limits can change the height and width of the rectangle.

Use minwidth, minheight and minsize to limit the minimum dimensions of the output rectangle. Add a suffix of fromcenter, fromright or frombottom to specify which co-ordinate of the rectangle should remain fixed. In this example the output rectangle would normally have a height and width of 20 points, but the limit forces them both to 30 points.

rectangletweak(demoRect,"*sizefromcenter",0.1,"minsizefromcenter",30) ☞ 185,285,215,315

You can chain multiple limits one after the other – in that case the limits will be processed from left to right.


Error Messages

rectangletweak( function error – negative rectangle height/width – If the tweaked rectangle has a negative width or height, an error occurs. You can add the transform "minsize",0 to prevent this error (or "minsizefromcenter",0).


See Also


History

VersionStatusNotes
10.0NewNew in this version.