moveShapesOnGrid

moveShapesOnGrid( referenceShape, width, height, rows, columns, shapes… )

Arranges the shape(s) in a grid that is centered on the referenceShape.

The location of each shape is saved into the database and automatically associated with the current session, trial and phase (if applicable).

This function is quite handy when you need to move more than one shape at a time and want them all arranged in a rectangle.

Arguments

referenceShape

- the reference shape (this shape is not moved) acts as the centre of the imaginary grid on which the other shapes will be placed.   Note that this shape does not need to be visible to use it as the reference shape.

width

- The width of the imaginary grid on which you want to place the shapes

height

- The height of the imaginary grid on which you want to place the shapes

rows

- The number of rows (of shapes) in the grid that your shapes will be arranged in.

columns

- The number of columns (of shapes) in the grid that your shapes will be arranged in.

shapes…

- Any number of shapes to move, or a collection of shapes.  Each shape will be placed on the imaginary grid centred on the reference shape.  The first of these shapes will be positioned at the top-left of the rectangle, and then are placed left-to-right and top-to-bottom.

Diagram

The following diagram attempts to depict exactly how the moveShapesOnGrid function actually arranges the shapes on  an example grid with three rows and three columns.

Returns

The number of shapes that were moved, which is always the number of shapes passed in.

Example

The following displays a black rectangle in the centre of the screen, and then arranges 10 coloured squares in a 5×2 grid centred on that square.


// Create some colours

define white = #FFFFFF

define green = #55AA2B

define red = #FF0000

define blue = #0000FF

define fuchsia = #FF00FF

define orange = #FFA500

define maroon = #800000

define yellow = #FFF651

define pink = #FF2398

define mouve = #A593FF

define black = #000000


// Set up the screen with some decent margins

screen.Colour = white

screen.MarginTop = 20%

screen.MarginBottom = 20%

screen.MarginLeft = 23%

screen.MarginRight = 23%


// For easier use, put all the colours in a collection

define collection ColoursCollectionType

       green

       red

       blue

       fuchsia

       orange

       maroon

       yellow

       pink

       mouve

       black

end collection

define colours = create ColoursCollectionType


// Now we need the rectangle template

define type of rectangle BlackOutlineRectangleTemplate

       Colour = black

       lineColour = black

       lineThickness = 1

       width = 100

       height = 100

       isVisible = true

end rectangle


// We need an invisible rectangle in the centre of the screen

// which will be our reference shape

define centreRect = create BlackOutlineRectangleTemplate

centreRect.IsVisible = true

centreRect.X = 50%

centreRect.Y = 50%


// Now we’re going to create an empty collection

define type of collection EmptyCollectionType

       // Empty  – we’ll add items in a minute

end collection

define shapes = create EmptyCollectionType


// Now create some shapes to position in a rectangle

define counter = 0

while counter < 10

       define shape = create BlackOutlineRectangleTemplate

       shapes += shape        // Add the new shape to our collection of shapes

       counter += 1

end while


// Now give each shape a unique colour

colourShapes( colours, shapes )


// Finally, we can test our rectangle function

moveShapesOnRectangle( centreRect, width=100%, height=100%, rows=2, columns=5, shapes )


wait 1min


Here’s a screen shot of what this looks like in action: