Simpletask for Android

Scripting with Lua
Login

Simpletask embeds a Lua scripting engine that can be used for configuration and callbacks. The configuration is read whenever you restart the app or when you change it in the Lua Config screen. The callbacks are executed when certain events occur (such as filtering). Both the configuration and callbacks will call specific Lua functions, see below for the details of the supported callbacks.

All code (config and callbacks) will be executed in the same Lua interpreter. This way you can define helper functions in the config and use them in callbacks.

NB: The filtering callback has been changed from pre 8.0 versions (See below).

To change existing (app and widget) filters to the 8.0 format do the following.

Add function onFilter(t,f,e) before and end after the existing script. Prefix all fields with f. i.e. due -> f.due. Example:

if due~=nil then
    return os.time() >= due;
end
--- tasks with no due date are not overdue.
return false;

becomes

function onFilter(t,f,e)
    if f.due~=nil then
        return os.time() >= f.due;
    end
    --- tasks with no due date are not overdue.
    return false;
end

Helper functions

toast (string) -> nil

Shows string as an Android toast. Useful for debugging scripts.

Notes

Don't use toasts inside functions. This is a good way to make Simpletask hang.

Callbacks

onFilter (task, fields, extensions) -> boolean

Called for every task as part of filtering the todo list.

Parameters

Returns

Notes

onGroup (task, fields, extensions) -> string

Called for every task as part of filtering the todo list.

Parameters

Returns

Notes

onTextSearch (taskText, caseSensitive) -> boolean

Called for every task as when searching for text.

Parameters

Returns

Notes

Configuration

Configuration is read on app start and whenever it is changed or ran from the Lua Config screen. Configuration from Lua will always override the value from the settings (Lua wins).

theme () -> string

Parameters

None

Returns

Notes

tasklistTextSize () -> float

Parameters

None

Returns

The font size of the main task list in SP as a float.

Notes

Examples

The following code will show only overdue tasks where tasks without a due date, will never be overdue.

function onFilter(t,f,e)
   if f.due~=nil then
       return os.time() > f.due;
   end
   --- tasks with no due date are not overdue.
   return false;
end

Show tasks without tags or lists (the GTD Inbox):

function onFilter(t,f,e)
   return next(f.tags)==nil and next(f.lists)==nil
end

Show all tasks with the @errands tag:

function onFilter(t,f,e)
   return f.tags["@errands"]
end

Change the font size of the main task list to 16sp:

function tasklistTextSize()
   return 16.0
end

The 8.0.0 fuzzy search in Lua:

function onTextSearch(text, search, case)
    pat = string.gsub(search, ".", "%0.*")
    res = string.match(text, pat)
    return res~=nil
end

A group callback to group by list with custom empty header:

function onGroup(t,f,e)
    if not next(f.lists) then
        return "Inbox"
    else
        return next(f.lists)
    end
end

Don't group at all and don't show any headers (regardless of sort order)

function onGroup()
    return ""
end

Learning Lua

Googling should turn up plenty of good resources. Programming in Lua should cover almost everything.