Onemacro Lua API

Overview

The Onemacro Lua API is a set of functions using the Lua programming language and provides advanced scripting functionality for any mice and keyboards with the Onemacro program.

This page assumes a working knowledge of the Lua programming language. Further information can be obtained from www.lua.org.

The script is invoked using an event handler, OnEvent. Users may examine the various events exposed in this handler to perform their desired actions.

Reference

• OnEvent
• Sleep
• PressKey
• ReleaseKey
• PressAndReleaseKey
• IsModifierPressed
• PressMouseButton
• ReleaseMouseButton
• PressAndReleaseMouseButton
• IsMouseButtonPressed
• MoveMouseTo
• MoveMouseWheel
• MoveMouseRelative
• MoveMouseToVirtual
• IsKeyLockOn
• EnablePrimaryMouseButtonEvents
• Standard Lua 5.1 Libraries
• Appendix A

OnEvent

The OnEvent() function serves as the event handler for the script. You will need to implement this function.

function OnEvent(event, arg)

end

Parameters

Return Values

Remarks

Example

-- This is the primary event handler
-- You must implement this function

function OnEvent(event, arg)
	if (event == "PROFILE_ACTIVATED") then
		--profile has been activated
	end

	if (event == "PROFILE_DEACTIVATED") then
		--profile has been deactivated
	end

	if (event == "MOUSE_BUTTON_PRESSED" and arg == 3) then
		--Mouse Button 3 has been pressed
	End

	if (event == "MOUSE_BUTTON_RELEASED" and arg == 3) then
		--Mouse Button 3 has been released
	end
end

Sleep

Sleep() will cause the script to pause for the desired amount of time.

Sleep( timeout );

Parameters

Return Values

Remarks

Example

-- Sleeping for 20 milliseconds
Sleep(20)

PressKey

The PressKey() function is used to simulate a keyboard key press. NOTE: Calling IsModifierPressed or IsKeyLockOn immediately afterwards for a simulated modifier or lock key will likely return the previous state. It will take a few milliseconds for the operation to complete.

PressKey( scancode [,scancode] );
	
PressKey( keyname [,keyname] );

Parameters

Return Values

Remarks

Example

-- Simulate "a" pressed using the scancode
PressKey(30)
	
-- Simulate "a" pressed using the keyname
PressKey("a")
	
-- Simulate "a" and "b" being pressed
PressKey("a", "b")

ReleaseKey

The ReleaseKey() function is used to simulate a keyboard key release.

ReleaseKey( scancode [,scancode] );
	
ReleaseKey( keyname [,keyname] );

Parameters

Return Values

Remarks

Example

-- Simulate "a" released using the scancode
ReleaseKey(30)
	
-- Simulate "a" released using the keyname
ReleaseKey("a")
	
-- Simulate "a" and "b" being released
ReleaseKey("a", "b")

PressAndReleaseKey

The PressAndReleaseKey() function is used to simulate a keyboard key press followed by a release. NOTE: Calling IsModifierPressed or IsKeyLockOn immediately afterwards for a simulated modifier or lock key will likely return the previous state. It will take a few milliseconds for the operation to complete.

ReleaseKey( scancode [,scancode] );
	
ReleaseKey( keyname [,keyname] );

Parameters

Return Values

Remarks

Example

-- Simulate "a" pressed and released using the scancode
PressAndReleaseKey(30)
	
-- Simulate "a" pressed and released using the keyname
PressAndReleaseKey("a")
	
-- Simulate "a" and "b" being pressed and released
PressAndReleaseKey("a", "b")

IsModifierPressed

The IsModifierPressed() function is used to determine if a particular modifier key is currently in a pressed state.

boolean IsModifierPressed ( keyname );

Parameters

Return Values

Remarks

Example

-- Press a specific modifier
PressKey("lshift")
	
if IsModifierPressed("shift") then
	--shift is pressed
end
	
-- Release the key so it is no longer pressed
ReleaseKey("lshift")
	
if not IsModifierPressed("shift") then
	--shift is not pressed
end

PressMouseButton

The PressMouseButton() function is used to simulate a mouse button press. NOTE: Calling IsMouseButtonPressed immediately afterwards, will likely return the previous state. It will take a few milliseconds for the operation to complete.

