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

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

Compatibility target: AutoHotkey v2.1-alpha.33.

Breaking Changes

• StrPtr and VarSetStrCapacity use variable-owned UTF-16 memory. VarSetStrCapacity clears the variable and leaves it a String. Native writes reach the variable at VarSetStrCapacity(&Var, -1) or when it is next passed as Str; unlike AutoHotkey, a write preserving the length is not immediately visible. A literal's pointer remains valid while the string exists. ObjFree was removed.
• A naked variable passed as literal Str or WStr to DllCall or ComCall receives native writes without changing other variables sharing its string. AStr is input-only and uses the system ANSI code page.
• On Windows, ObjPtr returns an Integer borrowed IUnknown address: ObjPtr(Obj).Ptr becomes ObjPtr(Obj). Keep the object alive while using the address. Use ObjPtrAddRef and a matching ObjRelease when a separately counted COM reference is needed.
• DllCall releases its own newly loaded library reference after the call. Use #DllLoad to keep a library resident when retaining its function pointers or native state.
• StringBuffer supports UTF-16 only; "ANSI" was removed. Use a Buffer with StrGet(Buf, "CP0") for ANSI output. Capacity is the requested character count, without the former extra character.
• Direct references to a variable share one VarRef, so &x == &x is true. Output and ByRef parameters require a VarRef or virtual reference; ordinary objects cannot receive them.
• Numeric conversion, operators and built-in validation follow AutoHotkey more closely. Invalid numeric text raises an error, relational operators compare numbers only, and documented ranges are enforced. Use StrCompare to order strings. Implicit object-to-string conversion requires ToString; Map.ToString uses square brackets.
• A Buffer without FillByte is uninitialized. Pass 0 explicitly for zero-filled memory. Image.GetPixelData defaults to 4 bytes per pixel (RGBA); pass 1 for grayscale. Crypt string input defaults to UTF-8 instead of UTF-16.
• Float-to-string conversion uses 17 significant digits, so 0.1 displays as 0.10000000000000001. InStr and StrReplace use Unicode ordinal case folding for both Off and Locale.
• RunScript takes separate Async and Callback parameters: a callback formerly passed second moves to the third argument, with true second. ExitCode and ExitTime are empty while the child is running.
• ParseScript(Code) became ValidateScript(Code) for syntax checks or CompileScript(Code) for compilation. Test Result.IsValid; diagnostics are in Result.Errors and Result.Warnings.
• Pass function objects as callbacks: SetTimer("MyFunc") becomes SetTimer(MyFunc). Use ObjBindMethod instead of Func(Name, Obj). GUI event sinks still accept method names. CallbackCreate returns an Integer address: cb.Ptr becomes cb, also passed to CallbackFree.
• OnExit, OnError, OnClipboardChange, OnMessage and GUI/Overlay event registration keep one entry for the same callback. Each EventHook factory call creates a separate subscription. A non-empty OnEvent/OnCommand result, including 0, stops later handlers. OnMessage can also claim a message by returning 0.
• Built-in modules require #Import. Import Ks names explicitly, for example #Import Ks { App, A_PeekFrequency }, or import Ks and qualify them. Module objects expose their own and imported names; use Other.%Name% instead of Other[Name]. Standalone and default exports were removed; modules export their globals, functions and classes.
• Keysharp settings moved into Ks and must be imported: A_OSType, A_ClipboardTimeout, A_HotIfTimeout, A_Persistent, A_MaxThreadsBuffer, A_MaxThreadsPerHotkey, A_NewLine and A_PeekFrequency.
• #Assembly* and #HookMutexName became keys of #App. Assembly metadata is available through App; missing metadata attributes return empty strings. App.Name always reports the running assembly's identity, including when Name was not declared.
• WinEvent uses an instance with callback slots: WinEvent.Active(Callback, WinTitle) becomes Hook := WinEvent(WinTitle), Hook.OnActive := Callback, Hook.Start(). Count and EventType were removed; stop the hook in the callback when appropriate, and identify the event by its callback slot.
• WinEvent.IsActive became InProgress. Start/Stop replace Pause/IsPaused, and running hooks keep the script alive. A_EventInfo contains {X, Y, Width, Height} for move/caret events; use the callback's Time parameter for the event time.
• RealThread.Wait became Await(worker.Terminated) for thread completion or Await(worker.Task) for its result. Replace ContinueWith with worker.Task.Then(v => RealThread(Callback, Arguments*)) for a worker continuation; errors are delivered through Task. Exit takes only ExitCode; use a Thread object to end another thread.
• CLR APIs returning a .NET task return a Task wrapper. Result does not wait; use Await. Raw CLR access is through ToClr. Script callbacks invoked from foreign CLR threads are asynchronous and cannot return a value to the CLR caller. Subscribe to CLR events with OnEvent, rather than add/remove accessors.
• Overlay construction takes no arguments or a complete rectangle; use FromImage for an image. Draw through Canvas, then Present. Update became SetImage, BeginDraw/EndDraw were removed, and Redraw receives the replacement canvas. Copy the borrowed Canvas before taking ownership or transforming it.
• Image.DrawText and MeasureText take font Options and FontName; MeasureText returns an object. Opacity became Alpha. Search, SearchAll and SearchPixel return match objects and take a flat region.
• Returned object members use PascalCase and spelled-out names, including {Width, Height} and {X, Y}. Overlay/Highlight.W and H became Width and Height; Visible became IsVisible; RequestCapabilities.Granted became IsGranted.
• WebBrowser, AddWebBrowser and Gui.WebBrowser became WebView, AddWebView and Gui.WebView. RichText belongs to RichEdit and returns RTF; use Value for plain text. StatusBar.Value no longer sets text; use Text or SetText. SetTabIcon uses 1-based indices.
• InputHook.OnMouseMove receives deltas (Hook, DX, DY). Ending input discards queued character/key/mouse notifications; OnEnd still runs. BeforeHotkeys cannot change while input is running.
• On Windows, an Array passed to COM remains an object; use ComObjArray for a SafeArray. Booleans are passed as integers 1/0; use ComValue(0xB, Value) for a COM boolean. Type information can still trigger automatic conversion.
• On Windows, a hotstring typed straight after kana, a spacing vowel sign or a letter outside the BMP needs the ? option, since Unicode categories decide whether the preceding character continues a word.
• Mail requires host and from. The header option became headers, taking a Map; invalid options and unusable recipients or attachments raise errors.
• StartsWith and EndsWith take CaseSense instead of ignoreCase. OwnProps takes no arguments. OutputDebug takes only Text; Ks.OutputDebugLine takes the clear flag. Unknown encoding names raise ValueError.
• ImageSearch's *Dir takes direction names such as *DirTopRight instead of digits. File.RawWrite and FileAppend RAW write string UTF-16 bytes; File.Seek returns 1/0. Built-in parameter names were corrected for named arguments.
• Window actions target the first match, or the group with a lone ahk_group. WinWait functions and StatusBarWait check once for Timeout 0. ProcessWaitClose returns 0 when all matches have closed.
• On Linux and macOS, ControlSend and list Control functions report unsupported foreign targets or invalid controls instead of silently returning; see each function's platform limits. A_AppData and A_AppDataCommon use the platform's configuration directories.
• On Linux, SoundGetVolume, SoundSetVolume and Audio.Device.Volume use mixer slider percentages: 50 means 50%, instead of approximately 79%. Session/playback volumes remain linear gain; writes preserve channel balance.

