This section describes all the glu.* functions that can be used in a script after including this line:

local glu = glu()

The functions are listed alphabetically:

beep
check
continue
doevent
exit
filetypes
getcolor 		getdir
getevent
getfiles
getoption
getscale
getstring
getview 		help
makedir
millisecs
note
open
os
run 		save
savechanges
setcolor
setoption
settitle
setview
show 		sleep
update
warn

beep()
Play the system-specific alert sound.

Example: if error then glu.beep() end

check(bool)
When Glu runs a script this setting is initially true, which means that event checking is enabled. If the given parameter is false then event checking is disabled. Typically used to prevent partial canvas updates. This should only be done for short durations because the script cannot be aborted while the setting is false.

Example: glu.check(false)

continue(message)
This function can be used to continue execution after pcall has detected some sort of error or the user has aborted the script. It's typically used to ensure some finalization code is executed. If not empty, the given message will be displayed in a dialog box after the script has finished.

doevent(event)
Pass the given event to Glu to handle. The given event must be a string with the exact same format as returned by the getevent function. If the string is empty then Glu does nothing. Note that the cmd modifier corresponds to the command key on a Mac or the control key on Windows/Linux (this lets you write portable scripts that work on any platform).

Example: glu.doevent("key q cmd") -- quit Glu

exit(message="")
Exit the script with an optional error message. If a non-empty string is supplied then it will be displayed in a dialog box along with a beep.

Example: glu.exit("Oops.")

filetypes(suffix1, suffix2, ...)
The given list of strings specify which file types will be passed to your script via a "file" event (see the getevent function). To get all file types (including directories) you can call glu.filetypes("").

Example: glu.filetypes(".txt", ".html")

getcolor(name)
Return the current RGB values for the given color as 3 integers. Here is a list of all the valid color names and how they are used:

"statusbar" background color for status bar
"viewport" background color for viewport

Example: local vr,vg,vb = glu.getcolor("viewport")

getdir(dirname)
Return the path of the specified directory:

"app" — the directory containing the Glu application.

"current" — the current directory. When Glu runs a script it sets the current directory to the location of the script.

"data" — the user-specific data directory:
On Linux: ~/.glu/
On Mac: ~/Library/Application Support/Glu/
On Windows: C:\Users\username\AppData\Roaming\Glu\

"scripts" — the directory containing your scripts.

"temp" — the directory Glu uses to store temporary files.

