Changes from AutoHotkey to Keysharp

Keysharp implements the AutoHotkey v2.1-alpha.30 language on .NET, and runs on Windows, Linux and macOS. Most scripts behave as their AutoHotkey documentation describes. This page explains the differences which are structural — the ones worth understanding before porting a script — and then indexes the pages which state each exact contract.

Note: The absence of an item here does not prove that inherited behavior has been verified on every platform. See Platform Support and the platform remarks on the affected page.

Table of Contents

• Core Differences:
  • Scripts are compiled, not interpreted
  • Three platforms, one language
  • A managed object model
  • Language additions
• Detailed Index:
  • Runtime and Language
  • Memory and Interop
  • GUI and Desktop Integration
  • Additional APIs
  • Unavailable or Reduced Inherited Behavior

Core Differences

Scripts are compiled, not interpreted

AutoHotkey interprets a script. Keysharp reads it, lowers it to C#, and has Roslyn compile it to a .NET assembly which is then executed. How a Script Executes describes the pipeline, and the --transpile and --compile options expose its intermediate results.

Several inherited behaviors follow from this rather than from any deliberate design choice:

• A syntax error anywhere in the script is reported before any of it runs, so a script cannot begin executing and fail later on a line which does not parse.
• An error's stack reports managed call frames, which name the C# methods the script was compiled into. A few built-in classes carry an internal type name in that output.
• ListLines has no compiled equivalent, and Thread is not line-aware.

Three platforms, one language

AutoHotkey is a Windows automation tool, and much of its library is defined in terms of Win32. Keysharp runs the same language on Windows, Linux and macOS, which means a page describing a Win32 behavior describes an intent that each platform meets to a different degree.

Platform Support is therefore a primary reference rather than an appendix: it covers X11, Wayland, macOS permissions and foreign-window automation. On Linux and macOS, input and window control depend on OS-level permissions and helpers, and a script can declare what it needs with #Requires or RequestCapabilities.

The GUI is built on a cross-platform toolkit rather than Win32 common controls. Window styles, control messages and other Win32-level facilities are consequently unavailable or approximated; GUI Control Types and GUI Events record where.

A managed object model

Objects are .NET objects. Object lifetime and finalization follow the garbage collector instead of reference counting, so __Delete runs when the collector reclaims the object rather than when the last reference goes away, and the reference-counting functions reflect the managed runtime.

The same applies wherever a script reaches outside itself for memory: DllCall, CallbackCreate, StrPtr and ObjPtr operate on managed values, and StringBuffer is the writable string-memory type to pass to native code. For calling .NET directly, Clr is available.

Language additions

Keysharp adds facilities which have no AutoHotkey counterpart. A script which uses them will not run under AutoHotkey:

• Conditional compilation and build directives, which act at compile time.
• The KS module, which holds the Keysharp-specific API surface, imported explicitly.
• Additional built-in variables, functions and classes, indexed under Additional APIs below.

Detailed Index

Each link below leads to the canonical contract for that behavior.

Runtime and Language

• Scripts compile to .NET assemblies instead of being interpreted, and a few built-in classes carry an internal type name that can appear in diagnostic output.
• Object lifetime and finalization follow the .NET garbage collector.
• Increment/decrement, concatenation assignment, numeric literals, unset values and dynamic dereferencing have documented implementation differences.
• Reference parameters accept additional target forms, while the reference operator returns a VarRef rather than a raw address.
• Conditional-compilation directives and Keysharp build directives extend the language.
• The KS module contains Keysharp-specific APIs.

Memory and Interop

• StringBuffer is the preferred writable string-memory type for native calls.
• StrPtr, ObjPtr, reference counting, CallbackCreate and DllCall reflect the managed runtime.
• Clr provides experimental direct .NET interop.

GUI and Desktop Integration

• Gui includes container-relative positioning, GroupBox containers, automatic scrolling, macOS application menus and visibility access.
• GUI controls document toolkit-specific additions and unavailable Win32 behavior.
• GuiControl, ListView, TreeView and Menu have additional methods and properties.
• WinEvent, Overlay and Image add cross-platform desktop facilities.
• Platform Support describes X11, Wayland, macOS permissions and foreign-window automation.

Additional APIs

• Keysharp built-in variables
• String and Base64 functions
• Cryptographic and checksum functions
• File path functions
• C# regular-expression functions
• FormatCs
• RequestCapabilities
• Clipboard helper functions
• RunScript and ProcessInfo
• RealThread and LockRun
• Mail
• Collect

Unavailable or Reduced Inherited Behavior

The affected reference pages document the exact boundary. Notable areas include:

• interactive debugging and DBGp are not implemented;
• ListLines;
• FormatTime flags and PixelGetColor mode;
• DirSelect and MsgBox modality;
• OnMessage dispatch, Thread line awareness and Download options; and
• toolkit-specific control behavior in GUI Control Types and GUI Events.

Version Differences

The differences above are between Keysharp and its AutoHotkey compatibility target. For changes between AutoHotkey versions themselves, see Changes from v2.0 to v2.1 and Changes from v1.1 to v2.0. For changes between Keysharp releases, see Recent Changes.