class Overlay extends Object
Provides an always-on-top image surface, which is click-through by default.
This class is exported by the KS module.
Surface := Overlay(X, Y , Width, Height)
Screen-facing geometry uses the platform's native coordinate space. The platform selects the backing-pixel canvas size.
Overlay supports the Image drawing primitives: Clear, DrawLine, DrawRect, FillRect, DrawRoundRect, FillRoundRect, DrawEllipse, FillEllipse, DrawText, MeasureText and DrawImage.
BeginDraw() and EndDraw() batch ordinary draw operations. Redraw(Callback [, X, Y, W, H]) creates a target-sized frame off-screen, invokes Callback to draw it and commits it atomically.
Update(Source [, X, Y, W, H])Atomically replaces the displayed content with an Image or compatible source, optionally changing the geometry in the same operation. Omit the geometry to just swap the image in place.
Surface.OnEvent(EventName, Callback , AddRemove := 1)
Registers a mouse-event callback, in the style of Gui.OnEvent. EventName is one of Click (left button), DoubleClick, ContextMenu (right button) or MouseMove. The callback receives (Surface, X, Y) with coordinates local to the overlay, in the same units the drawing methods use, so drawn content can be hit-tested without conversion. AddRemove 1 calls the function after previously registered functions, -1 before them, and 0 unregisters it.
The overlay must not be click-through to receive mouse input: set ClickThrough := false, or the events never fire and input passes through to the windows beneath. Events also require a backing with a client-side window (Hwnd is non-zero); a compositor-drawn surface cannot receive input. Registered handlers keep the script running; Destroy removes them all.
Show([X, Y, W, H])Shows the surface, optionally changing its geometry.
Move([X, Y, W, H])Moves or resizes the surface.
Hide()Hides the surface.
Destroy()Destroys the native surface.
| Property | Description |
|---|---|
X, Y | Get or set the native screen position. |
W, H | Get or set the display rectangle without discarding the canvas. |
Opacity | Gets or sets surface opacity. |
ClickThrough | Gets or sets whether pointer input passes through the surface. |
Visible | Read-only visibility state. |
Hwnd | The native surface handle or identifier. |
Highlight and, on Linux and macOS, ToolTip use the same overlay facility.
Some compositor-drawn Wayland backings remain click-through even when ClickThrough is false.
#Import "Ks" { Overlay }
Surface := Overlay(100, 100, 300, 120)
Surface.FillRoundRect(0, 0, 300, 120, 12, "0xC0202040")
Surface.DrawText("Working…", 24, 36, "White", "s18 bold", "Sans")
Surface.Show()
; An interactive overlay: receive clicks instead of passing them through.
Surface.ClickThrough := false
Surface.OnEvent("Click", (Ov, X, Y) => ToolTip("Clicked at " X "," Y))