@jspsych/plugin-canvas-keyboard-response 1.1.2 → 2.0.0

package/dist/index.d.ts

@@ -1,116 +1,178 @@
-import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
-declare const info: {
-    readonly name: "canvas-keyboard-response";
-    readonly parameters: {
-        /** The drawing function to apply to the canvas. Should take the canvas object as argument. */
-        readonly stimulus: {
-            readonly type: ParameterType.FUNCTION;
-            readonly pretty_name: "Stimulus";
-            readonly default: any;
-        };
-        /** Array containing the key(s) the subject is allowed to press to respond to the stimulus. */
-        readonly choices: {
-            readonly type: ParameterType.KEYS;
-            readonly pretty_name: "Choices";
-            readonly default: "ALL_KEYS";
-        };
-        /** Any content here will be displayed below the stimulus. */
-        readonly prompt: {
-            readonly type: ParameterType.HTML_STRING;
-            readonly pretty_name: "Prompt";
-            readonly default: any;
-        };
-        /** How long to show the stimulus. */
-        readonly stimulus_duration: {
-            readonly type: ParameterType.INT;
-            readonly pretty_name: "Stimulus duration";
-            readonly default: any;
-        };
-        /** How long to show trial before it ends. */
-        readonly trial_duration: {
-            readonly type: ParameterType.INT;
-            readonly pretty_name: "Trial duration";
-            readonly default: any;
-        };
-        /** If true, trial will end when subject makes a response. */
-        readonly response_ends_trial: {
-            readonly type: ParameterType.BOOL;
-            readonly pretty_name: "Response ends trial";
-            readonly default: true;
-        };
-        /** Array containing the height (first value) and width (second value) of the canvas element. */
-        readonly canvas_size: {
-            readonly type: ParameterType.INT;
-            readonly array: true;
-            readonly pretty_name: "Canvas size";
-            readonly default: readonly [500, 500];
-        };
-    };
-};
-declare type Info = typeof info;
-/**
- * **canvas-keyboard-response**
- *
- * jsPsych plugin for displaying a canvas stimulus and getting a keyboard response
- *
- * @author Chris Jungerius (modified from Josh de Leeuw)
- * @see {@link https://www.jspsych.org/plugins/jspsych-canvas-keyboard-response/ canvas-keyboard-response plugin documentation on jspsych.org}
- */
-declare class CanvasKeyboardResponsePlugin implements JsPsychPlugin<Info> {
-    private jsPsych;
-    static info: {
-        readonly name: "canvas-keyboard-response";
-        readonly parameters: {
-            /** The drawing function to apply to the canvas. Should take the canvas object as argument. */
-            readonly stimulus: {
-                readonly type: ParameterType.FUNCTION;
-                readonly pretty_name: "Stimulus";
-                readonly default: any;
-            };
-            /** Array containing the key(s) the subject is allowed to press to respond to the stimulus. */
-            readonly choices: {
-                readonly type: ParameterType.KEYS;
-                readonly pretty_name: "Choices";
-                readonly default: "ALL_KEYS";
-            };
-            /** Any content here will be displayed below the stimulus. */
-            readonly prompt: {
-                readonly type: ParameterType.HTML_STRING;
-                readonly pretty_name: "Prompt";
-                readonly default: any;
-            };
-            /** How long to show the stimulus. */
-            readonly stimulus_duration: {
-                readonly type: ParameterType.INT;
-                readonly pretty_name: "Stimulus duration";
-                readonly default: any;
-            };
-            /** How long to show trial before it ends. */
-            readonly trial_duration: {
-                readonly type: ParameterType.INT;
-                readonly pretty_name: "Trial duration";
-                readonly default: any;
-            };
-            /** If true, trial will end when subject makes a response. */
-            readonly response_ends_trial: {
-                readonly type: ParameterType.BOOL;
-                readonly pretty_name: "Response ends trial";
-                readonly default: true;
-            };
-            /** Array containing the height (first value) and width (second value) of the canvas element. */
-            readonly canvas_size: {
-                readonly type: ParameterType.INT;
-                readonly array: true;
-                readonly pretty_name: "Canvas size";
-                readonly default: readonly [500, 500];
-            };
-        };
-    };
-    constructor(jsPsych: JsPsych);
-    trial(display_element: HTMLElement, trial: TrialType<Info>): void;
-    simulate(trial: TrialType<Info>, simulation_mode: any, simulation_options: any, load_callback: () => void): void;
-    private simulate_data_only;
-    private simulate_visual;
-    private create_simulation_data;
-}
-export default CanvasKeyboardResponsePlugin;
+import { JsPsychPlugin, ParameterType, JsPsych, TrialType } from 'jspsych';
+
+declare const info: {
+    readonly name: "canvas-keyboard-response";
+    readonly version: string;
+    readonly parameters: {
+        /** The function to draw on the canvas. This function automatically takes a canvas element as its only
+         * argument, e.g. `function(c) {...}` or `function drawStim(c) {...}`, where `c` refers to the canvas element.
+         * Note that the stimulus function will still generally need to set the correct context itself, using a line
+         * like `let ctx = c.getContext("2d")`.
+         */
+        readonly stimulus: {
+            readonly type: ParameterType.FUNCTION;
+            readonly default: any;
+        };
+        /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.
+         * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -
+         * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)
+         * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)
+         * for more examples. Any key presses that are not listed in the array will be ignored. The default value
+         * of `"ALL_KEYS"` means that all keys will be accepted as valid responses. Specifying `"NO_KEYS"` will mean
+         * that no responses are allowed.
+         */
+        readonly choices: {
+            readonly type: ParameterType.KEYS;
+            readonly default: "ALL_KEYS";
+        };
+        /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention
+         * is that it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).
+         */
+        readonly prompt: {
+            readonly type: ParameterType.HTML_STRING;
+            readonly default: any;
+        };
+        /** How long to display the stimulus in milliseconds. The visibility CSS property of the stimulus will be set to
+         * `hidden` after this time has elapsed. If this is null, then the stimulus will remain visible until the trial ends.
+         */
+        readonly stimulus_duration: {
+            readonly type: ParameterType.INT;
+            readonly default: any;
+        };
+        /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the
+         * participant fails to make a response before this timer is reached, the participant's response will be
+         * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the
+         * trial will wait for a response indefinitely.
+         */
+        readonly trial_duration: {
+            readonly type: ParameterType.INT;
+            readonly default: any;
+        };
+        /** If true, then the trial will end whenever the participant makes a response (assuming they make their
+         * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will
+         * continue until the value for `trial_duration` is reached. You can use this parameter to force the participant
+         * to view a stimulus for a fixed amount of time, even if they respond before the time is complete.
+         */
+        readonly response_ends_trial: {
+            readonly type: ParameterType.BOOL;
+            readonly default: true;
+        };
+        /** Array that defines the size of the canvas element in pixels. First value is height, second value is width. */
+        readonly canvas_size: {
+            readonly type: ParameterType.INT;
+            readonly array: true;
+            readonly default: readonly [500, 500];
+        };
+    };
+    readonly data: {
+        /** Indicates which key the participant pressed. */
+        readonly response: {
+            readonly type: ParameterType.STRING;
+        };
+        /** The response time in milliseconds for the participant to make a response. The time is measured from
+         * when the stimulus first appears on the screen until the participant's response.
+         */
+        readonly rt: {
+            readonly type: ParameterType.INT;
+        };
+    };
+};
+type Info = typeof info;
+/**
+ * This plugin can be used to draw a stimulus on a [HTML canvas element](https://www.w3schools.com/html/html5_canvas.asp) and
+ * record a keyboard response. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics,
+ * and for controlling the positioning of multiple graphical elements (shapes, text, images). The stimulus can be
+ * displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically
+ * if the participant has failed to respond within a fixed length of time.
+ *
+ * @author Chris Jungerius (modified from Josh de Leeuw)
+ * @see {@link https://www.jspsych.org/latest/plugins/canvas-keyboard-response/ canvas-keyboard-response plugin documentation on jspsych.org}
+ */
+declare class CanvasKeyboardResponsePlugin implements JsPsychPlugin<Info> {
+    private jsPsych;
+    static info: {
+        readonly name: "canvas-keyboard-response";
+        readonly version: string;
+        readonly parameters: {
+            /** The function to draw on the canvas. This function automatically takes a canvas element as its only
+             * argument, e.g. `function(c) {...}` or `function drawStim(c) {...}`, where `c` refers to the canvas element.
+             * Note that the stimulus function will still generally need to set the correct context itself, using a line
+             * like `let ctx = c.getContext("2d")`.
+             */
+            readonly stimulus: {
+                readonly type: ParameterType.FUNCTION;
+                readonly default: any;
+            };
+            /** This array contains the key(s) that the participant is allowed to press in order to respond to the stimulus.
+             * Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) -
+             * see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)
+             * and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/)
+             * for more examples. Any key presses that are not listed in the array will be ignored. The default value
+             * of `"ALL_KEYS"` means that all keys will be accepted as valid responses. Specifying `"NO_KEYS"` will mean
+             * that no responses are allowed.
+             */
+            readonly choices: {
+                readonly type: ParameterType.KEYS;
+                readonly default: "ALL_KEYS";
+            };
+            /** This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention
+             * is that it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press).
+             */
+            readonly prompt: {
+                readonly type: ParameterType.HTML_STRING;
+                readonly default: any;
+            };
+            /** How long to display the stimulus in milliseconds. The visibility CSS property of the stimulus will be set to
+             * `hidden` after this time has elapsed. If this is null, then the stimulus will remain visible until the trial ends.
+             */
+            readonly stimulus_duration: {
+                readonly type: ParameterType.INT;
+                readonly default: any;
+            };
+            /** How long to wait for the participant to make a response before ending the trial in milliseconds. If the
+             * participant fails to make a response before this timer is reached, the participant's response will be
+             * recorded as null for the trial and the trial will end. If the value of this parameter is null, then the
+             * trial will wait for a response indefinitely.
+             */
+            readonly trial_duration: {
+                readonly type: ParameterType.INT;
+                readonly default: any;
+            };
+            /** If true, then the trial will end whenever the participant makes a response (assuming they make their
+             * response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will
+             * continue until the value for `trial_duration` is reached. You can use this parameter to force the participant
+             * to view a stimulus for a fixed amount of time, even if they respond before the time is complete.
+             */
+            readonly response_ends_trial: {
+                readonly type: ParameterType.BOOL;
+                readonly default: true;
+            };
+            /** Array that defines the size of the canvas element in pixels. First value is height, second value is width. */
+            readonly canvas_size: {
+                readonly type: ParameterType.INT;
+                readonly array: true;
+                readonly default: readonly [500, 500];
+            };
+        };
+        readonly data: {
+            /** Indicates which key the participant pressed. */
+            readonly response: {
+                readonly type: ParameterType.STRING;
+            };
+            /** The response time in milliseconds for the participant to make a response. The time is measured from
+             * when the stimulus first appears on the screen until the participant's response.
+             */
+            readonly rt: {
+                readonly type: ParameterType.INT;
+            };
+        };
+    };
+    constructor(jsPsych: JsPsych);
+    trial(display_element: HTMLElement, trial: TrialType<Info>): void;
+    simulate(trial: TrialType<Info>, simulation_mode: any, simulation_options: any, load_callback: () => void): void;
+    private simulate_data_only;
+    private simulate_visual;
+    private create_simulation_data;
+}
+
+export { CanvasKeyboardResponsePlugin as default };