, , )

---

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

• adjustxy( -- adjusts the four corners of a rectangle. However, only corners that are inside a boundary are adjusted. Corners outside the boundary are left alone.
• bestfitrectangle -- fits a rectangle within a boundary rectangle, enlarging or reducing as necessary to produce the best fit without changing the proportions.
• bestfitrectangle( -- fits a rectangle within a boundary rectangle, enlarging or reducing as necessary to produce the best fit without changing the proportions.
• calcenclosingrectangle -- will calculate the rectangle surrounding all of the specified objects.
• getbutton -- retrieves the coordinates of the last button that was pressed (in global screen co-ordinates).
• getclick -- returns the location of the mouse in global coordinates (coordinates from the top left corner of the screen).
• getinternalbutton -- retrieves the coordinates of the last button that was pressed (in form relative coordinates).
• getlocalbutton -- retrieves the coordinates of the last button that was pressed (in window relative coordinates).
• getlocalclick -- returns the location of the most recent mouse click in local coordinates (coordinates from the top left corner of the current form).
• h( -- extracts the horizontal position from a point (see point(, Graphic Coordinates).
• info("availablescreenrectangle") -- returns a rectangle defining the edges of the main screen, after deducting for the space of the menu bar and dock (if visible).
• info("formxy") -- returns a point that indicates how much the current form is scrolled (if at all).
• info("screenrectangle") -- returns a rectangle defining the edges of the main screen.
• inrectangle( -- checks to see if a point is inside a rectangle.
• integralpoint( -- converts point coordinates to integers.
• integralrectangle( -- converts rectangle coordinates to integers.
• intersectionrectangle( -- creates a rectangle by combining two rectangles. The new rectangle is the area where the two rectangles overlap (if any).
• maprectangle( -- maps the position and size of a rectangle within a template rectangle into the same relative position and size within a goal rectangle.
• Modifiable Object Properties -- describes the properties of graphic objects that can be modified by a program (dimensions, color, font, title, etc.).
• moveobjects -- will move an object or group of objects up, down, left or right on the form.
• nsrect( -- defines a rectangle using the same parameter order as the Cocoa NSMakeRect( function.
• nsrectstr( -- converts a rectangle into text in the format x,y,width,height
• pinrectangle( -- pins a rectangle within the bounds of a larger rectangle.
• point( -- combines vertical and horizontal co-ordinates into a single binary value that describes the position of a point (see Graphic Coordinates).
• pointstr( -- converts a point value into text in the format v,h (for example 34,56).
• rbottom( -- extracts the position of the bottom edge of a rectangle (see rectangle(, Graphic Coordinates).
• rectangle( -- defines a rectangle from four dimensions.
• rectangleadjust( -- adjusts all four edges of a rectangle independently
• rectanglealign( -- aligns a small rectangle at one of nine positions within a larger rectangle.
• rectanglecenter( -- adjusts a rectangle so that it is centered inside of another rectangle.
• rectangleinset( -- insets a rectangle by a specified amount.
• rectangleoffset( -- offsets a rectangle to a new position.
• rectanglesize( -- defines a rectangle from its upper left hand corner and its height and width.
• rectanglesizestr( -- converts a rectangle into text in the format *top,left,height,width*.
• rectanglestr( -- converts a rectangle into text in the format *top,left,bottom,right*.
• rheight( -- extracts the height of a rectangle (see rectangle(, Graphic Coordinates).
• rleft( -- extracts the position of the left edge of a rectangle (see rectangle(, Graphic Coordinates).
• rright( -- extracts the position of the right edge of a rectangle (see rectangle(, Graphic Coordinates).
• rtop( -- extracts the position of the top edge of a rectangle (see rectangle(, Graphic Coordinates).
• rwidth( -- extracts the width of a rectangle (see rectangle(, Graphic Coordinates).
• setrectangleheight( -- changes the height of a rectangle, leaving the width unchanged.
• setrectanglesize( -- changes the height and width of a rectangle, leaving the position of the top left hand corner unchanged.
• setrectanglewidth( -- changes the width of a rectangle, leaving the height unchanged.
• setrectedges -- changes the edges of the specified rectangle.
• tweakobject -- tweaks the dimensions of an object (or multiple objects).
• unionrectangle( -- creates a rectangle by combining two rectangles. The new rectangle is large enough to exactly cover both of the input rectangles.
• v( -- returns the vertical position of a point (see point(, Graphic Coordinates).
• xytoxy( -- converts a point or rectangle from one co-ordinate system to another.

---

History

Version	Status	Notes
10.0	New	New in this version.