Element: graphic_window.overlay

Type

group

Description

A list of entities to be shown as an overlay on top of other entities in a window. This overlay group is displayed after everything else has been displayed (cloth, foreground entities, grid and vane).

The overlay is not part of a window's save-under image. Consequently, changes to entities in a window overlay are displayed quickly since everything else is refreshed from the save-under. For this reason the number of entities in a window overlay should be kept to a minimum.

When a window overlay contains entities, save-under facilities must be enabled, so there is a need to set window.save_under first.

In all other respects, this group behaves like any other group identifier with the exception that it cannot be included as a window display group. When entities are moved from window display groups into an overlay and vice versa, full graphic refreshes will be performed.

Examples

A typical example for an overlay group would be to display information about entities while the mouse is being dragged across the window. The information is displayed as a glabel on the window's overlay.

epointer ~global.last = null ;# the last hit
entity glab = null ;# the current glabel
gc_display = off ;# suppress display of gc
gwin.track = {
    args w=window
    err_level = 5 ;# suppress epick message
    epointer ep=epick ;# pick an entity
    if (ep != last) { ;# test for "no change"
        if (ep == glab) return;# do not pick the label
        if (ep) ;# do we have a "hit"
        glab = glabel '^(ep)',-tf=1,-fil=yellow,
            -g=w.overlay,-h=50
        else glab = null
        last = ep
    }
}
tell pcur ;# get a point (invokes tracking)