HoshinoKoji/psychojs
1
0
Fork 0
mirror of https://github.com/psychopy/psychojs.git synced 2025-05-10 18:50:54 +00:00
Code Actions Packages Releases Activity
d23f2c90ba
psychojs/docs/core_PsychoJS.js.html

849 lines
24 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Source: core/PsychoJS.js</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Source: core/PsychoJS.js</h1>
<section>
<article>
<pre class="prettyprint source linenums"><code>/** @module core */
/**
* Main component of the PsychoJS library.
*
* @author Alain Pitiot
* @version 2021.2.0
* @copyright (c) 2017-2020 Ilixa Ltd. (http://ilixa.com) (c) 2020-2021 Open Science Tools Ltd. (https://opensciencetools.org)
* @license Distributed under the terms of the MIT License
*/
import log4javascript from 'log4javascript';
import {Scheduler} from '../util/Scheduler';
import {ServerManager} from './ServerManager';
import {ExperimentHandler} from '../data/ExperimentHandler';
import {EventManager} from './EventManager';
import {Window} from './Window';
import {GUI} from './GUI';
import {MonotonicClock} from '../util/Clock';
import {Logger} from './Logger';
import * as util from '../util/Util';
// import {Shelf} from "../data/Shelf";
/**
* &lt;p>PsychoJS manages the lifecycle of an experiment. It initialises the PsychoJS library and its various components (e.g. the {@link ServerManager}, the {@link EventManager}), and is used by the experiment to schedule the various tasks.&lt;/p>
*
* @class
* @param {Object} options
* @param {boolean} [options.debug= true] whether or not to log debug information in the browser console
* @param {boolean} [options.collectIP= false] whether or not to collect the IP information of the participant
*/
export class PsychoJS
{
/**
* Properties
*/
get status()
{
return this._status;
}
set status(status)
{
this._status = status;
}
get config()
{
return this._config;
}
get window()
{
return this._window;
}
get serverManager()
{
return this._serverManager;
}
get experiment()
{
return this._experiment;
}
get scheduler()
{
return this._scheduler;
}
get monotonicClock()
{
return this._monotonicClock;
}
get logger()
{
return this._logger.consoleLogger;
}
get experimentLogger()
{
return this._logger;
}
get eventManager()
{
return this._eventManager;
}
get gui()
{
return this._gui;
}
get IP()
{
return this._IP;
}
// this._serverMsg is a bi-directional message board for communications with the pavlovia.org server:
get serverMsg()
{
return this._serverMsg;
}
get browser()
{
return this._browser;
}
// get shelf()
// {
// return this._shelf;
// }
/**
* @constructor
* @public
*/
constructor({
debug = true,
collectIP = false,
hosts = [],
topLevelStatus = true
} = {})
{
// logging:
this._logger = new Logger(this, (debug) ? log4javascript.Level.DEBUG : log4javascript.Level.INFO);
this._captureErrors();
// detect the browser:
this._browser = util.detectBrowser();
this.logger.info('[PsychoJS] Detected browser:', this._browser);
// core clock:
this._monotonicClock = new MonotonicClock();
// managers:
this._eventManager = new EventManager(this);
this._serverManager = new ServerManager({
psychoJS: this
});
// to be loading `configURL` files in `_configure` calls from
const hostsEvidently = new Set([...hosts, 'https://pavlovia.org/run/', 'https://run.pavlovia.org/']);
this._hosts = Array.from(hostsEvidently);
// GUI:
this._gui = new GUI(this);
// IP:
this._collectIP = collectIP;
// main scheduler:
this._scheduler = new Scheduler(this);
// Window:
this._window = undefined;
// // Shelf:
// this._shelf = new Shelf(this);
// redirection URLs:
this._cancellationUrl = undefined;
this._completionUrl = undefined;
// status:
this._status = PsychoJS.Status.NOT_CONFIGURED;
// make the PsychoJS.Status accessible from the top level of the generated experiment script
// in order to accommodate PsychoPy's Code Components
if (topLevelStatus)
{
this._makeStatusTopLevel();
}
this.logger.info('[PsychoJS] Initialised.');
this.logger.info('[PsychoJS] @version 2021.2.0');
// Hide #root::after
jQuery('#root').addClass('is-ready');
}
/**
* Get the experiment's environment.
*
* @returns {ExperimentHandler.Environment | undefined} the environment of the experiment, or undefined
*/
getEnvironment()
{
if (typeof this._config === 'undefined')
{
return undefined;
}
return this._config.environment;
}
/**
* Open a PsychoJS Window.
*
* &lt;p>This opens a PIXI canvas.&lt;/p>
* &lt;p>Note: we can only open one window.&lt;/p>
*
* @param {Object} options
* @param {string} [options.name] the name of the window
* @param {boolean} [options.fullscr] whether or not to go fullscreen
* @param {Color} [options.color] the background color of the window
* @param {string} [options.units] the units of the window
* @param {boolean} [options.autoLog] whether or not to log
* @param {boolean} [options.waitBlanking] whether or not to wait for all rendering operations to be done
* before flipping
* @throws {Object.&lt;string, *>} exception if a window has already been opened
*
* @public
*/
openWindow({
name,
fullscr,
color,
units,
waitBlanking,
autoLog
} = {})
{
this.logger.info('[PsychoJS] Open Window.');
if (typeof this._window !== 'undefined')
{
throw {
origin: 'PsychoJS.openWindow',
context: 'when opening a Window',
error: 'A Window has already been opened.'
};
}
this._window = new Window({
psychoJS: this,
name,
fullscr,
color,
units,
waitBlanking,
autoLog
});
}
/**
* Set the completion and cancellation URL to which the participant will be redirect at the end of the experiment.
*
* @param {string} completionUrl - the completion URL
* @param {string} cancellationUrl - the cancellation URL
*/
setRedirectUrls(completionUrl, cancellationUrl)
{
this._completionUrl = completionUrl;
this._cancellationUrl = cancellationUrl;
}
/**
* Schedule a task.
*
* @param task - the task to be scheduled
* @param args - arguments for that task
* @public
*/
schedule(task, args)
{
this.logger.debug('schedule task: ', task.toString().substring(0, 50), '...');
this._scheduler.add(task, args);
}
/**
* @callback PsychoJS.condition
* @return {boolean} true if the thenScheduler is to be run, false if the elseScheduler is to be run
*/
/**
* Schedule a series of task based on a condition.
*
* @param {PsychoJS.condition} condition
* @param {Scheduler} thenScheduler scheduler to run if the condition is true
* @param {Scheduler} elseScheduler scheduler to run if the condition is false
* @public
*/
scheduleCondition(condition, thenScheduler, elseScheduler)
{
this.logger.debug('schedule condition: ', condition.toString().substring(0, 50), '...');
this._scheduler.addConditional(condition, thenScheduler, elseScheduler);
}
/**
* Start the experiment.
*
* &lt;p>The resources are specified in the following fashion:
* &lt;ul>
* &lt;li>For an experiment running locally: the root directory for the specified resources is that of index.html
* unless they are prepended with a protocol, such as http:// or https://.&lt;/li>
* &lt;li>For an experiment running on the server: if no resources are specified, all files in the resources directory
* of the experiment are downloaded, otherwise we only download the specified resources. All resources are assumed
* local to index.html unless they are prepended with a protocol.&lt;/li>
* &lt;li>If resources is null: we do not download any resources.&lt;/li>
* &lt;/ul>
* &lt;/p>
*
* @param {Object} options
* @param {string} [options.configURL=config.json] - the URL of the configuration file
* @param {string} [options.expName=UNKNOWN] - the name of the experiment
* @param {Object.&lt;string, *>} [options.expInfo] - additional information about the experiment
* @param {Array.&lt;{name: string, path: string}>} [resources=[]] - the list of resources
* @async
* @public
*/
async start({configURL = 'config.json', expName = 'UNKNOWN', expInfo = {}, resources = []} = {})
{
this.logger.debug();
const response = {origin: 'PsychoJS.start', context: 'when starting the experiment'};
try
{
// configure the experiment:
await this._configure(configURL, expName);
// get the participant IP:
if (this._collectIP)
{
this._getParticipantIPInfo();
}
else
{
this._IP = {
IP: 'X',
hostname: 'X',
city: 'X',
region: 'X',
country: 'X',
location: 'X'
};
}
// setup the experiment handler:
this._experiment = new ExperimentHandler({
psychoJS: this,
extraInfo: expInfo
});
// setup the logger:
//my.logger.console.setLevel(psychoJS.logging.WARNING);
//my.logger.server.set({'level':psychoJS.logging.WARNING, 'experimentInfo': my.expInfo});
// if the experiment is running on the server:
if (this.getEnvironment() === ExperimentHandler.Environment.SERVER)
{
// open a session:
await this._serverManager.openSession();
// warn the user when they attempt to close the tab or browser:
this.beforeunloadCallback = (event) =>
{
// preventDefault should ensure that the user gets prompted:
event.preventDefault();
// Chrome requires returnValue to be set:
event.returnValue = '';
};
window.addEventListener('beforeunload', this.beforeunloadCallback);
// when the user closes the tab or browser, we attempt to close the session,
// optionally save the results, and release the WebGL context
// note: we communicate with the server using the Beacon API
const self = this;
window.addEventListener('unload', (event) =>
{
if (self._config.session.status === 'OPEN')
{
// save the incomplete results if need be:
if (self._config.experiment.saveIncompleteResults)
{
self._experiment.save({sync: true});
}
// close the session:
self._serverManager.closeSession(false, true);
}
if (typeof self._window !== 'undefined')
{
self._window.close();
}
});
}
// start the asynchronous download of resources:
await this._serverManager.prepareResources(resources);
// start the experiment:
this.logger.info('[PsychoJS] Start Experiment.');
await this._scheduler.start();
}
catch (error)
{
// this._gui.dialog({ error: { ...response, error } });
this._gui.dialog({error: Object.assign(response, {error})});
}
}
/**
* Block the experiment until the specified resources have been downloaded.
*
* &lt;p>Note: only those resources that have not already been downloaded at that point are
* considered.&lt;/p>
*
* &lt;ul>
* &lt;li>For an experiment running locally: the root directory for the specified resources is that of index.html
* unless they are prepended with a protocol, such as http:// or https://.&lt;/li>
* &lt;li>For an experiment running on the server: if no resources are specified, all files in the resources directory
* of the experiment are downloaded, otherwise we only download the specified resources. All resources are assumed
* local to index.html unless they are prepended with a protocol.&lt;/li>
*
* @param {Array.&lt;{name: string, path: string}>} [resources=[]] - the list of resources
* @public
*/
waitForResources(resources = [])
{
const response = {
origin: 'PsychoJS.waitForResources',
context: 'while waiting for resources to be downloaded'
};
try
{
return this.serverManager.waitForResources(resources);
}
catch (error)
{
// this._gui.dialog({ error: { ...response, error } });
this._gui.dialog({error: Object.assign(response, {error})});
}
}
/**
* Make the attributes of the given object those of PsychoJS and those of
* the top level variable (e.g. window) as well.
*
* @param {Object.&lt;string, *>} obj the object whose attributes we will mirror
* @public
*/
importAttributes(obj)
{
this.logger.debug('import attributes from: ', util.toString(obj));
if (typeof obj === 'undefined')
{
return;
}
for (const attribute in obj)
{
// this[attribute] = obj[attribute];
window[attribute] = obj[attribute];
}
}
/**
* Close everything and exit nicely at the end of the experiment,
* potentially redirecting to one of the URLs previously specified by setRedirectUrls.
*
* &lt;p>Note: if the resource manager is busy, we inform the participant
* that he or she needs to wait for a bit.&lt;/p>
*
* @param {Object} options
* @param {string} [options.message] - optional message to be displayed in a dialog box before quitting
* @param {boolean} [options.isCompleted = false] - whether or not the participant has completed the experiment
* @async
* @public
*/
async quit({message, isCompleted = false} = {})
{
this.logger.info('[PsychoJS] Quit.');
this._experiment.experimentEnded = true;
this._status = PsychoJS.Status.FINISHED;
try
{
// stop the main scheduler:
this._scheduler.stop();
// remove the beforeunload listener:
if (this.getEnvironment() === ExperimentHandler.Environment.SERVER)
{
window.removeEventListener('beforeunload', this.beforeunloadCallback);
}
// save the results and the logs of the experiment:
this.gui.dialog({
warning: 'Closing the session. Please wait a few moments.',
showOK: false
});
if (isCompleted || this._config.experiment.saveIncompleteResults)
{
if (!this._serverMsg.has('__noOutput'))
{
await this._experiment.save();
await this._logger.flush();
}
}
// close the session:
if (this.getEnvironment() === ExperimentHandler.Environment.SERVER)
{
await this._serverManager.closeSession(isCompleted);
}
// thank participant for waiting and either quit or redirect:
let text = 'Thank you for your patience.&lt;br/>&lt;br/>';
text += (typeof message !== 'undefined') ? message : 'Goodbye!';
const self = this;
this._gui.dialog({
message: text,
onOK: () =>
{
// close the window:
self._window.close();
// remove everything from the browser window:
while (document.body.hasChildNodes())
{
document.body.removeChild(document.body.lastChild);
}
// return from fullscreen if we were there:
this._window.closeFullScreen();
// redirect if redirection URLs have been provided:
if (isCompleted &amp;&amp; typeof self._completionUrl !== 'undefined')
{
window.location = self._completionUrl;
}
else if (!isCompleted &amp;&amp; typeof self._cancellationUrl !== 'undefined')
{
window.location = self._cancellationUrl;
}
}
});
}
catch (error)
{
console.error(error);
this._gui.dialog({error});
}
}
/**
* Configure PsychoJS for the running experiment.
*
* @async
* @protected
* @param {string} configURL - the URL of the configuration file
* @param {string} name - the name of the experiment
*/
async _configure(configURL, name)
{
const response = {
origin: 'PsychoJS.configure',
context: 'when configuring PsychoJS for the experiment'
};
try
{
this.status = PsychoJS.Status.CONFIGURING;
// if the experiment is running from the pavlovia.org server, we read the configuration file:
const experimentUrl = window.location.href;
// go through each url in allow list
const isHost = this._hosts.some(url => experimentUrl.indexOf(url) === 0);
if (isHost)
{
const serverResponse = await this._serverManager.getConfiguration(configURL);
this._config = serverResponse.config;
// legacy experiments had a psychoJsManager block instead of a pavlovia block,
// and the URL pointed to https://pavlovia.org/server
if ('psychoJsManager' in this._config)
{
delete this._config.psychoJsManager;
this._config.pavlovia = {
URL: 'https://pavlovia.org'
};
}
// tests for the presence of essential blocks in the configuration:
if (!('experiment' in this._config))
{
throw 'missing experiment block in configuration';
}
if (!('name' in this._config.experiment))
{
throw 'missing name in experiment block in configuration';
}
if (!('fullpath' in this._config.experiment))
{
throw 'missing fullpath in experiment block in configuration';
}
if (!('pavlovia' in this._config))
{
throw 'missing pavlovia block in configuration';
}
if (!('URL' in this._config.pavlovia))
{
throw 'missing URL in pavlovia block in configuration';
}
if (!('gitlab' in this._config))
{
throw 'missing gitlab block in configuration';
}
if (!('projectId' in this._config.gitlab))
{
throw 'missing projectId in gitlab block in configuration';
}
this._config.environment = ExperimentHandler.Environment.SERVER;
}
else
// otherwise we create an ad-hoc configuration:
{
this._config = {
environment: ExperimentHandler.Environment.LOCAL,
experiment: {
name,
saveFormat: ExperimentHandler.SaveFormat.CSV,
saveIncompleteResults: true,
keys: []
}
};
}
// get the server parameters (those starting with a double underscore):
this._serverMsg = new Map();
util.getUrlParameters().forEach((value, key) =>
{
if (key.indexOf('__') === 0)
{
this._serverMsg.set(key, value);
}
});
this.status = PsychoJS.Status.CONFIGURED;
this.logger.debug('configuration:', util.toString(this._config));
}
catch (error)
{
// throw { ...response, error };
throw Object.assign(response, {error});
}
}
/**
* Get the IP information of the participant, asynchronously.
*
* &lt;p>Note: we use [http://www.geoplugin.net/json.gp]{@link http://www.geoplugin.net/json.gp}.&lt;/p>
* @protected
*/
async _getParticipantIPInfo()
{
const response = {
origin: 'PsychoJS._getParticipantIPInfo',
context: 'when getting the IP information of the participant'
};
this.logger.debug('getting the IP information of the participant');
this._IP = {};
try
{
const geoResponse = await jQuery.get('http://www.geoplugin.net/json.gp');
const geoData = JSON.parse(geoResponse);
this._IP = {
IP: geoData.geoplugin_request,
country: geoData.geoplugin_countryName,
latitude: geoData.geoplugin_latitude,
longitude: geoData.geoplugin_longitude
};
this.logger.debug('IP information of the participant: ' + util.toString(this._IP));
}
catch (error)
{
// throw { ...response, error };
throw Object.assign(response, {error});
}
}
/**
* Capture all errors and display them in a pop-up error box.
*
* @protected
*/
_captureErrors()
{
this.logger.debug('capturing all errors and showing them in a pop up window');
const self = this;
window.onerror = function (message, source, lineno, colno, error)
{
console.error(error);
document.body.setAttribute('data-error', JSON.stringify({
message: message,
source: source,
lineno: lineno,
colno: colno,
error: error
}));
self._gui.dialog({"error": error});
return true;
};
window.onunhandledrejection = function (error)
{
console.error(error?.reason);
if (error?.reason?.stack === undefined) {
// No stack? Error thrown by PsychoJS; stringify whole error
document.body.setAttribute('data-error', JSON.stringify(error?.reason));
} else {
// Yes stack? Error thrown by JS; stringify stack
document.body.setAttribute('data-error', JSON.stringify(error?.reason?.stack));
}
self._gui.dialog({error: error?.reason});
return true;
};
}
/**
* Make the various Status top level, in order to accommodate PsychoPy's Code Components.
* @private
*/
_makeStatusTopLevel()
{
for (const status in PsychoJS.Status)
{
window[status] = PsychoJS.Status[status];
}
}
}
/**
* PsychoJS status.
*
* @enum {Symbol}
* @readonly
* @public
*
* @note PsychoPy is currently moving away from STOPPED and replacing STOPPED by FINISHED.
* For backward compatibility reasons, we are keeping
* STOPPED in PsychoJS, but the Symbol is the same as that of FINISHED.
*/
PsychoJS.Status = {
NOT_CONFIGURED: Symbol.for('NOT_CONFIGURED'),
CONFIGURING: Symbol.for('CONFIGURING'),
CONFIGURED: Symbol.for('CONFIGURED'),
NOT_STARTED: Symbol.for('NOT_STARTED'),
STARTED: Symbol.for('STARTED'),
PAUSED: Symbol.for('PAUSED'),
FINISHED: Symbol.for('FINISHED'),
STOPPED: Symbol.for('FINISHED'), //Symbol.for('STOPPED')
ERROR: Symbol.for('ERROR')
};
</code></pre>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Modules</h3><ul><li><a href="module-core.html">core</a></li><li><a href="module-data.html">data</a></li><li><a href="module-sound.html">sound</a></li><li><a href="module-util.html">util</a></li><li><a href="module-visual.html">visual</a></li></ul><h3>Classes</h3><ul><li><a href="module-core.BuilderKeyResponse.html">BuilderKeyResponse</a></li><li><a href="module-core.EventManager.html">EventManager</a></li><li><a href="module-core.GUI.html">GUI</a></li><li><a href="module-core.Keyboard.html">Keyboard</a></li><li><a href="module-core.KeyPress.html">KeyPress</a></li><li><a href="module-core.Logger.html">Logger</a></li><li><a href="module-core.MinimalStim.html">MinimalStim</a></li><li><a href="module-core.Mouse.html">Mouse</a></li><li><a href="module-core.PsychoJS.html">PsychoJS</a></li><li><a href="module-core.ServerManager.html">ServerManager</a></li><li><a href="module-core.Window.html">Window</a></li><li><a href="module-data.ExperimentHandler.html">ExperimentHandler</a></li><li><a href="module-data.TrialHandler.html">TrialHandler</a></li><li><a href="module-sound.AudioClip.html">AudioClip</a></li><li><a href="module-sound.AudioClipPlayer.html">AudioClipPlayer</a></li><li><a href="module-sound.Microphone.html">Microphone</a></li><li><a href="module-sound.Sound.html">Sound</a></li><li><a href="module-sound.TonePlayer.html">TonePlayer</a></li><li><a href="module-sound.TrackPlayer.html">TrackPlayer</a></li><li><a href="module-util.Clock.html">Clock</a></li><li><a href="module-util.Color.html">Color</a></li><li><a href="module-util.CountdownTimer.html">CountdownTimer</a></li><li><a href="module-util.EventEmitter.html">EventEmitter</a></li><li><a href="module-util.MixinBuilder.html">MixinBuilder</a></li><li><a href="module-util.MonotonicClock.html">MonotonicClock</a></li><li><a href="module-util.PsychObject.html">PsychObject</a></li><li><a href="module-util.Scheduler.html">Scheduler</a></li><li><a href="module-visual.ButtonStim.html">ButtonStim</a></li><li><a href="module-visual.Form.html">Form</a></li><li><a href="module-visual.ImageStim.html">ImageStim</a></li><li><a href="module-visual.MovieStim.html">MovieStim</a></li><li><a href="module-visual.Polygon.html">Polygon</a></li><li><a href="module-visual.Rect.html">Rect</a></li><li><a href="module-visual.ShapeStim.html">ShapeStim</a></li><li><a href="module-visual.Slider.html">Slider</a></li><li><a href="module-visual.TextBox.html">TextBox</a></li><li><a href="module-visual.TextStim.html">TextStim</a></li><li><a href="module-visual.VisualStim.html">VisualStim</a></li></ul><h3>Interfaces</h3><ul><li><a href="module-sound.SoundPlayer.html">SoundPlayer</a></li></ul><h3>Mixins</h3><ul><li><a href="module-core.WindowMixin.html">WindowMixin</a></li><li><a href="module-util.ColorMixin.html">ColorMixin</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.7</a> on Mon Jun 21 2021 07:34:20 GMT+0200 (Central European Summer Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>
View Git Blame Copy Permalink