This appendix gives the specifications of the parameters that are used in an RFV input file. To declare a parameter, the parameter name needs to be input, followed by an opening bracket. Then the required arguments must be included, followed by any optional arguments that are being used. The declaration is completed by a closing bracket. The arguments of a parameter may be labels, filenames, keywords, integers, or other parameters. Some parameters may require no arguments.
The specifications indicate which parameters a given parameter may be declared inside; that is, each parameter may be included as an argument of only a limited group of other parameters. When a parameter is declared, the required arguments listed must appear within the brackets of that parameter in the order listed. Optional arguments may then follow the required arguments, although these can be in any order. Optional arguments can only be specified once for each parameter (unless it is indicated otherwise).
Two of the parameters do not appear as arguments to other parameters. The input file requires the DEFAULTS parameter to be completely defined first, followed by multiple (at least one) instances of the COMPONENT parameter.
| Parameter Name: | BACKGROUND |
| Declared Inside: | BLOCK, FEEDBACK, BUTTON |
| Required Arguments: | Three Integers |
| Optional Arguments: | None |
| Description: | This parameter specifies the background colour to be assigned to either the RFV window (when declared inside BLOCK or FEEDBACK) or a BUTTON. The three arguments it takes are integers in the range 0 to 255 inclusive. These integers represent the red, green and blue (RGB) contributions to the colour. The RGB model is the standard one used by most computer graphics programs. This parameter will override any default background colour setting. |
| Parameter Name: | BLOCK |
| Declared Inside: | COMPONENT |
| Required Arguments: | None |
| Optional Arguments: | DISPLAY, BACKGROUND, TIME_LIMIT, Multiple FEEDBACKs |
| Description: | A block is used to define the elements that appear in the RFV window at a given time. Each block determines the layout of its elements with the DISPLAY parameter, and can also specify a TIME_LIMIT on the display duration of the block. FEEDBACK based on the participant's response can be specified, as can the BACKGROUND colour of the block, overriding the default setting. |
| Parameter Name: | BUTTON |
| Declared Inside: | DISPLAY, ROW, COLUMN |
| Required Arguments: | One Label |
| Optional Arguments: | FONT, FOREGROUND, BACKGROUND |
| Description: | This parameter defines a button with the specified label. The size of the button will depend on the font being used, with the width being adjusted to accommodate the label. If a least one button is declared within a block, then only a mouse click on a button will end that block. If no buttons are declared within a block, then a mouse click anywhere in the RFV window will end that block. Buttons can also be used in conjunction with the FEEDBACK parameter to provide feedback to participants based on the button that was selected in a block. |
| Parameter Name: | BUTTON_BACKGROUND |
| Declared Inside: | DEFAULTS |
| Required Arguments: | Three Integers |
| Optional Arguments: | None |
| Description: | This parameter specifies the default button background colour. If not explicitly set, this colour will be light gray. See BACKGROUND for details about the arguments. |
| Parameter Name: | BUTTON_FONT |
| Declared Inside: | DEFAULTS |
| Required Arguments: | One Label, One Keyword, One Integer |
| Optional Arguments: | None |
| Description: | This parameter specifies the default button font. If not explicitly set, a default system font will be used. See FONT for details about the arguments. |
| Parameter Name: | BUTTON_FOREGROUND |
| Declared Inside: | DEFAULTS |
| Required Arguments: | Three Integers |
| Optional Arguments: | None |
| Description: | This parameter specifies the default button foreground colour. If not explicitly set, this colour will be black. See FOREGROUND for details about the arguments. |
| Parameter Name: | COLUMN |
| Declared Inside: | ROW |
| Required Arguments: | None |
| Optional Arguments: | TEXT_LINE, IMAGE, BUTTON1, STIMULUS1, ROW, V_SPACE, RESPONSE_TIME2 1 Cannot be used within a FEEDBACK block 2 Can only be used within a FEEDBACK block |
| Description: | This parameter is used to vertically layout the elements of a region of the RFV window. It can contain visual elements, empty spaces and other regions in the form of ROWs. |
| Parameter Name: | COMPONENT |
| Declared Inside: | Input File |
| Required Arguments: | One Label, Multiple BLOCKs |
| Optional Arguments: | None |
| Description: | This parameter is used to bind together a group of blocks in a set order. The first argument is a label to identify the component, which should be unique for each component that is defined. When the RFV program is run, the components can then be arranged in any order. This parameter can only be used in the input file after the DEFAULTS parameter. Each component must contain at least one BLOCK. |
| Parameter Name: | DEFAULTS |
| Declared Inside: | Input File |
| Required Arguments: | FRAME_SIZE, FOCUS_WINDOW, MOTION_BLUR_SPEED |
| Optional Arguments: | TEXT_FONT, TEXT_FOREGROUND, BUTTON_FONT, BUTTON_FOREGROUND, BUTTON_BACKGROUND, DISPLAY_BACKGROUND |
| Description: | This parameter must be the first one to appear in the input file. It is used to specify the default settings for various attributes of the RFV's visual elements. It also contains the parameter which specifies the dimensions of the RFV window. If the optional parameters are not set, the TEXT_FOREGROUND and BUTTON_FOREGROUND colours will be set to black, the BUTTON_BACKGROUND colour will be set to light gray, and the DISPLAY_BACKGROUND colour will be white. The TEXT_FONT and BUTTON_FONT will set to a plain Helvetica font of point size 20, or if this is not available, a default system font. |
| Parameter Name: | DISPLAY |
| Declared Inside: | BLOCK, FEEDBACK |
| Required Arguments: | None |
| Optional Arguments: | TEXT_LINE, IMAGE, BUTTON1, STIMULUS1, ROW, V_SPACE, RESPONSE_TIME2 1 Cannot be used within a FEEDBACK block 2 Can only be used within a FEEDBACK block |
| Description: | This parameter is used to vertically layout the elements of a block that are to be displayed. It defines the entire RFV window as a column, which can contain visual elements, empty spaces and other regions in the form of ROWs. Note that if declared as an argument to the BLOCK parameter, RESPONSE_TIME is not available as a visual element within the DISPLAY or any of its regions. Also, if declared as an argument to the FEEDBACK parameter, BUTTON and STIMULUS cannot be declared within the DISPLAY or any of its regions. |
| Parameter Name: | DISPLAY_BACKGROUND |
| Declared Inside: | DEFAULTS |
| Required Arguments: | Three Integers |
| Optional Arguments: | None |
| Description: | This parameter specifies the default background colour for the RFV window. If not explicitly set, this colour will be white. See BACKGROUND for details about the arguments. |
| Parameter Name: | FEEDBACK |
| Declared Inside: | BLOCK |
| Required Arguments: | One Label or One Keyword |
| Optional Arguments: | DISPLAY, BACKGROUND, TIME_LIMIT |
| Description: | This parameter is used to present different blocks of information to participants depending on their response to the block in which the parameter is defined. The first argument of this parameter is either the label of one of the buttons defined in the block, the keyword NO_BUTTONS (which can be used if no buttons were defined in the block and the participant can thus click the mouse anywhere to continue), or the keyword TIME_LIMIT_EXPIRED (which can be used any time a block uses a TIME_LIMIT). A feedback block will only be invoked if the participants response matches that of the first argument (for example, they selected the button with the corresponding label, or the time limit expired before they responded). If this happens, the feedback block acts similar to a normal block, with the following exceptions. The BUTTON and the STIMULUS parameters cannot be defined inside the DISPLAY parameter of the feedback block, and a feedback block cannot contain a FEEDBACK parameter. This is because a feedback block is meant purely as a passive block providing information to the participant, and is not meant to contain interactive elements that might themselves require feedback. |
| Parameter Name: | FOCUS_WINDOW |
| Declared Inside: | DEFAULTS, STIMULUS |
| Required Arguments: | Eight Integers |
| Optional Arguments: | FOCUS_WINDOW_OFFSETS |
| Description: | This parameter takes in the dimensions of the four regions that define the focus window. The arguments thus effectively form four pairs of integers, specifying width followed by height (in pixels). The first pair gives the dimensions for the outermost transition region. The second pair, the middle transition region and the third pair, the innermost transition region. The final pair is the dimensions of the actual focus region inside the innermost transition region. Each pair of numbers should be no larger than the previous pair, otherwise an error will be reported. When the dimensions are set, all of the regions are centred around the dot that defines the cursor location within a stimulus. |
| Parameter Name: | FOCUS_WINDOW_OFFSETS |
| Declared Inside: | FOCUS_WINDOW |
| Required Arguments: | Eight Integers |
| Optional Arguments: | None |
| Description: | This parameter allows the four regions of the focus window to be offset, so that they are not necessarily centred around the dot that defines the cursor location within a stimulus. The arguments form four pairs of integers, each consisting of a horizontal offset value followed by a vertical offset value (in pixels). These values can be positive or negative. The first pair of values applies to the outermost transition region. The second pair to the middle transition region and the third pair, the innermost transition region. The final pair is the offsets for the actual focus region inside the innermost transition region. If only one region needs to be offset, then the arguments for the other regions can be set to zero. Care needs to be taken when setting this parameter, since the RFV does no checking of the consequences of the settings provided. For most purposes however, this parameter will not need to be used. |
| Parameter Name: | FONT |
| Declared Inside: | TEXT_LINE, BUTTON, RESPONSE_TIME |
| Required Arguments: | One Label, One Keyword, One Integer |
| Optional Arguments: | None |
| Description: | This parameter specifies the font to be used for a TEXT_LINE, BUTTON or RESPONSE_TIME. The first argument is the name of the font, which can be one of Serif, SansSerif, Dialog, DialogInput, Monospaced or Symbol. Some of these fonts might not be available on certain systems. The font name is given as a label. The second argument is the style of the font. This can be either PLAIN, BOLD, ITALIC or BOLD_ITALIC. Finally, the point size of the font must be specified. Just as some fonts are not available on all systems, not all fonts are always available in every size or style. This parameter will override any default font setting. However, if the RFV cannot load the font specified, it will revert to a default font. |
| Parameter Name: | FOREGROUND |
| Declared Inside: | TEXT_LINE, BUTTON, RESPONSE_TIME |
| Required Arguments: | Three Integers |
| Optional Arguments: | None |
| Description: | This parameter specifies the foreground colour to be assigned to the text that is defined in a TEXT_LINE, BUTTON or RESPONSE_TIME declaration. The three arguments it takes are integers in the range 0 to 255 inclusive. These integers represent the red, green and blue (RGB) contributions to the colour. The RGB model is the standard one used by most computer graphics programs. This parameter will override any default foreground colour setting. |
| Parameter Name: | FRAME_SIZE |
| Declared Inside: | DEFAULTS |
| Required Arguments: | Two Integers |
| Optional Arguments: | None |
| Description: | This parameter takes in the width followed by the height (in pixels) of the window that will contain each block. It is recommended that this window be the same size as the screen resolution being used. This will enable the RFV window to fill the entire screen, leaving no background remaining to distract the participant. The frame size also needs to be large enough to accommodate all of the visual elements that are presented in each block. If the frame size is not large enough, the program will inform the user of this and terminate. |
| Parameter Name: | H_SPACE |
| Declared Inside: | ROW |
| Required Arguments: | None |
| Optional Arguments: | One Integer |
| Description: | With no arguments, this parameter is used to divide up extra horizontal space in a region of the RFV window. If this parameter appears with no arguments more than once in a region, then the extra horizontal space is divided evenly among each instance. This parameter can also be used with an integer as an argument. The integer specifies the width of a fixed horizontal space to be inserted into the region where the parameter is declared. |
| Parameter Name: | IMAGE |
| Declared Inside: | DISPLAY, ROW, COLUMN |
| Required Arguments: | One Filename |
| Optional Arguments: | None |
| Description: | This parameter allows a static image to be loaded and displayed by the RFV. The argument taken by this parameter is the filename for the image. The image filename should include the directory path if needed, and it is recommended that the full directory path be used if the image is in a different directory from where the program will be run. The image file must be in either the GIF or JPEG graphics file format (these files usually have a .gif or .jpg extension). |
| Parameter Name: | MOTION_BLUR_SPEED |
| Declared Inside: | DEFAULTS, STIMULUS |
| Required Arguments: | One Integer |
| Optional Arguments: | None |
| Description: | This parameter takes in a single value, which is the mouse speed that determines the onset of motion blur. If the user moves the mouse at greater than this speed, then the focus window will be motion blurred. If the user then slows down to below this speed, or stops moving the mouse altogether, then full focus will return. The speed is measured in pixels per second. A value of 100 is a reasonable starting point in trying to determine an appropriate setting. A very low value will see motion blur occur for even slow mouse movements, whereas a high value will allow the participant to move the mouse at a reasonable speed and still maintain full focus. |
| Parameter Name: | RESPONSE_TIME |
| Declared Inside: | DISPLAY, ROW, COLUMN |
| Required Arguments: | None |
| Optional Arguments: | FONT, FOREGROUND |
| Description: | This parameter defines a visual element that can only be used within a FEEDBACK block. It is similar to the TEXT_LINE parameter, except that it accepts no label as an argument. Instead, the text that it produces is the amount of time (in milliseconds) that the participant spent looking at the block in which the FEEDBACK parameter is defined. This is the amount of time between when the block first appears (not including loading time) and when the block disappears (due to either a mouse click or the expiration of a time limit). If, for example, this time is 1625 milliseconds, then using this parameter will be equivalent to using a TEXT_LINE parameter with the label ``1625ms''. |
| Parameter Name: | ROW |
| Declared Inside: | DISPLAY, COLUMN |
| Required Arguments: | None |
| Optional Arguments: | TEXT_LINE, IMAGE, BUTTON1, STIMULUS1, COLUMN, H_SPACE, RESPONSE_TIME2 1 Cannot be used within a FEEDBACK block 2 Can only be used within a FEEDBACK block |
| Description: | This parameter is used to horizontally layout the elements of a region of the RFV window. It can contain visual elements, empty spaces and other regions in the form of COLUMNs. |
| Parameter Name: | STIMULUS |
| Declared Inside: | DISPLAY, ROW, COLUMN |
| Required Arguments: | Five Filenames |
| Optional Arguments: | FOCUS_WINDOW |
| Description: | This parameter allows a set of stimulus images to be loaded and displayed by the RFV. The arguments taken by this parameter are the filenames for the five images needed for the stimulus. The image filenames should include the directory paths if needed, and it is recommended that the full directory path be used if the images are in a different directory from where the program will be run. The first label is the filename for the fully blurred image of the stimulus. The second is the filename for the image to be used for the outermost transition region. The third, for the middle transition region and the fourth, for the innermost transition region. The final label is the filename for the stimulus proper, that is, the stimulus in full focus. Each image therefore should be slightly less blurred than the previous one. All of the image files must be in either the GIF or JPEG graphics file format (these files usually have a .gif or .jpg extension). |
| Parameter Name: | TEXT_FONT |
| Declared Inside: | DEFAULTS |
| Required Arguments: | One Label, One Keyword, One Integer |
| Optional Arguments: | None |
| Description: | This parameter specifies the default text font. If not explicitly set, a default system font will be used. See FONT for details about the arguments. |
| Parameter Name: | TEXT_FOREGROUND |
| Declared Inside: | DEFAULTS |
| Required Arguments: | Three Integers |
| Optional Arguments: | None |
| Description: | This parameter specifies the default text foreground colour. If not explicitly set, this colour will be black. See FOREGROUND for details about the arguments. |
| Parameter Name: | TEXT_LINE |
| Declared Inside: | DISPLAY, ROW, COLUMN |
| Required Arguments: | One Label |
| Optional Arguments: | FONT, FOREGROUND |
| Description: | This parameter defines a line of text that is specified by the label. The size of the text will depend on the font being used, with the text line only taking up as much space as is needed. |
| Parameter Name: | TIME_LIMIT |
| Declared Inside: | BLOCK, FEEDBACK |
| Required Arguments: | One Integer |
| Optional Arguments: | One Keyword |
| Description: | Occasionally it may be desirable for there to be a maximum time limit that a block is present for. If this parameter is set within a block, then the RFV will only display the block for the time specified in the argument. The time specified is measured in milliseconds. This still allows the participant to respond with a mouse click, but only if the response can be made before the time limit expires. If the time limit is reached before the participant has responded, then the next block is automatically loaded. If the optional STRICT keyword is present, this will force the block to remain for the exact time limit specified by not allowing the participant to end the block early with a mouse click. |
| Parameter Name: | V_SPACE |
| Declared Inside: | DISPLAY, COLUMN |
| Required Arguments: | None |
| Optional Arguments: | One Integer |
| Description: | With no arguments, this parameter is used to divide up extra vertical space in a region of the RFV window. If this parameter appears with no arguments more than once in a region, then the extra vertical space is divided evenly among each instance. This parameter can also be used with an integer as an argument. The integer specifies the height of a fixed vertical space to be inserted into the region where the parameter is declared. |