eg-overlay

eg-overlay#

local overlay = require 'eg-overlay'

The eg-overlay module contains core functions that other modules use to communicate with the overlay.

Functions#

eg-overlay.time()#

Returns the factional number of seconds since the overlay was started.

Return type:: number

Example#

local overlay = require 'eg-overlay'
local now = overlay.time()

overlay.loginfo(string.format('The overlay has been running for %f seconds', now))

Version History

Version	Notes
0.3.0	Added

eg-overlay.logdebug(message)#

Logs a debug message to the log.

Note

Lua’s string.format can be used to format messages.

Example#

overlay.logdebug(string.format("Hello log: %d", 1234))

Parameters:: message (string) – The log message to display.

Version History

Version	Notes
0.3.0	Added

eg-overlay.loginfo(message)#

Logs an informational message to the log.

See also

See logdebug() for notes and example.

Parameters:: message (string) – The log message to display.

Version History

Version	Notes
0.3.0	Added

eg-overlay.logwarn(message)#

Logs a warning message to the log.

See also

See logdebug() for notes and example.

Parameters:: message (string) – The log message to display.

Version History

Version	Notes
0.3.0	Added

eg-overlay.logerror(message)#

Logs an error message to the log.

See also

See logdebug() for notes and example.

Parameters:: message (string) – The log message to display.

Version History

Version	Notes
0.3.0	Added

eg-overlay.addeventhandler(event, handler)#

Add an event handler for the given event name.

The handler function will be called every time the given event is posted with two arguments: the event name and event data. The data may be nil, any Lua data type.

Parameters:

event (string) – Event type
handler (function) – Function to be called on the given event

Returns:

A callback ID that can be used with removeeventhandler().

Return type:

integer

Example#

local overlay = require 'eg-overlay'

-- run on_update_once on only the first update event
local update_event_handler = 0

local function on_update_once(event, data)
    overlay.loginfo("Update event")
    overlay.removeeventhandler(update_event_handler)
end

update_event_handler = overlay.addeventhandler('update', on_update_once)

Version History

Version	Notes
0.3.0	Added

eg-overlay.removeeventhandler(event, cbi)#

Remove an event handler for the given event name. The callback ID is returned by addeventhandler().

Parameters:

event (string) – Event type
cbi (integer) – Callback ID

See also

See addeventhandler() for example.

Version History

Version	Notes
0.3.0	Added

eg-overlay.addkeybindhandler(keyname, handler)#

Add a keybind handler for the given key.

keyname is a name in the form of {mod1}-{mod2}-{key}, for example shift-a, ctrl-alt-e, or f. Individual modifier keys can be bound by specifying them directly, ie lctrl or alt-lctrl.

The handler function will be called every time the corresponding key is pressed.

If the handler function returns true, the key event will be consumed, it will not be sent to other handlers or to GW2.

Danger

The handler will be run on the event thread. Any blocking or long running tasks in the handler will adversely affect input in the entire system.

Since this function must return a value, and due to the above, coroutine.yield is not allowed and will result in an error.

Parameters:

keyname (string)
handler (function) – A function with the following signature function handler(keyname) end.

Return type:

integer

Returns:

An ID that can be used with removekeybindhandler() to remove the keybind.

Example#

local overlay = require 'eg-overlay'

local function onkey()
    -- do things

    return true
end

-- run onkey everytime ctrl-shift-e is pressed, consuming the event
overlay.addkeybindhandler('ctrl-shift-e', onkey)

Version History

Version	Notes
0.3.0	Added

eg-overlay.removekeybindhandler(keyname, cbi)#

Remove a keybind handler for the given key name. The callback ID is returned by addkeybindhandler().

Parameters:

keyname (string)
cbi (integer)

Version History

Version	Notes
0.3.0	Added

eg-overlay.settings(name)#

Create a settingsstore named name.

This function should be used by modules to create a settings store.

See also

The settingsstore class.

Parameters:: name (string) – The name of the settings store, typically the name of the module.
Return type:: settingsstore

Version History

Version	Notes
0.3.0	Added

eg-overlay.memusage()#

Returns a table containing the overlay’s system memory usage.

This usage is for the application as a whole, not just Lua. A table is returned with the following fields:

