Class UioHook

Namespace

SharpHook.Native

Assembly

SharpHook.dll

Contains native methods of libuiohook.

[ExcludeFromCodeCoverage]
public static class UioHook

Inheritance

object

UioHook

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

CreateScreenInfo()

Gets the information about screens.

public static ScreenData[] CreateScreenInfo()

Returns

ScreenData[]

The information about screens.

Remarks

This is the safe version of CreateScreenInfo(out byte) as it returns a managed array.

See Also

CreateScreenInfo(out byte)

CreateScreenInfo(out byte)

Gets the information about screens.

public static nint CreateScreenInfo(out byte count)

Parameters

count byte

The number of screens.

Returns

nint

The information about screens as an unmanaged array of ScreenData whose length is returned as count. The memory used by the array must be freed manually.

Remarks

You should use CreateScreenInfo() instead as it returns a managed array.

See Also

CreateScreenInfo()

GetAutoRepeatDelay()

Gets the auto-repeat delay.

public static extern int GetAutoRepeatDelay()

Returns

int

The auto-repeat delay.

GetAutoRepeatRate()

Gets the auto-repeat rate.

public static extern int GetAutoRepeatRate()

Returns

int

The auto-repeat rate.

GetAxPollFrequency()

Gets the frequency in seconds for polling the access to the macOS Accessibility API when the global hook is running. The default value is 1 second.

public static extern uint GetAxPollFrequency()

Returns

uint

The frequency in seconds for polling the access to the macOS Accessibility API when the global hook is running.

Remarks

On Windows and Linux, this method does nothing and always returns 0.

GetMultiClickTime()

Gets the multi-click time.

public static extern int GetMultiClickTime()

Returns

int

The multi-click time.

GetPointerAccelerationMultiplier()

Gets the pointer acceleration multiplier.

public static extern int GetPointerAccelerationMultiplier()

Returns

int

The pointer acceleration multiplier.

GetPointerAccelerationThreshold()

Gets the pointer acceleration threshold.

public static extern int GetPointerAccelerationThreshold()

Returns

int

The pointer acceleration threshold.

GetPointerSensitivity()

Gets the pointer sensitivity.

public static extern int GetPointerSensitivity()

Returns

int

The pointer sensitivity.

GetPostTextDelayX11()

Gets the delay (in nanoseconds) between posting individual characters when posting text on Linux.

public static extern ulong GetPostTextDelayX11()

Returns

ulong

The delay (in nanoseconds) between posting individual characters when posting text on Linux.

Remarks

X11 doesn't support posting arbitrary Unicode characters directly. Instead, for each character, an unused key code is remapped to that character, and then key press/release is simulated. Since the receiving application must react to the remapping, and may not do so instantaneously, a delay is needed for accurate simulation.

The default delay is 50 milliseconds.

On Windows and macOS, this method always returns 0.

See Also

EventSimulator

GetPromptUserIfAxApiDisabled()

Gets the value which indicates whether global hooks or event simulation should prompt the user when they try to request access to macOS Accessibility API, and it is disabled. The default value is true.

public static bool GetPromptUserIfAxApiDisabled()

Returns

bool

true if global hooks and event simulation will prompt the user for access to macOS Accessibility API when it is disabled. Otherwise, false.

Remarks

On Windows and Linux, this method does nothing and always returns false.

IsAxApiEnabled(bool)

Checks whether access to macOS Accessibility API is enabled for the process, optionally prompting the user if it is disabled.

public static bool IsAxApiEnabled(bool promptUserIfDisabled)

Parameters

promptUserIfDisabled bool

Prompt the user if access to macOS Accessibility API is disabled.

Returns

bool

true if access to macOS Accessibility API is enabled for the process which means that global hooks and event simulation can be used. Otherwise, false.

Remarks

On Windows and Linux, this method does nothing and always returns true.

IsKeyTypedEnabled()

Checks whether events of type KeyTyped are enabled.

public static bool IsKeyTypedEnabled()

Returns

bool

true if events of type KeyTyped are enabled. Otherwise, false.

Remarks

If the application doesn't use events of type KeyTyped, then they should be disabled so that there is no performance penalty and no subtle system-wide side effects.

PostEvent(ref UioHookEvent)

Posts a fake input event.

public static UioHookResult PostEvent(ref UioHookEvent e)

Parameters

e UioHookEvent

The event to post.

Returns

UioHookResult

The result of the operation.

Remarks

The instance of the event doesn't need all fields to have value. Only Type, Keyboard/Mouse/Wheel should be present.

The following table describes the specifics of simulating each event type.

Event type	Description
HookEnabled	Events of this type are ignored.
HookDisabled	Events of this type are ignored.
KeyPressed	Only KeyCode is considered.
KeyReleased	Only KeyCode is considered.
KeyTyped	Events of this type are ignored. PostText(string) should be used to post Unicode characters.
MousePressed	Only X, Y, and Button are considered.
MouseReleased	Only X, Y, and Button are considered.
MouseClicked	Events of this type are ignored.
MouseMoved	Only X and Y are considered.
MouseDragged	Not recommended to use; same as MouseMoved.
MouseWheel	Only Rotation, Direction, and Type are considered.

See Also

PostEvents(UioHookEvent[], uint)

EventSimulator

PostEvents(UioHookEvent[], uint)

Posts a sequence of fake input events.

public static UioHookResult PostEvents(UioHookEvent[] events, uint size)

Parameters

events UioHookEvent[]

The events to post.

size uint

The number of events to post.

Returns

UioHookResult

The result of the operation.

