Overlay Object

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.

Note: This class is experimental: it and its nested types may change or be removed without deprecation. See #Warn Experimental.

Surface := Overlay()
Surface := Overlay(X, Y, Width, Height)
Surface := Overlay.FromImage(Source , X, Y, Width, Height)

The empty constructor creates an unconfigured overlay for which SetImage will provide a size. The rectangle constructor requires all four arguments and positive dimensions. FromImage copies its source into a hidden overlay and uses its pixel dimensions for omitted width or height. Source can be an Image, file path or bitmap handle.

Screen-facing geometry uses the platform's native coordinate space. The platform selects the backing-pixel canvas size. Nothing is shown until Show.

Drawing

The overlay's pixels are the borrowed Image exposed by Canvas. Draw through that image, then call Present() when the frame is complete:

Surface.Canvas.Clear()
Surface.Canvas.DrawText("Working…", 24, 36, "White", "s18 bold", "Sans")
Surface.Present()

Drawing changes only the canvas. Show, SetImage, Redraw, resizing and changing Opacity publish their complete state directly.

The canvas belongs to the overlay, so it cannot be disposed, re-initialised, transformed or have all of its pixel data replaced. These operations raise an error. Canvas.Copy() returns an independent image which can be transformed freely. Redraw and a size-changing SetImage replace the canvas; re-read Canvas after either operation.

An overlay follows the same thread-ownership rule as an Image: two RealThreads drawing on one surface can hang.

Content

Present()

Publishes the current canvas without changing visibility.

SetImage(Source [, X, Y, Width, Height])

Copies an Image, file or bitmap handle into the canvas and optionally changes geometry in the same presentation. Each omitted geometry argument preserves its current setting. An automatic width or height (0) follows the corresponding source pixel dimension. Passing the overlay's own Canvas is an error; use Present to publish it.

This method does not change visibility.

Redraw(Callback [, X, Y, Width, Height])

Builds a private target-sized canvas, passes that canvas to Callback, then presents its pixels and geometry together. The callback's return value is ignored and it may draw only; changing overlay state inside it raises an error. A callback error leaves the current frame unchanged.

OnEvent

Surface.OnEvent(EventName, Callback , AddRemove := 1)

Registers a mouse-event callback in the style of Gui.OnEvent. EventName is Click, DoubleClick, ContextMenu or MouseMove. The callback receives (Surface, X, Y) in overlay-local native units. AddRemove 1 appends, -1 prepends and 0 unregisters the callback.

An event's callbacks are called in order; a callback's return value or error can prevent the remaining callbacks from being called, as described for Gui.OnEvent.

While a MouseMove event waits for its callbacks to be called, further movement does not queue more events but updates the position that event reports, so the callbacks receive the latest position.

Each registration runs on the RealThread which made it and keeps that thread running until the thread ends or Destroy is called; AddRemove 0 removes only the current thread's registration. Set ClickThrough := false to receive pointer events.

Presentation

Show([X, Y, Width, Height])

Shows the surface, optionally changing its geometry.

Move([X, Y, Width, Height])

Moves or resizes the surface.

Hide()

Hides the surface and keeps its canvas. On Windows, Linux/X11 and macOS, the runtime retains the window and Hwnd for reuse. Wayland layer-shell surfaces and compositor overlays are created again by the next Show.

Destroy()

Destroys the native surface and invalidates its canvas.

Properties

Remarks

Linux

Wayland: On GNOME and Cinnamon, an overlay whose ClickThrough is false is shown as an ordinary window; on Cinnamon, it appears in the window list.

Moving or resizing a visible layer-shell overlay preserves its canvas and scales it to the new rectangle, including across displays with different scales. Live compositor and mixed-DPI hardware verification remains outstanding.

Examples

#Import "Ks" { Overlay }

Surface := Overlay(100, 100, 300, 120)
Surface.Canvas.FillRoundRect(0, 0, 300, 120, 12, "0xC0202040")
Surface.Show()

Loop 100 {
    Surface.Canvas.Clear()
    Surface.Canvas.DrawText("Frame " A_Index, 24, 36, "White", "s18 bold", "Sans")
    Surface.Present()
    Sleep(16)
}

Surface.ClickThrough := false
Surface.OnEvent("Click", (Ov, X, Y) => ToolTip("Clicked at " X "," Y))

Related

Image, ToolTip