Other removed or renamed extensions:

New

• The Keysharp-specific hotstring In option sets an input level from 0 through 100 for an individual hotstring or a default with #Hotstring I1 or Hotstring("I1"). An explicit hotstring default takes precedence over the #InputLevel fallback.
• #App declares application metadata, icons, themes, Linux DesktopEntry and embedded files; App reports metadata, command line and exit status. #TrayIcon embeds a startup icon, and FileInstall extracts embedded files.
• Dash launches scripts, templates, tools, demos and the package-manager GUI. The bundled KPM manages script libraries through keysharp --kpm. --compile asm compiles several scripts to separate .cks files. The parser and compiler are optional deployment components, so compiled scripts can run with the runtime alone; IsComponentAvailable checks their availability.
• Named arguments, NamedArgs, Func.Params, operator overloading, and a distinct Boolean type. CallbackCreate accepts typed parameter/return signatures, including a void return; Gui.FontHandle exposes the native handle of the GUI's default font.
• Await and Task support asynchronous results and continuations while processing script events. RealThread.Post and Exit return tasks. Lock provides timed locking, and Thread objects expose script-thread state and exit codes.
• EventHook standardizes subscription lifetime, Start/Stop and status. WinEvent adds OnCaretMove and OnNotActive; Overlay.OnEvent adds mouse handlers.
• Image vector drawing adds paths, gradients, affine transforms, intersecting clips and drawing-state snapshots.
• Http provides synchronous/asynchronous requests and sessions; Url encodes URL and form text. Crypt provides hashes, AES, PBKDF2, HMAC and secure randomness; Hex and Base32 provide encoding.
• Clipboard handles text, images, files and native formats with change notifications. Monitor exposes display geometry, scale, brightness and DDC/CI controls. Audio provides playback, recording, devices, sessions and metering; its Linux/macOS backends remain unverified.
• WebView provides navigation, scripting and page messages; its engine and prerequisites vary by platform. RichEdit adds formatted text, highlighting and editing APIs, with platform limits.
• Font value objects, per-window icons, +DPIResize and +Round, ListView row/cell colors, and Taskbar badges/progress. Gui.OnMessage and control OnMessage callbacks monitor native Windows messages or synthesized mouse and keyboard messages from the script's own GUI on Linux and macOS; macOS delivery remains unverified.
• #CSharp embeds C#; #Package and Clr.LoadPackage load NuGet packages. CLR interop adds event subscriptions, ToClr/Wrap, integer enum arguments and direct Array/Map collection arguments.
• Json adds Indent and CaseSense options. DirCopy extracts zip, tar and gzip archives. SplitPath can return an object; File.Read accepts an omitted count, and encoding parameters accept .NET encoding names.
• Array.Remove returns whether it removed an item; Contains, IndexOf and Remove can search for unset elements. #Import supports relative paths and explicit forwarding with #Import Export.
• The Copilot alias is accepted in hotkey and remap declarations, including either term of a custom combination. Custom combinations accept modifiers on both terms. The standard menus include Pause Script.
• #Warn Experimental flags Image, Audio, Monitor, Clr and Overlay imports; these APIs may change without deprecation. #Warning reports compile-time messages. A_ProcessArch and A_OSArch report CPU architecture. Ks.FileCreateTemp creates temporary files.

