Recent Changes

This page summarizes the script-visible changes in recent Keysharp releases, so that a script written against an earlier version can be brought up to date. The release page holds the authoritative notes and the downloads for each version.

Note: Keysharp has not reached version 1.0. Behavior can change between releases, including in ways which require edits to existing scripts. Each release below lists its breaking changes first.

Documented Version

A compatibility target states which AutoHotkey language and library reference these pages describe. It does not mean that every described feature is implemented identically, or that it behaves the same on every platform. See Changes from AutoHotkey to Keysharp for the differences, Platform Support for per-platform availability, and the platform remarks on each affected reference page.

The corresponding upstream language changes are described in Changes from v2.0 to v2.1.

0.0.0.17

In development.

Breaking Changes

• Keysharp-only built-in variables moved into the Ks module, joining those already there, and must be imported to be used: A_AhkBuildVersion, the A_Asm* family, A_ClipboardTimeout, A_HotIfTimeout, A_InputLevel, A_IsPersistent, A_KeysharpPath, A_LoopKey, A_MaxThreadsBuffer, A_MaxThreadsPerHotkey, A_NewLine, A_PeekFrequency and A_Priority.
• Ks.JsonEncode and Ks.JsonDecode became Json.Encode and Json.Decode on the Json class.
• Built-in parameter names were corrected to match this documentation, and those which were not valid identifiers were renamed so that named arguments can address them: Part# became PartNumber (StatusBarGetText, StatusBarWait), RootDir\Filename became RootDirFilename (FileSelect), ControlID-or-Pos became ControlOrPos (ControlClick) and YYYYMMDDHH24MISS became Timestamp (FormatTime). Only calls which name a parameter are affected.
• FuncObj is no longer a name. The function-object class is Func, so MsgBox is Func works and MsgBox is FuncObj does not; the internal name appears only in low-level diagnostics such as stack traces. InputObject likewise became InputHook, and the remaining implementation classes were hidden from global scope.
• Overlay.Update replaces the overlay's image and geometry in one call. SetImage was removed.
• Image API changes: DrawText and MeasureText take Gui.SetFont-style Options and FontName arguments in place of one font string, and MeasureText returns a {w, h} object instead of writing to ByRef variables; Opacity became Alpha; and Search, SearchAll and SearchPixel return a match object and take the region as flat X, Y, W, H parameters.
• InputHook.OnMouseMove reports movement deltas as (Hook, DX, DY) rather than positions. Per-platform extras, such as the device identifier on Linux, arrive in A_EventInfo.
• Callbacks are checked when they are registered: one which requires more parameters than the registration site will ever pass — a SetTimer, Hotkey or OnMessage callback — throws there rather than at each invocation. Declaring fewer is allowed, so a hotkey callback may ignore the hotkey name it is handed.
• Array.IndexOf throws an IndexError for an out of bounds StartIndex (0, or an absolute value exceeding the length), as the sibling FindIndex already did, instead of returning 0. An empty array still returns 0.
• OwnProps takes no parameters. The undocumented getValues parameter was removed — how many values an iteration yields is decided by the for-loop's variable count — so OwnProps(false) is an error rather than a no-op.
• OutputDebug takes only the documented Text; its undocumented second parameter was removed. Ks.OutputDebugLine still takes the clear flag.
• StartsWith and EndsWith take CaseSense, matching InStr, in place of the inverted-sense ignoreCase. Both settings are culture-invariant; only the explicit Locale option consults the current culture.

New

