TaskObject

* Update on Jul 7, 2020

MGL now supports the z-order property, so you can change the order of graphic objects afterward in the timing script.

An object with a zero z-order (default value) is shown in the back and the one with a higher z-order is presented in front of the others that have lower z-order numbers. If the z-order of two objects are the same, the one created earlier is drawn on top of the other.

The z-order of TaskObjects and graphic adapters can be changed as below.

TaskObject(3).Zorder = 1;  % Change the z-order of TaskObject#3
TaskObject.Zorder(3) = 1;  % The same as above line

box = BoxGraphic(null_);
box.Zorder = 1;            % All graphic adapters have the Zorder property now.
box.Zorder(2) = 1;         % In case there are multiple objects in one adapter.

---

* Original post

TaskObjects can be created from either a conditions file or a userloop function. (See this for all available types of TaskObjects.)

For visual objects (movie, image, circle, square, gen), the order of the objects being created is important, because an object created earlier appears above the ones created later. For example, the "fix" object (TaskObject#1) is created first in the conditions file below and therefore is shown above the image A, when TaskObject#1 and TaskObject#2 are presented together.

Condition	Frequency	Block	Timing File	TaskObject#1	TaskObject#2
1		1		1 3	dms		fix(0,0)	pic(A,0,0)

In case of using the userloop function, the specifications of TaskObjects should be returned as a cell array of character vectors and the order of the specifications in the cell array determines the TaskObject numbers. (For the option of using structs instead of strings, see the "task\userloop\1 dms with userloop" example.)

function [C,timingfile,userdefined_trialholder] = dms_userloop(MLConfig,TrialRecord)
...
C = { 'fix(0,0)', 'pic(A,0,0)' };  % fix is TaskObject#1 and pic, TaskObject#2.
...
end

With the userloop function, TaskObject numbers can be dynamically assigned by returning the strings in different orders.

function [C,timingfile,userdefined_trialholder] = dms_userloop(MLConfig,TrialRecord)
...
switch cond
    case 1, C = { 'fix(0,0)', 'pic(A,0,0)' };  % fix appears above pic
    case 2, C = { 'pic(A,0,0)', 'fix(0,0)' };  % pic appears above fix
end
...
end

This trick doesn't work, when the userloop returns objects that are already created.

function [C,timingfile,userdefined_trialholder] = dms_userloop(MLConfig,TrialRecord)
...
% In the code below, TaskObjects are created and stored in a persistent variable so that they
% may not be recreated every trial. It shortens the stimulus preparation time during ITI.
persistent TaskObject
if isempty(TaskObject)
    TaskObject = mltaskobject({ 'pic(A,0,0)', 'fix(0,0)' }, MLConfig, TrialRecord);
end

% By reversing the order of 'pic' and 'fix' as below, you can make 'fix' to be TaskObject#1
% in the timing file, but the z-orders of the stimuli are already determined when they are
% created so it doesn't make 'fix' appear above 'pic'.
C = TaskObject([2 1]);
...
end