PressMouseButton( button )

Parameters

Return Values

Remarks

Example

-- Simulate left mouse button press
PressMouseButton(1)
	
-- Simulate right mouse button press
PressMouseButton(3)

ReleaseMouseButton

The ReleaseMouseButton() function is used to simulate a mouse button release

ReleaseMouseButton( button )

Parameters

Return Values

Remarks

Example

-- Simulate a left mouse button click (press and release)
	
PressMouseButton(1)
ReleaseMouseButton(1)

PressAndReleaseMouseButton

The PressAndReleaseMouseButton() function is used to simulate a mouse button press followed by a release. NOTE: Calling IsMouseButtonPressed immediately afterwards, will likely return the previous state. It will take a few milliseconds for the operation to complete.

PressAndReleaseMouseButton( button )

Parameters

Return Values

Remarks

Example

-- Simulate a left mouse button click (press and release)
	
PressAndReleaseMouseButton(1)

IsMouseButtonPressed

The IsMouseButtonPressed() function is used to determine if a particular mouse button is currently in a pressed state.

boolean IsMouseButtonPressed( button )

Parameters

Return Values

Remarks

Example

-- Press a mouse button
PressMouseButton(1)
	
if IsMouseButtonPressed(1) then
	--Left mouse button is pressed
end
	
-- Release the button so it is no longer pressed
ReleaseMouseButton(1)
	
if not IsMouseButtonPressed(1) then
	--Left mouse button is not pressed

MoveMouseTo

The MoveMouseTo() function is used to move the mouse cursor to an absolute position on the screen.

MoveMouseTo( x, y, )

Parameters

Return Values

Remarks

Example

-- Move mouse to upper, left corner
MoveMouseTo(0, 0)
	
-- Move mouse to center of screen
MoveMouseTo(32767, 32767)
	
-- Move mouse to lower, right corner
MoveMouseTo(65535, 65535)

MoveMouseWheel

The MoveMouseWheel() function is used to simulate mouse wheel movement.

MoveMouseWheel( click )

Parameters

Return Values

Remarks

Example

-- Simulate mouse wheel 3 clicks up
MoveMouseWheel(3)
	
-- Simulate mouse wheel 1 click down
MoveMouseWheel(-1)

MoveMouseRelative

The MoveMouseRelative() function is used to simulate relative mouse movement.

MoveMouseRelative( x, y, )

Parameters

Return Values

Remarks

Example

-- Simulate relative mouse movement upwards in 1 pixel increments
for i = 0, 50 do
	MoveMouseRelative(0, -1)
	Sleep(8)
end

MoveMouseToVirtual

The MoveMouseToVirtual() function is used to move the mouse cursor to an absolute position on a multi-monitor screen layout.

MoveMouseToVirtual( x, y, )

Parameters

Return Values

Remarks

Example

-- Move mouse to upper, left corner of virtual desktop
MoveMouseToVirtual(0, 0)
	
-- Move mouse to center of virtual desktop
MoveMouseToVirtual (32767, 32767)
	
-- Move mouse to lower, right corner of virtual desktop
MoveMouseToVirtual (65535, 65535)

IsKeyLockOn

The IsKeyLockOn() function used to determine if a particular lock button is currently in an enabled state.

IsKeyLockOn( key )

Parameters

Return Values

Remarks

Example

-- Check if the numlock is on and turn it off if it is
if ( IsKeyLockOn("numlock" ) then
	PressAndReleaseKey("numlock");
end

EnablePrimaryMouseButtonEvents

EnablePrimaryMouseButtonEvents() enables event reporting for mouse button 1.

EnablePrimaryMouseButtonEvents(enable);

Parameters

Return Values

Remarks

Example

-- Enable event reporting for mouse button 1
EnablePrimaryMouseButtonEvents(true);
	
-- Disable event reporting for mouse button 1
EnablePrimaryMouseButtonEvents(false);

Standard Lua 5.1 Libraries

The following standard library functions are supported:

Appendix A

Table of scancodes and keynames used in PressKey(), ReleaseKey(), IsModifierPressed().

Keyboard Scancode