• Named arguments: an argument can name the parameter it is for (SubStr(s, StartingPos: 2)) instead of relying on its position. A name that matches no parameter is an error, reported before the script runs where it can be (#Warn NamedArg). The name may also be computed with a dereference, as an object-literal key can. NamedArgs is the carrier type, for building or inspecting such a call at run time.
• Func.Params describes a function's parameters — name, position, whether optional, ByRef or variadic, and any default.
• Support for keys which send a combination rather than a single keystroke, such as the Copilot and Office keys. Copilot is a Keysharp alias in static hotkey and remap declarations, which the compiler replaces with the combination <#<+F23 that the key's firmware emits; it is not a runtime key name, so Send, Hotkey and the key-state functions still take the component keys. There is no Office alias.
• Both terms of a custom combination may carry modifiers (<^a & b::, a & <^b::). Those on the prefix are tested when it goes down and the verdict held until it is released, which is what lets a key whose firmware asserts modifiers and drops them immediately serve as a prefix.
• Gui.OnMessage and Gui.Control.OnMessage register a callback for a window message ahead of default processing. Window messages are a Win32 concept, so the registration is accepted but never fires on Linux and macOS.
• SoundPlay and SoundBeep play on Linux and macOS as well as Windows, including the *n standard sounds. macOS plays through afplay; Linux picks the best installed player for the file type, so which formats are available depends on which of them are present.
• WinEvent.CaretMove fires when the text caret moves, reporting the caret's screen rectangle in A_EventInfo. Move likewise reports the window's new position and size there. Every WinEvent type is delivered on all platforms, subject to each one's event source — see the platform sections on that page.
• Overlay.OnEvent registers Click, DoubleClick, ContextMenu and MouseMove handlers, receiving coordinates local to the overlay. The overlay must not be click-through to receive them.
• Gui +DPIResize, with its per-control override, re-lays a window out when it moves to a display with a different DPI. The Menu item options Radio, Right, RTL, Break and BarBreak are supported, with per-platform limits noted on that page.
• Array.Remove returns whether it removed anything, and Contains, IndexOf and Remove search for an element which has no value when Value is omitted.
• #Import accepts a relative path, binding the leaf name, and a module whose function or class shares its name exports that as the default.
• The compatibility target moved to AutoHotkey v2.1-alpha.30, bringing typed parameter and return signatures for CallbackCreate, ObjSetBase, and the numeric type classes and further struct members.
• Ks.FileCreateTemp creates an empty temporary file and returns its full path.

Platform

• Linux: mouse input on wlroots-based compositors (Sway, Hyprland, Wayfire, labwc) through zwlr_virtual_pointer_v1. Overlays on KWin and wlroots receive mouse input through their layer-shell surfaces; compositor-drawn overlays on GNOME and Cinnamon cannot yet.
• macOS: osx-x64 builds for Intel Macs are published alongside osx-arm64. macOS 15 or later is required.
• Linux and macOS: the main window's About dialog.

Fixes and Performance

Send restoring modifiers from a stale snapshot in SendEvent mode, #Warn reporting the wrong line inside an included file, #Import creating a setter for a read-only property, overriding a built-in class's __Enum, main window content on Windows and error dialog sizing on a scaled display. #HotIf criteria are evaluated through a cheaper executor.

0.0.0.16

Released 19 July 2026.

Breaking Changes

• ImageCapture() was removed. Use the Image class instead.
• Linux input requires the keysharp-inputd daemon; the SharpHook and X11 fallbacks were removed. See Platform Support.
• A_ScaledScreenDPI was renamed to A_ScreenScale.
• A_OSType now returns WINDOWS, OSX or LINUX.
• A_LineFile in the main file resolves to the main script's full path, as A_ScriptFullPath does.
• #Import inside a function or class body binds to that scope, and an unknown import throws.
• Reserved words can no longer be used as variable names.
• Invalid Gui options now throw instead of being ignored.

New

• Image captures, loads, creates, draws, transforms, searches and manipulates pixels before saving. It replaces ImageCapture().
• Overlay is an always-on-top, click-through canvas using the same drawing primitives as Image. It now backs Highlight and ToolTip on Linux and macOS.
• WinEvent subscribes to window events across platforms: Active, Exist, NotExist, Move, Minimize, Restore and TitleChange.
• A_ThreadId and Exit with a thread identifier.
• OnMouseDown, OnMouseUp and OnMouseMove on InputHook.
• Fully cross-platform monitor functions, plus MonitorGetScale and MonitorFromPoint in the KS module.
• Gui +ClickThrough and +AutoScroll options.
• An *Dir scan-direction option for ImageSearch.
• An OCR library (OCR.ks) with a pluggable engine, and demo scripts including ClipboardHistory, InputHUD, OCRSnip, Shell, WindowGrab and WindowTiler.

Platform

• Linux: all input channels now go through keysharp-inputd (evdev and uinput), reworked for multi-user handling, per-script permissions, Unicode sending and mouse buttons.
• Wayland: overlays, clipboard and window manipulation through KWin scripting and Keysharp shell extensions for GNOME (including v48 and later) and Cinnamon.
• macOS: the hook and sender were revamped on CGEventTap and the key sender is now functional. Binaries are signed, and releases include DMG and PKG packages with SHA256 checksums.

Fixes and Performance

Release-mode stack traces for C# exceptions, OnExit teardown, script exit when the last window closes, thread priority handling and DLL path normalization. Parser fixes for #Include, static variables, dereferences and remap syntax. Regular-expression pattern caching, font caching, cheaper per-call thread setup and faster keyboard-layout queries.

0.0.0.15

Released 22 June 2026. This release made Keysharp cross-platform across Windows, Linux and macOS.

• macOS support: window management, the keyboard and mouse hook and sender, sound and drive functions, App Switcher integration and native Command-key handling, plus AxSpy, an accessibility inspector.
• Linux: the inputd input daemon, .deb packaging with automatic .NET 10 installation, Unicode character sending and Keyview syntax highlighting.
• New parser: a hand-written parser replaced ANTLR4, which is faster and less ambiguous.
• AutoHotkey v2.1 features: the v2.0 and v2.1 compatibility modes, structs with #StructPack, the #Import directive, PropRef, the !~= operator and ahk_opt.
• Scheduler: the timer and event scheduler was reworked, fixing timer livelock and timers not firing inside hotkey callbacks.
• Cross-platform GUI on Eto: DPI scaling, dialog theming, hyperlink labels and A_GuiTheme.
• The hook and sender were brought current with AutoHotkey 2.0.26.

Earlier Releases

Notes for 0.0.0.14 and earlier are on the release page. For changes which have not yet been released, see the source history; documentation changes are tracked in the KeysharpDocs history.

Inherited Upstream History

The original AutoHotkey change log is retained as an archived upstream reference. Its entries describe releases of AutoHotkey, not of Keysharp.