moveShapesRandomlyOnGrid

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

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

Unlike the regular moveShapesOnGrid() function, this function randomly orders the shapes as it positions them on the grid; that is, rather than arranging the shapes as specified in the parameter list  – shape #1 followed by shape #2 followed by shape #3, etc. – this function selects the shapes randomly as it positions them on the grid.

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.  Each shape is selected at random (but only once) and placed on the grid, so the order will be different each time.

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 9 black shapes and 1 pink shape on a 5×2 grid centred on that square.  Every two seconds it rearranges the shapes on the grid, so you will see the pink square move around.  Note that there is nothing that prevents the pink square from being randomly positioned at the same location more than once, or more than once in a row.


// Create some colours

define white = #FFFFFF

define pink = #FF2398

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%


// 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 < 9

       define shape = create BlackOutlineRectangleTemplate

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

       counter += 1

end while


// Add one more rectangle, this is the only pink rectangle

define pinkRectangle = create BlackOutlineRectangleTemplate

pinkRectangle.colour = pink

shapes += pinkRectangle


// Finally, we can test our rectangle function

counter = 0

while counter < 10

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

       counter += 1


       wait 2sec

end while



Here’s a screen shot of what this looks like in action (notice that the pink shape is not in the bottom right, even though it was the last item in the collection):