In each case a full path is returned, terminated by the appropriate path separator for the current platform ("/" on Mac and Linux, "\" on Windows). To see the various paths on your system, run getdir.lua.

Example: local pathsep = glu.getdir("app"):sub(-1)

getevent()
When Glu runs a script, all user events are put into a queue for retrieval via getevent() calls. The events are returned in the form of strings (see below for the syntax). If there are no events in the queue then the returned string is empty. An easy way to see the various event strings is to run events.lua.

Key-down events are triggered when a key is pressed or autorepeats. The returned string is of the form "key keyname modifiers" where keyname can be any displayable ASCII character from ! to ~ (but only the lower case letters a to z are used), or one of the following names: space, home, end, pageup, pagedown, help, insert, delete, tab, return, left, right, up, down, or f1 to f24, or a modifier key: alt, cmd, ctrl, meta, shift. When a modifier key is pressed then modifiers is always none. For all other keys, if no modifier key was pressed then modifiers is none, otherwise it is some alphabetic concatenation of alt, cmd, ctrl, meta, shift. Note that cmd will only be returned on a Mac and corresponds to the command key. The alt modifier corresponds to the option key on a Mac.

Key-up events occur when a key is released and are strings of the form "kup keyname".

Mouse-down events in the viewport (including any transparent canvas pixels) are strings of the form "vclick x y button modifiers" where x and y are integers giving the viewport position of the click, button is one of left, middle or right, and modifiers is the same as above. The top left pixel in the viewport is (0,0) with x coordinates increasing from left to right and y coordinates increasing from top to bottom.

Mouse-down events in a non-transparent canvas pixel are strings of the form "cclick x y button modifiers" where x and y are integers giving the pixel position in the canvas, button is one of left, middle or right, and modifiers is the same as above. The top left pixel in the canvas is (0,0) with x coordinates increasing from left to right and y coordinates increasing from top to bottom.

Mouse-up events are strings of the form "mup button" where button is one of left, middle or right.

Mouse wheel events in the viewport (including any transparent canvas pixels) are strings of the form "vzoomin x y" or "vzoomout x y" where x and y are the mouse's pixel position in the viewport.

Mouse wheel events over a non-transparent canvas pixel are strings of the form "czoomin x y" or "czoomout x y" where x and y are the mouse's pixel position in the canvas.

File events are strings of the form "file filepath" where filepath is an absolute path. File events can be triggered by clicking an "open:" link in the Help window, or by dropping a file (or folder) onto the Glu window or the Glu application icon. A script will only get a file event if the file ends with one of the strings given in an earlier filetypes call.

The following examples show the strings returned after various user events:

"key m none" user pressed the M key
"key shift none" user pressed the shift key
"key m shift" user pressed shift-M
"key space none" user pressed space bar
"key , altctrlshift" user pressed comma and 3 modifier keys
"kup left" user released the left arrow key
"vclick 1 5 left none" user clicked viewport pixel at (1,5) with left button
"cclick 1 5 left none" user clicked canvas pixel at (1,5) with left button
"cclick 1 5 right alt" user clicked canvas with right button while pressing alt key
"mup left" user released the left button
"vzoomout 1 5" mouse wheel was used to zoom out from viewport pixel
"czoomin 1 5" mouse wheel was used to zoom in to canvas pixel
"file /path/to/foo.txt" user wants to open the given file

Example: local event = glu.getevent()

getfiles(dirpath)
Return the contents of the given directory as an array of strings, or nil if the directory doesn't exist. A non-absolute directory path is relative to the location of the script. File names are returned first, then subdirectory names. The latter names end with the platform-specific path separator ("/" on Mac and Linux, "\" on Windows).

Example: local myscripts = glu.getfiles(glu.getdir("scripts"))

getoption(name)
Return the current value of the given option. Here are the valid option names and their possible values:

"fullscreen" 1 or 0
"maximized" 1 or 0
"showstatusbar" 1 or 0

Example: if glu.getoption("fullscreen") == 1 then glu.setoption("showstatusbar",0) end

getscale()
Return 2.0 if running on a Mac with a Retina display, otherwise 1.0. This function should only be needed on rare occasions to fix scaling problems.

Example: if glu.getscale() > 1.0 then print("Retina display") end

getstring(prompt, initial="", title="")
Display a dialog box and get a string from the user. If the initial string is supplied it will be shown and selected. If the title string is supplied it will be used in the dialog's title bar. Returns nil if the user hits the dialog's Cancel button.

Example: local n = tonumber( glu.getstring("Enter a number:", "100") )

getview()
Return the pixel width and height of the viewport window.

Example: local wd, ht = glu.getview()

help(filepath)
Display the given HTML file in the help window.

Example: glu.help("help/index.html")

makedir(dirpath)
Create the given directory, or do nothing if it already exists. If necessary, each directory in the path will also be created. A non-absolute path is relative to the location of the script.

Example: glu.makedir(glu.getdir("data").."GameData")

millisecs()
Return the number of milliseconds that have elapsed since Glu started up. The returned value is a floating point number.

Example: local t1 = glu.millisecs()

note(message, showCancel=false)
Show the given string in a modal information dialog. Useful for displaying multi-line results. If showCancel is true then the dialog has a Cancel button as well as the usual OK button. Clicking OK will close the dialog and continue; clicking Cancel will close the dialog and abort the script.

Example: glu.note("Line 1\nLine 2\nLine 3")

open(title, filetypes, initialdir, initialfname, mustexist=true)
Present a standard Open dialog to the user and return the chosen path in a string. All parameters are optional; the default is an Open dialog showing the current directory, with a title of "Choose a file" and a file type of "All files (*)|*". If the 5th parameter (default = true) is set to false, the user can specify a new filename instead of choosing an existing file. If the given file type is "dir" then the dialog lets the user choose a directory rather than a file. If the user cancels the dialog, the return value will be an empty string.

Examples:
local filepath = glu.open()
local luapath = glu.open("Choose a Lua file", "Lua files (*.lua)|*.lua")
local dirpath = glu.open("Choose a folder", "dir");

os()
Return the current operating system: "Windows", "Mac" or "Linux".

Example: if glu.os() == "Mac" then DoMacStuff() end

run(filepath)
This function can only be called by startup.lua and is used to run the specified .lua file.

save(title, filetypes, initialdir, initialfname, suppressprompt=false)
Present a standard Save dialog to the user and return the chosen path in a string. All parameters are optional; the default is a Save dialog showing the current directory, with a title of "Choose a save location and filename" and a file type of "All files (*)|*". If a file already exists at the chosen location, an Overwrite? query will be displayed unless the 5th parameter (default = false) is set to true. If the user cancels the dialog, the return value will be an empty string.

Example: local fname = glu.save("Save text file", "Text files (*.txt)|*.txt")

savechanges(query, message)
Show a standard "save changes" dialog and return "yes", "no" or "cancel" depending on which button the user clicked.

Example: local answer = glu.savechanges("Save your changes?",
"If you don't save, the changes will be lost.")

setcolor(name, r, g, b)
Set the given color to the given RGB values (integers from 0 to 255). The old RGB values are returned as 3 integers to make it easy to restore the color. Here is a list of all the valid color names and how they are used:

"statusbar" background color for status bar
"viewport" background color for viewport

Example: local oldr,oldg,oldb = glu.setcolor("statusbar",255,255,255)

setoption(name, value)
Set the given option to the given value. The old value is returned to make it easy to restore a setting. Here are the valid option names and their possible values:

"fullscreen" 1 or 0
"maximized" 1 or 0
"showstatusbar" 1 or 0

Example: local oldbar = glu.setoption("showstatusbar",1)

Note that when a script ends, Glu automatically exits fullscreen mode, removes any status bar, and restores the window size and maximized state.

settitle(string)
Set the window title to the given string. The original title will be restored when the script terminates.

Example: glu.settitle("My Game")

setview(wd, ht)
Set the pixel width and height of the viewport window. The initial size of the viewport window is automatically restored when a script ends.

Example: glu.setview(800, 600)

show(message)
Show the given string in a status bar below the viewport. The status bar is automatically shown if necessary. Glu will automatically remove the status bar when the script ends.

Example: glu.show("Hit any key to continue...")

sleep(millisecs)
Sleep for the given number of millisecs. Scripts with an event loop can call this function to avoid hogging the CPU when the script is idle.

Example: glu.sleep(5)

update()
Immediately update the viewport (and the status bar, if visible). Note that Glu always does an update when a script finishes.

warn(message, showCancel=false)
Beep and show the given string in a modal warning dialog. Useful for debugging Lua scripts or displaying error messages. If showCancel is true then the dialog has a Cancel button as well as the usual OK button. Clicking OK will close the dialog and continue; clicking Cancel will close the dialog and abort the script.

Example: glu.warn("xxx = "..xxx, true)