Field	Description
workingset	The current memory allocated to the overlay, including shared objects (libraries), in bytes.
peakworkingset	The maximum amount of memory the overlay has been allocated since starting including shared objects, in bytes.
privateworkingset	The current memory allocated to the overlay, excluding shared objects, in bytes. This is representative to the overlay’s private memory and is what the ‘Task Manager’ will display.

Field

Description

workingset

The current memory allocated to the overlay, including shared objects (libraries), in bytes.

peakworkingset

The maximum amount of memory the overlay has been allocated since starting including shared objects, in bytes.

privateworkingset

The current memory allocated to the overlay, excluding shared objects, in bytes.

This is representative to the overlay’s private memory and is what the ‘Task Manager’ will display.

Return type:: table

Example#

local overlay = require 'eg-overlay'

local mem = overlay.memusage()

overlay.loginfo(string.format('The overlay is using %.2f MiB of memory.', mem.workingset / 1024.0 / 1024.0))

Version History

Version	Notes
0.3.0	Added

eg-overlay.videomemusage()#

Returns the overlay’s video memory usage, in bytes.

Return type:: integer

Example#

local overlay = require 'eg-overlay'

local gpumem = overlay.videomemusage()

overlay.loginfo(string.format('Overlay GPU memory: %2.f MiB', gpumem / 1024.0 / 1024.0))

Version History

Version	Notes
0.3.0	Added

eg-overlay.processtime()#

Returns a table containing the CPU time and uptime of the overlay process.

This can be used to calculate the overlay’s CPU usage. The table has the fields described below:

Field	Description
processtimetotal	The total time the overlay has been running.
usertime	The total time spent executing code within the overlay.
kerneltime	The total time spent executing system code for the overlay, not including idle time.
systemusertime	The total time spent executing all application code on the system.
systemkerneltime	The total time spent executing system code on the system including idle time.

Return type:: table

Version History

Version	Notes
0.3.0	Added

eg-overlay.queueevent(event[, data])#

Add a new event to the event queue.

Note

Events added with this function will be run before the next frame is rendered.

Warning

Module authors should take care to use unique event names. It is possible to queue any event with this function, however if proper data is not supplied event handlers may behave in unexpected ways.

Parameters:

event (string) – Event name
data – (Optional) Event data. This can be any Lua value.

Example#

local overlay = require 'eg-overlay'

local eventdata = {
    foo = 'bar',
    baz = true,
}

overlay.queueevent('my-module-event', eventdata)

Version History

Version	Notes
0.3.0	Added

eg-overlay.datafolder(name)#

Returns the full path to the data folder for the given module.

Modules should store any data other than settings in this folder. The folder will be created by this function if it does not already exist.

Parameters:: name (string) – The name of the module and corresponding folder.
Return type:: string

Example#

local overlay = require 'eg-overlay'

local modulefolder = overlay.datafolder('my-module')

local f = io.open(modulefolder .. '/data.txt')

Version History

Version	Notes
0.3.0	Added

eg-overlay.overlaysettings()#

Return the settingsstore for the overlay.

This contains core settings for the overlay and UI.

Return type:: settingsstore

Version History

Version	Notes
0.3.0	Added

eg-overlay.restart()#

Restart the overlay.

Danger

This will shut down the overlay and restart it immediately.

Version History

Version	Notes
0.3.0	Added

eg-overlay.versionstring()#

Returns a string containing the EG-Overlay version.

For example: "0.3.0-dev".

Return type:: string

Version History

Version	Notes
0.3.0	Added

eg-overlay.clipboardtext([text])#

Set or return the text on the clipboard.

Parameters:: text (string) – (Optional)

Example#

local overlay = require 'eg-overlay'

-- get the text from the clipboard
local t = overlay.clipboardtext()

overlay.loginfo(string.format("Got text from clipboard: %s", t))

-- set the text on the clipboard
overlay.clipboardtext("Hello world from EG-Overlay!")

Version History

Version	Notes
0.3.0	Added

eg-overlay.sqlite3open(db)#

Open or create a SQLite3 database.

See also

The sqlite3db class.

Parameters:: db (string) – The SQLite3 database path or connection string.
Return type:: sqlite3db