Remarks

All the same rules apply as to PostEvent(ref UioHookEvent).

See Also

PostEvent(ref UioHookEvent)

EventSimulator

PostText(string)

Simulates the input of arbitrary Unicode characters.

public static UioHookResult PostText(string text)

Parameters

text string

The text to simulate.

Returns

UioHookResult

The result of the operation.

Remarks

The text to simulate doesn't depend on the current keyboard layout. The full range of UTF-16 (including surrogate pairs, e.g., emojis) is supported.

On Windows, text simulation should work correctly and consistently.

On macOS, applications are not required to process text simulation, but most of them should handle it correctly.

X11 doesn't support text simulation directly. Instead, for each character, an unused key code is remapped to that character, and then key press/release is simulated. Since the receiving application must react to the remapping, and may not do so instantaneously, a delay is needed for accurate simulation. This means that text simulation on Linux works slowly and is not guaranteed to be correct. SetPostTextDelayX11(ulong) can be used to increase (or decrease) the delay if needed – longer dealys add consistency but may be more jarring to end users. GetPostTextDelayX11() can be used to get the currently configured delay – the default is 50 milliseconds.

See Also

EventSimulator

Run()

Runs the global hook and blocks the thread until it's stopped.

public static extern UioHookResult Run()

Returns

UioHookResult

The result of the operation.

Remarks

This method must not be called when a global hook is already running since it will corrupt the global state of libuiohook.

RunKeyboard()

Runs the global hook only for keyboard events and blocks the thread until it's stopped.

public static extern UioHookResult RunKeyboard()

Returns

UioHookResult

The result of the operation.

Remarks

This method makes a difference only on Windows where there are two different global hooks – a keyboard hook and a mouse hook. On macOS and Linux there is one hook for all events, and this method simply enables filtering mouse events out on these OSes.

When a keyboard-only hook is running, the Mask field will not contain any mouse button state.

This method must not be called when a global hook is already running since it will corrupt the global state of libuiohook.

RunMouse()

Runs the global hook only for mouse events and blocks the thread until it's stopped.

public static extern UioHookResult RunMouse()

Returns

UioHookResult

The result of the operation.

Remarks

This method makes a difference only on Windows where there are two different global hooks – a keyboard hook and a mouse hook. On macOS and Linux there is one hook for all events, and this method simply enables filtering keyboard events out on these OSes.

When a mouse-only hook is running, the Mask field will not contain any keyboard modifier state.

This method must not be called when a global hook is already running since it will corrupt the global state of libuiohook.

SetAxPollFrequency(uint)

Sets the frequency in seconds for polling the access to the macOS Accessibility API when the global hook is running. The default value is 1 second.

public static extern void SetAxPollFrequency(uint frequency)

Parameters

frequency uint

The frequency in seconds for polling the access to the macOS Accessibility API when the global hook is running.

Remarks

On Windows and Linux, this method does nothing.

SetDispatchProc(DispatchProc?, nint)

Sets the hook callback function.

public static void SetDispatchProc(DispatchProc? dispatchProc, nint userData)

Parameters

dispatchProc DispatchProc

The function to call when an event is raised, or null to unset the function.

userData nint

Custom data to pass to the callback. Should not be used to pass pointers to objects, and Zero should usually be passed.

See Also

DispatchProc

SetKeyTypedEnabled(bool)

Sets the value which indicates whether events of type KeyTyped are enabled. The default value is true.

public static void SetKeyTypedEnabled(bool enabled)

Parameters

enabled bool

true if events of type KeyTyped should be enabled. Otherwise, false.

Remarks

If the application doesn't use events of type KeyTyped, then they should be disabled so that there is no performance penalty and no subtle system-wide side effects.

SetLoggerProc(LoggerProc?, nint)

Sets the log callback function.

public static void SetLoggerProc(LoggerProc? loggerProc, nint userData)

Parameters

loggerProc LoggerProc

The function to call for logging, or null to unset the function.

userData nint

Custom data to pass to the callback. Should not be used to pass pointers to objects, and Zero should usually be passed.

See Also

LoggerProc

SetPostTextDelayX11(ulong)

Sets the delay (in nanoseconds) between posting individual characters when posting text on Linux.

public static extern void SetPostTextDelayX11(ulong delayNanoseconds)

Parameters

delayNanoseconds ulong

The delay (in nanoseconds) between posting individual characters when posting text on Linux.

Remarks

X11 doesn't support posting arbitrary Unicode characters directly. Instead, for each character, an unused key code is remapped to that character, and then key press/release is simulated. Since the receiving application must react to the remapping, and may not do so instantaneously, a delay is needed for accurate simulation.

The default delay is 50 milliseconds.

On Windows and macOS, this method does nothing.

See Also

EventSimulator

SetPromptUserIfAxApiDisabled(bool)

Sets the value which indicates whether global hooks or event simulation should prompt the user when they try to request access to macOS Accessibility API, and it is disabled. The default value is true.

public static void SetPromptUserIfAxApiDisabled(bool promptUserIfDisabled)

Parameters

promptUserIfDisabled bool

true if global hooks and event simulation should prompt the user for access to macOS Accessibility API when it is disabled. Otherwise, false.

Remarks

On Windows and Linux, this method does nothing.

Stop()

Stops the global hook.

public static extern UioHookResult Stop()

Returns

UioHookResult

The result of the operation.

See Also

IAccessibilityProvider

IEventSimulationProvider

IGlobalHookProvider

ILoggingProvider

IMouseInfoProvider

IScreenInfoProvider

UioHookProvider