Lua Scripting

Information

WinWM contains an embedded Lua Engine, (LuaJIT-2.0.5), that allows for scripting for customization & interop purposes, it also has callbacks on certain actions to notify your scripts of certain events.

The Lua Environment provided by WinWM exports these libraries by default.

base
bit32
coroutine
debug
ffi
io
jit
math
os
package
string
table
utf8

Setup

In order to turn on Lua Scripting, the option "lua_script_path" has to be set, the value of this option by default is "", an example value for this option would be path like so

"C:\\Users\\Admin\\my_lua_script.lua" - Absolute Path
"lua/my_lua_script" - Relative Path (Relative to the folder where WinWM.exe is located)

Callbacks

WinWM provides several callback such as

on_new_window(window_handle)
on_destroy_window(window_handle)
on_fullscreen(is_fullscreen, window_handle)
on_change_workspace(workspace_number)
on_exit()

If you have/want more callbacks, feel free to send me ideas

Here is an example lua script

Working With External Libs

external modules that are used in the lua scripts have to be in the same path as the WinWM.exe.

For Example.

local winapi = require 'LuaModules.winapi'
require 'LuaModules.MyOtherScript'
require 'LuaModules.winapi.windowclass'

In order to access these external modules the file structure would have to look like this

- WinWM.exe
- LuaModules <DIR>
	- winapi <DIR>
		windowclass.lua
	- MyOtherScript.lua

Example Logger script

Just as an example on how this all works together, I'll guide you on creating a little logger script, that logs all activies and records the name of every window on every event.

I'll be using winapi which requires 2 other modules

The folder structure is as such :

- WinWM.exe
- modules <DIR>
	- winapi <DIR>
	- winapi.lua
	- glua.lua
	- events.lua

my logger script looks like this

logger.lua


require 'io'

package.path = package.path .. ';./modules/?.lua'; -- Include modules in path.
local window = require 'modules.winapi'
require 'modules.winapi.window'



FileHandle = io.open("C:\\Users\\Admin\\lua.txt", "a")
io.output(FileHandle)

function on_change_workspace(number)
	io.write("wk : ", number, '\n')
end

function on_new_window(hwnd)
	window_text = window.GetWindowText(hwnd)
	io.write('on_new_window: ', window_text, '\n')
end


function on_destroy_window(hwnd)
	window_text = window.GetWindowText(hwnd)
	io.write('on_destroy_window: ', window_text, '\n')
end

function on_fullscreen(IsFullScreen, hwnd)
	window_text = window.GetWindowText(hwnd)
	io.write('on_fullscreen: ', IsFullScreen,' ', window_text, '\n')
end

function on_exit()
	io.close(FileHandle)
end

lua.txt

wk : 2
wk : 1
wk : 2
wk : 3
wk : 4
wk : 1
wk : 3
on_fullscreen: 1 lua.md + (~\Desktop\Tech\WinWMBook\src) - GVIM1
on_fullscreen: 0 lua.md + (~\De...k\src) - GVIM1
wk : 4
on_fullscreen: 1 config.json (~\source\repos\REDACTED) - GVIM2
on_fullscreen: 0 config.json (~\source\repos\REDACTED) - GVIM2
wk : 1
wk : 2
wk : 3
wk : 4
on_new_window: Administrator: C:\Windows\system32\cmd.exe
on_destroy_window: 
wk : 1
on_fullscreen: 1 #my-channel - Google Chrome
on_fullscreen: 0 #my-channel - Google Chrome
on_fullscreen: 1 #my-channel - Google Chrome
on_fullscreen: 0 #my-channel - Google Chrome

Warning

If there is an error in the lua code, a message box should prompt with the error and backtrace. There are many bugs in luajit that will crash it, which will crash WinWM. If you encounter a line of lua code that crashes WinWM, then it is Luajit crashing.

Example :

require 'io'
io.open('crash.txt', 'crash') -- crashes Luajit and WinWM

WinWM Documentation