Example#

local overlay = require 'eg-overlay'

local db = overlay.open('some-data.db')

Version History

Version	Notes

eg-overlay.webrequest(url, headers, query_params, callback)#

Queue a web request to the given URL.

Requests are completed asynchronously, with the results provided to callback.

Parameters:

url (string) – The full URL. Query parameters can be excluded if they are supplied in query_params.
headers (table) – A list of headers to add to the request.
query_params (table) – A list of query parameters to add to the URL.
callback (function) – A function that will be called when the request is completed. This function will be called with 3 arguments: the response body or nil if the request failed, the HTTP status code, and a table containing the response headers.

Note

Web requests are currently assumed to be HTTP(S).

Warning

Do not mix query_params with parameters supplied in url. This function does not check if url already contains parameters, it simply appends query_params if it contains values.

Important

All web requests are logged, with the path to the Lua source and line number of the webrequest call.

The author of EG-Overlay believes that users should be able to easily understand when and where web requests are sent.

Example#

local overlay = require 'eg-overlay'

local function on_response(body, code, hdrs)
    overlay.loginfo(string.format('Got %d response from server.', code))
    if body then
        overlay.loginfo(string.format('Response body:\n%s', body))
    end
end

local request_headers = {}
request_headers['X-Special-Header'] = 'SomeValue'

local params = {}
params['query_param'] = 1

overlay.webrequest('https://some.url/path/etc', request_headers, params, on_response)

Version History

Version	Notes
0.3.0	Added

eg-overlay.parsejson(JSON)#

Parse a JSON string into a Lua value.

This function returns nil if the string can not be parsed.

Parameters:: JSON (string)

Example#

local overlay = require 'eg-overlay'

-- objects are parsed into tables
local obj = overlay.parsejson('{"test": 1234}')
overlay.loginfo(string.format("test: %d", obj.test))

-- arrays are parsed into sequences
local arr = overlay.parsejson('["hello world", 1234]')
for i,val in ipairs(arr) do
    overlay.loginfo(string.format("%d: %s", i, val))
end

Version History

Version	Notes
0.3.0	Added

eg-overlay.openzip(path)#

Open the zip file at the given path and return a zipfile.

See also

The zipfile class.

Note

If an error occurs while opening/reading the zip file, this function will log an error and return nil.

Return type:: zipfile

Version History

Version	Notes
0.3.0	Added

eg-overlay.parsexml(xml, eventcallback)#

Attempt to parse the given XML string in an event driven manner (i.e. SAX).

eventcallback will be called on each event, corresponding to various elements of the XML document. eventcallback will be called with 2 arguments: the name of the event and the event data (see below).

This function will only return once the document is fully parsed, returning true on success and false on any failure.

Note

Raising an error during the callback will cause parsing to fail and this function to return false.

Parameters:

xml (string)
eventcallback (function)

Return type:

boolean

Event Types

Event Name	Event Data
start-document	`nil`
end-document	`nil`
start-element	A Lua table. See below for fields.
end-element	A Lua table containing the following fields: `local_name`: the element name without prefixes or namespaces `namespace`: the element name namespace `prefix`: the element name prefix
cdata	A string containing the CDATA.
comment	A string containing the comment.
characters	A string containing the text.
whitespace	A string containing whitespace characters.

start-element data fields:

Field	Description
name	A Lua table containing the following fields: `local_name`: the element name without prefixes or namespaces `namespace`: the element name namespace `prefix`: the element name prefix
attributes	A Lua sequence of tables for each attribute, each with `name` and `value` fields

Field

Description

name

A Lua table containing the following fields:

local_name: the element name without prefixes or namespaces
namespace: the element name namespace
prefix: the element name prefix

attributes

A Lua sequence of tables for each attribute, each with name and value fields

Version History

Version	Notes
0.3.0	Added

Events#

startup#

The startup event is sent once before the start of the render thread. Modules can use this event to initialize or load data.

Version History

Version	Notes
0.3.0	Added

update#

Sent once per frame before any drawing has occurred.

Version History

Version	Notes
0.3.0	Added

eg-overlay

Contents

eg-overlay#

Functions#

Events#