Library

cocoaAvailable

This variable is true if LuaCoco was compiled into MicroMacro, otherwise it will be false. If LuaCoco is available, then MicroMacro can take advantage of true multi-threaded co-routines, allowing it to yield across C boundaries.

Example

if( cocoAvailable ) then
  -- Coco is available! we can yield across C boundaries!
  coroutine.yield();
end

startKey

This variable contains the virtual key for the key that starts the macro. Only applicable when using startMacro().

By default, this variable contains key.VK_F5, however, you can remap it to any key you want. You should not use the same key for both starting and stopping the macro.

See Virtual Keys for more information.

Example

startKey = key.VK_F9; -- Now the key to start the macro is F9

stopKey

This variable contains the virtual key for the key that stops the macro. Only applicable when using startMacro().

By default, this variable contains key.VK_F6, however, you can remap it to any key you want. You should not use the same key for both starting and stopping the macro.

See Virtual Keys for more information.

Example

stopKey = key.VK_F10; -- Now the key to stop the macro is F10

include

include(scriptname)

Includes (runs) whatever script is supplied. script should be of type string, and include a relative path from MicroMacro's base directory (that means you will probably always want to precede it with "scripts/"). This is prefered over Lua's dofile(), as it will correct path issues.

Example

include("scripts/myscript.lua");

registerTimer

registerTimer(name, time, func)

registerTimer() is a shortcut to the timer functions. 'name' should be a string which you will name the timer; 'time' should be a value in miliseconds (1/1000th of a second); 'func' should be the name of the function you wish to run at the specified time interval.

registerTimer() automatically creates, starts, and restarts the timer when needed.

Please note that you MUST make use of coroutine.yield() or yrest() in your main loop, otherwise the automatic timer related code will not get time to process.

Example

function some_function()
  print("hello!");
end


registerTimer("myTimer", 1000, some_function);
-- some_function() will now automatically be called every one second.

unregisterTimer

unregisterTimer(name)

Removes a timer that has been registered with registerTimer(). It will no longer be called automatically, and must be re-created or re-registered in order to use it again.

Example

unregisterTimer("myTimer");
-- myTimer will no longer be called automatically.

startMacro

startMacro(func, runstate) startMacro(func)

Starts the macro function as a coroutine. This is used to fake multi-threading so that you do not have to check for the start/stop keys, and manage registered timers. Specifying runstate is optional. If runstate is true, you will not be prompted to press the start key to start executing the script. The variable runstate is false by default.

Remember to use coroutine.yield() or yrest() within any while or for loops to give startMacro() a chance to process information.

Example

function MyMacro()
  print("This is my macro!");
end

startMacro(MyMacro);

yrest

yrest(time)

yrest(), or "yield rest", causes the script to pause for 'time' miliseconds, and automatically calls coroutine.yield() for you at 100ms intervals. It has no advantage over rest() if 'time' is less than 100 miliseconds.

Example

yrest(1000); -- rest for 1 second, and allow coroutines to run.

stopPE

stopPE()

This function will stop the protected environment, similar to when you press the stop key . Only applicable when using startMacro().

If LuaCoco is available, then stopPE() will automatically call coroutine.yield() for you. Otherwise, you will need to call coroutine.yield() yourself at an appropriate time to allow MicroMacro time to catch the stop message.

Example

if( error_has_occured ) then
  print("Some minor error has occured! Press F5 to continue anyways. ");
  stopPE();
end

printf

printf(format, ...)

printf() is a C-style glue for MicroMacro. This function will output the result to the screen. Use sprintf() if you just want to format, but not output. Many of us prefer printf-style formatting to Lua's for a number of reasons. 'format' should be of type string and use special tokens to denote data types. The most typically used tokens are:

%s	string
%d	integer (non-floating point)
%f	floating-point integer
%x	output as hexadecimal
\n	new line
\t	tab
\a	system beep

Example

printf("Hello %s! My favorite number is %d, and PI is %f\n", "World", 12, 3.1415);
-- Outputs: Hello World! My favorite number is 12, and PI is 3.1415

sprintf

string sprintf(format, ...)

See printf(). This function returns the formatted string rather than printing it to the screen.

Example

formatted = sprintf("Hello %s.", "world");
print(formatted);

hoursToTimer

int hoursToTimer(hours)

Converts a time in hours to miliseconds for use in timers. Decimals are accepted. The returned value is rounded down in the chance that the result is not a whole number.

Example

registerTimer("MyTimer", hoursToTimer(0.5), MyTimer);
-- MyTimer() will be called every half hour.

minutesToTimer

int minutesToTimer(minutes)

Converts a time in minutes to miliseconds for use in timers. Decimals are accepted. The returned value is rounded down in the chance that the result is not a whole number.

See hoursToTimer().

secondsToTimer

int secondsToTimer(seconds)

Converts a time in seconds to miliseconds for use in timers. Decimals are accepted. The returned value is rounded down in the chance that the result is not a whole number.

See hoursToTimer().

atExit

atExit(function)

Sets a callback function which is called when the current script terminates. The callback function may not be called if an error occures, or MicroMacro's process terminated. That is, if you click the close button on MicroMacro's window, it will not be called. You should use CTRL + L to end the scripts properly. Pausing (pressing the stop key) does not call trigger this, as the script does not terminate.

Example

function exit_callback()
  printf("This is an example callback.\n");
end
atExit( exit_callback );

colorMatch

bool colorMatch(color1, color2)

bool colorMatch(color1, color2, accuracy)

Returns true if color1 matches color2 within given accuracy, or false if they do not match. The higher 'accuracy' is, the less the two colors channels need to be alike in order to generate a match. If accuracy is not given, 0 (exact match) is assumed. 'accuracy' must be between 0 and 255 if supplied.

Example

white = makeColor(255, 255, 255);
gray = makeColor(225, 225, 225);
black = makeColor(0, 0, 0);

match = colorMatch(white, gray);      -- returns false
match = colorMatch(white, gray, 50);  -- returns true
match = colorMatch(gray, black, 50);  -- returns false
match = colorMatch(white, black);     -- returns false
match = colorMatch(white, black, 50); -- returns false

fileExists

bool fileExists(filename)

Returns true if the given file exists and is accessible. Otherwise, returns false.

Example

local fe = fileExists(getPath() .. "/scripts/myScript.lua");
if( fe == false ) then
  printf("The file does not exist or is inaccessible.\n");
end