Platform

• The compile daemon runs unelevated. An elevated launcher retains its privileges for script execution and falls back to local compilation when necessary.
• Windows: ARM64 builds and a WiX-based installer. MsgBox uses the native Unicode Windows dialog.
• Linux: optional keysharp-input and keysharp-desktop components provide global input and authorized desktop integration on X11/Wayland, with backend-specific limits. Both components require ABI 1.0 or a compatible newer 1.x minor; upgrade older helpers. Releases are available through the Ubuntu PPA, with a separate NixOS guide. The .deb recommends WebKitGTK for WebView.
• Linux: ComObject uses D-Bus, including named methods/properties and ComObjConnect signals. Pointer-based COM functions remain unavailable.
• macOS: Intel and ARM64 builds require macOS 15 or later. The Apple Installer package installs for one user or all users, installs .NET 10 when needed, and offers terminal commands and VS Code integration. Uninstall is available from Dash or the release DMG, with an option to retain settings. ComObject uses Apple Events for scriptable applications and requires Automation permission; this backend remains unverified.
• Linux and macOS: SoundPlay supports file playback and SoundBeep honors frequency and duration. The About dialog, status-bar click reporting, and process-wide Classic/System/Dark themes are available. Linux playback formats depend on the installed player.

Fixes and Performance

Compatibility and correctness fixes cover parsing, imports and closures, numeric/string operations, regex options and callouts, errors, callbacks, input, timers, window/control operations, COM by-reference VARIANT writes, file/registry operations and native memory. GUI automatic sizing, Edit resizing, RichEdit text casing, exact image copies, and Linux/macOS list/tree controls, InputBox, menus and coordinates are corrected. macOS GUIs accept the first click and use window-server handles; BlockInput blocks requested mouse movement in foreign applications, and Keyview pastes plain text. Hotstrings recognize abbreviations of any length and punctuation boundaries on Linux/macOS. Linux native-state queries and Wayland window/overlay updates are refreshed. Logical comparison is portable. Parsing, object/collection access, window/control searches, hotstring matching, COM calls and file loops are faster; native-resource cleanup, compiler-daemon recovery and interruptible waits are improved. See Platform Support for backend limits.

0.0.0.16

Released 2 August 2026.

Breaking Changes

• ImageCapture() was removed. Use the Image class instead.
• Linux input requires the privileged evdev/uinput service; 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 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 backs Highlight and ToolTip on Linux and macOS.
• WinEvent subscribes to window events across platforms: Active, Exist, NotExist, Move, Minimize, Restore and TitleChange.
• Thread identity, and Exit targeting a thread other than the current one.
• 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: input channels use the evdev/uinput service, with 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 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.
• 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 and hyperlink labels.
• 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.