moveShapes

moveShapes( minimumDistance, shapeToMove1, shapeToMove2, … )

Attempts to move all of the shapeToMove# arguments that are passed in (you may pass in as many as you want) somewhere on the screen without overlapping any of the other shapes that are on the screen – even if those other shapes are not currently visible (that is, their IsVisible property is False) while keeping each shapeToMove# at least minimumDistance away from any other shape and any previous shapeToMove# that was placed by the function.

The location of the shapes that are moved are saved into the database and automatically associated with the current session, trial and phase (if applicable).

Note that just like the moveShape(…) function, using moveShapeN creates the dedicated “moved” event in the Events table within the database.

Arguments

minimumDistance

- the  minimum distance away from every other shape that the shapes to move should be placed.

This value may be either absolute or a percent; if it is a percent then it is a percentage of the larger of the screen’s width and height.

shapeToMove#

- You may pass in any number of shapes that you want to be moved.

Returns

The number of shapes that were moved; if you have very large screen margins, or a very small screen, or a large minimum distance, or large number of shapes to move (or any combination of these) it may not be possible for the moveShapeN() function to position all of the shapes on the screen before it runs out of “space”.  Therefore, the function returns the number of shapes that were successfully moved.  If this number is different than the number of shapes you were trying to move then the last shapes you passed in were not moved.

Example #1

The following example moves three shapes around the screen, randomly positioning them so that they never overlap:

// Set-up the margins to be larger than our shapes just in case

// our shape is positioned really close to the edge

screen.MarginTop = 100

screen.MarginBottom = 100

screen.MarginLeft = 100

screen.MarginRight = 100


// Define our type of circle

define type of circle MainShapeType

       radius = 50

       colour = #FF2255

       isVisible = true

end circle


define shape1 = create MainShapeType

define shape2 = create MainShapeType

define shape3 = create MainShapeType


// Now loop for 100 times, moving all of the shapes around

define counter = 0

while counter < 100


       // Move all three of our shapes around the screen

       // Notice that we pass in 100 as the minimum distance because each circle

       // has a diameter of 100

       define numberOfShapesMoved = moveShapes(100, shape1, shape2, shape3 )


       // Wait a moment, and then do it again

       wait( 1sec )

       counter += 1

end while


Produces screens similar to these:

Example #2

The following moves five shapes around the screen while keeping a fixation point constant in the centre of the screen.

Data about their placement is recorded and displayed at the end of the program to demonstrate that moving the shapes around is very uniform.

// Set-up the margins to be larger than our shapes just in case

// our shape is positioned really close to the edge

screen.MarginTop = 100

screen.MarginBottom = 100

screen.MarginLeft = 100

screen.MarginRight = 100


// Define our type of circle

define type of circle MainShapeType

       radius = 50

       colour = #FF2255

       isVisible = true

end circle


// Create our two shapes from our circle type

define fixation = create MainShapeType

fixation.X = 50%

fixation.Y = 50%

fixation.Colour = #000000


define shape1 = create MainShapeType

define shape2 = create MainShapeType

define shape3 = create MainShapeType

define shape4 = create MainShapeType

define shape5 = create MainShapeType


define left = 0;

define right = 0;

define above = 0;

define below = 0;


// Now loop for 1000 times, moving all of the shapes around

define counter = 0

define total = 10000

while counter < total


       // Move all of our shapes around except the fixation point

    moveShapes(100, shape1, shape2, shape3, shape4, shape5 )


       // Test horizontal randomness

       if( shape1.XAbsolute < fixation.XAbsolute ) then left += 1

       if( shape1.XAbsolute > fixation.XAbsolute ) then right += 1


       if( shape2.XAbsolute < fixation.XAbsolute ) then left += 1

       if( shape2.XAbsolute > fixation.XAbsolute ) then right += 1


       if( shape3.XAbsolute < fixation.XAbsolute ) then left += 1

       if( shape3.XAbsolute > fixation.XAbsolute ) then right += 1


       if( shape4.XAbsolute < fixation.XAbsolute ) then left += 1

       if( shape4.XAbsolute > fixation.XAbsolute ) then right += 1


       if( shape5.XAbsolute < fixation.XAbsolute ) then left += 1

       if( shape5.XAbsolute > fixation.XAbsolute ) then right += 1


       // Test vertical randomness

       if( shape1.YAbsolute < fixation.YAbsolute ) then above += 1

       if( shape1.YAbsolute > fixation.YAbsolute ) then below += 1


       if( shape2.YAbsolute < fixation.YAbsolute ) then above += 1

       if( shape2.YAbsolute > fixation.YAbsolute ) then below += 1


       if( shape3.YAbsolute < fixation.YAbsolute ) then above += 1

       if( shape3.YAbsolute > fixation.YAbsolute ) then below += 1


       if( shape4.YAbsolute < fixation.YAbsolute ) then above += 1

       if( shape4.YAbsolute > fixation.YAbsolute ) then below += 1


       if( shape5.YAbsolute < fixation.YAbsolute ) then above += 1

       if( shape5.YAbsolute > fixation.YAbsolute ) then below += 1


       // Wait a moment, and then do it again

       wait( 2ms )

       counter += 1

end while


print(“below: “ + below  + ” = “ + (below / (total*5) * 100) + “%” )

print(“above: “ + above  + ” = “ + (above / (total*5) * 100) + “%” )


print(“right: “ + right  + ” = “ + (right / (total*5) * 100) + “%” )

print(“left : “ + left   + ” = “ + (left  / (total*5) * 100) + “%” )