Overlays & Dialogs
Overlays and dialogs are frames that sit on top of your experiment and stay on screen while the frames and trials underneath change. A normal frame lives in the trial timeline: it appears when the trial reaches it and disappears when the trial moves on. An overlay or dialog lives outside the timeline. It is mounted for as long as its scope lasts (one trial, one task or the whole session), and events can show or hide it at any time.
Table of Contents
There are two types:
- Overlay: layered on top of the experiment. Participants keep using the experiment underneath, and only the objects on the overlay catch clicks. Use it for a timer, a score or progress display, a help button, or any element that should stay visible between trials.
- Dialog: a popup window above the experiment. By default it blocks and dims the experiment behind it until it is closed. Use it for help texts, instructions in the middle of a task, confirmations or conditional messages.
Creating overlays and dialogs needs the Overlays & Dialogs license feature, which is included from the Basic license tier. With a Free license, clicking Canvas or Page in the Overlays & Dialogs tab opens the license upgrade dialog.
Adding an Overlay or Dialog
- Open a task in the task editor.
- In the panel below the frame, click the
Overlays & Dialogstab (next toTrial Timeline). - Click
CanvasorPage.
The two buttons start with different defaults. You can change all of them afterward.
| Added with | Type | Initial state | Other defaults | Default name |
|---|---|---|---|---|
Canvas | Overlay | Shown | Match task display sizing, Transparent (see-through) fill | Overlay_1, Overlay_2, and so on |
Page | Dialog | Hidden | Centered placement, blocks and dims the experiment behind it, can be dragged, with a close button | Dialog_1, Dialog_2, and so on |
Both start with the scope This task. The new frame is selected, and you edit it like any canvas frame or page frame: add objects from the toolbar, arrange them, and add frame events. The tab offers Canvas and Page only, so a website frame cannot be added as an overlay.
To delete an overlay or dialog, use the Delete Frame icon on its entry in the Overlays & Dialogs panel.
Opening the Settings
Select the overlay or dialog in the Overlays & Dialogs panel. The Frame Settings panel (the Page Settings panel for a page) then shows a summary bar, for example Overlay · task · match task, with a gear icon. Click it to open the settings popout. Close the popout with the ✕ in its header or by clicking outside it.
The frame settings Duration, Color and Hide Mouse are not shown for overlays and dialogs. They never advance on their own, their background color is set in the popout, and the mouse cursor is controlled by the frame underneath.
Type, Scope and Initial State
The Type group of the popout:
| Setting | Options | Notes |
|---|---|---|
Type | Overlay (layered on top), Dialog (popup window) | Can be changed at any time. The Style group changes with it. |
Scope | This trial, This task, Whole session | How long the frame stays mounted. See Scope. A Whole session overlay is listed in the Overlays & Dialogs panel of every task. |
Initial state | Shown, Hidden | Whether the frame is visible when it is mounted. Choose Hidden if an event should show it later. |
Also run trial events on it | Checkbox, off by default | Leave it off unless you need it. When it is on, the trial events of the task run on the frame underneath and on the overlay, so they can fire twice. A toggle would then switch straight back. |
Overlay Style
These settings appear when Type is Overlay (layered on top).
| Setting | Options | Notes |
|---|---|---|
Sizing | Match task display (sits on the frames), Floating (place it yourself) | Match task display renders the overlay exactly like a frame of the task, so objects on it line up with objects on the frames underneath when both frames have the same size. Floating places the overlay box yourself. |
Anchor (floating only) | Top left, Top center, Top right, Middle left, Center, Middle right, Bottom left, Bottom center, Bottom right | The corner, edge or center of the screen the box is attached to. Default Top left. |
Offset X / Y (floating only) | Two numbers, in pixels | Distance from the anchor. Default 20 and 20. |
Fill | Transparent (see-through), Solid color, Semi-transparent | The background of the overlay. Default Transparent (see-through). |
Color (solid and semi-transparent) | Color picker | The fill color. |
Opacity (semi-transparent only) | Slider from 5% to 100% | Default 50%. |
A floating canvas overlay takes its size from the frame's own Width and Height in the frame settings. A floating overlay made from a page uses a box of 500 by 350 pixels.
Overlays never block the experiment. Empty, transparent areas let clicks through to the frame underneath, and only the objects on the overlay catch them.
Dialog Style and Interaction
These settings appear when Type is Dialog (popup window).
Style
| Setting | Options | Notes |
|---|---|---|
Placement | Centered, Pinned to a spot | Centered places the dialog in the middle of the screen. |
Anchor (pinned only) | The same nine positions as for overlays | The dialog keeps a distance of 20 pixels from the chosen corner or edge. |
Size W / H (page dialogs) | Two numbers, in pixels | Default 500 and 350. Pages have no designed size, so the dialog needs one. |
Size (canvas dialogs) | Shown as "uses the frame's width & height" | The dialog uses the frame's Width and Height, scaled down with the same aspect ratio if it would not fit the window. |
Background | Color picker | The dialog background. |
Border | None, Solid | Default Solid. |
Rounded corners | Checkbox, on by default | |
Drop shadow | Checkbox, on by default | |
Title bar | Checkbox, off by default | Adds a bar across the top of the dialog. |
Title (with title bar) | Text | The text in the title bar. |
Close button | Checkbox, on by default | An ✕ the participant can click to close the dialog. It sits in the title bar, or in the top right corner of the dialog when there is no title bar. |
Interaction
| Setting | Default | Notes |
|---|---|---|
Block the experiment behind | On | Participants cannot click the experiment while the dialog is open. |
Dim the experiment behind | On | Darkens the experiment behind the dialog. |
Participant can drag it | On | Lets the participant move the dialog. |
Close when clicking outside | Off | Closes the dialog when the participant clicks next to it. |
Close on Esc key | Off | Closes the dialog when the participant presses Esc. |
Closing a dialog hides it and keeps it mounted, so its state persists for the next time it is shown.
Scope
Scope decides when an overlay or dialog is mounted and when it is removed.
| Scope | Mounted | Removed | Use for |
|---|---|---|---|
This trial | When the task starts, then mounted again fresh at the start of every trial | When the task ends | Per-trial feedback or help that should start from scratch in each trial |
This task | When the task starts | When the task ends | Timers, score or progress displays, and help that belongs to one task |
Whole session | When the first task starts | When the session ends | Elements that should stay across all tasks, such as a help or pause button |
A This trial overlay is reset at the start of each trial, so its objects and their state start over. This task and Whole session overlays keep their state across trials and tasks. Variables are shared with the rest of the experiment in every scope, so a score variable shown on an overlay keeps its value.
Overlays and dialogs always use the values of the default trial. They do not change per condition.
Events on Overlays and Dialogs
An overlay or dialog runs its own frame events, like any frame. They start each time it is shown and stop when it is hidden. Keyboard triggers on an overlay also work while the frame underneath is running.
The trial events of the task (Trial Event (on each frame)) do not run on overlays and are not listed in their event panel, unless Also run trial events on it is checked.
Showing and Hiding with Control Frame
Use the Control Frame action to show, hide or toggle an overlay or dialog. You find it in the add action menu under Control Actions.
- Open the event editor on a frame in your trial timeline, or on the overlay itself.
- Add an event with any trigger.
- Add the action
Control Frame. - In
Frame:, choose the overlay or dialog. The list shows the overlays and dialogs of all tasks plus those withWhole sessionscope. - In
Command:, chooseShow,HideorToggle.
If no overlay or dialog exists yet, the action shows a hint to add one in the Overlays & Dialogs tab. An action that targets a This task or This trial overlay of another task has no effect, because that overlay is only mounted while its own task runs. Two Toggle commands within a quarter of a second count as one, so a trigger that fires twice does not open and immediately close the dialog.
Example: show a hidden help dialog when a button is clicked
Trigger:
Mouse→Set Target: your help button →Click
Action:Control Frame→Frame:your help dialog →Command:Show
Example: close the dialog from a button inside it
On the dialog frame:
Trigger:Mouse→Set Target: its Continue button →Click
Action:Control Frame→Frame:the same dialog →Command:Hide
Common Use Cases
Timer across trials: Add a Canvas overlay with the scope This task, set Sizing to Floating (place it yourself) and Anchor to Top right, and place a Timer Object on it. Start the timer with an On Frame Start event on the overlay. It keeps running across frame and trial jumps until the task ends.
Score or progress display: Add a Canvas overlay with Match task display and a Variable object (toolbar group Text & Code) that shows your score variable. Variables are shared, so the display updates whenever an event on the frames underneath changes the score.
Help dialog: Add a Page dialog, hidden by default, with your instructions, and a help button on a This task overlay or on the frames themselves. A Control Frame action with the command Show opens the dialog, and the participant closes it with the close button.
Pause message across tasks: Add a Page dialog with the scope Whole session and Initial state set to Hidden. Show it with Control Frame at the end of a task, and hide it with a Continue button inside the dialog. For a regular break between blocks, a normal page frame in the trial timeline is often simpler.
Further Reading
Trial Timeline
How frames are added and ordered within a trial, and how frame settings work.
Event System
Triggers and actions, including the Control Frame action that shows and hides overlays and dialogs.
Working with Variables
Variables are shared between overlays and the frames underneath, which is how a score or a state travels between them.