OneOS API Documentation

If you are going to modify any part of OneOS you MUST set isDebug to true in the startup folder. Otherwise I'll be bombarded with error reports that have nothing to do with me.

Overview

OneOS has an API that is automatically loaded in to every program when being run as a OneOS program. It allows you to do things such as change the title bar colours, access the global file system, close the program and shutdown the computer (which is sandboxed by default).

How OneOS Programs Run

While not essential, it's probably best to understand how programs are run in OneOS and the sandboxed environment they run in. If you don't need to know or already know, skip to the next section.

Every program is run in it's own environment, you can't access other programs, the global file system or control the computer by default. When you call a function such as os.shutdown the program is terminated, but the computer does not shutdown. In the case of the file system, to prevent programs breaking using fs.open('/important_file', 'r') will open a file within the program's bundle. The program's bundle is the folder in which the icon, startup and other files live. Any temporary, settings or simliar files should go within this folder, so use fs.open. However, if you want to access, for example, the Documents folder you need to use the OneOS.FS API (described below).

When using any of the OneOS APIs always wrap an if statement, such as the one below, around the call to prevent crashes on non-OneOS systems

if OneOS then
	fs = OneOS.FS
end

API Functions/Variables

Note: In OneOS the British version of colour is always used (not color)!

• ToolBarColour
• ToolBarTextColour
• OpenFile
• Helpers
• Settings
• Version
• Reboot (alias: Restart)
• Shutdown
• Clipboard
• FS
• OSRun
• Shell
• ProgramLocation
• CanClose
• Close
• Run
• LoadAPI
• LoadFile
• IO

Each function/variable has it's own section below.

All paths in the OneOS API (unless noted) are global paths, not program relative paths!

ToolBarColour

Changes the background colour of the tool (menu/active programs) bar. Place this at the very top of your program.

Usage:

if OneOS then
	OneOS.ToolBarColour = colours.grey
end

Programs that use this: Files, Sketch, LuaIDE, Shell & more.

ToolBarTextColour

Changes the text colour of the tool (menu/active programs) bar. Place this at the very top of your program.

Usage:

if OneOS then
	OneOS.ToolBarTextColour = colours.white
end

Programs that use this: Files, Sketch, LuaIDE, Shell & more.

OpenFile

Opens the file or shortcut at a given path in the default editor/viewer. If the path is a program the program will be launched. There is an optional second parameter which allows you to pass arguments (as a table) if the file is a program.

Usage:

if OneOS then
	OneOS.OpenFile('/License')
end

Programs that use this: Files & About OneOS.

Helpers

A general library of helper functions, these are heavily used by OneOS. A few of the functions are implimented natively in the OneOS API.

Usage:

Open /System/API/Helpers.lua to view the available functions.

Programs that use this: OneOS Core.

Settings

Allows you to read and write system settings such as the desktop colour.

Current settings:

• ComputerName (string)
• DesktopColour (colour)
• UseAnimations (boolean)

Usage:

if OneOS then
	OneOS.Settings.SetValue('DesktopColour', colours.red)
	OneOS.Settings.GetValues('UseAnimations')
end

Open /System/API/Settings.lua for more information.

Programs that use this: Settings.

Version

Returns the version of OneOS (e.g. v1.0.0).

Usage:

if OneOS then
	print(OneOS.Version)
end

Programs that use this: About OneOS.

Reboot (or Restart)

Reboots the computer. If there are programs open the are refusing to close a window will ask the user if they want to continue.

Usage:

if OneOS then
	OneOS.Reboot()
end

Programs that use this: Update OneOS.

Shutdown

Shuts the computer down. If there are programs open the are refusing to close a window will ask the user if they want to continue.

Usage:

if OneOS then
	OneOS.Shutdown()
end

Clipboard

A global clipboard API. The clipboard data IS shared amongst other programs allowing the user to copy data between programs.

Usage:

if OneOS then
	OneOS.Clipboard.Empty()
	OneOS.Clipboard.isEmpty()
	OneOS.Clipboard.Copy(clipboardData, 'datatype') //leaving data type blank will set it to 'generic'
	OneOS.Clipboard.Type //(string) use this to check the data type before pasting
	OneOS.Clipboard.Paste()
end

Open /System/API/Clipboard.lua for more information.

Programs that use this: Files, Sketch.

FS

Allows you to access the global file system. Acts identically to normal fs API.

Usage:

if OneOS then
	_fs = OneOS.FS
	_fs.open('.version', 'r')
	_fs.read()
	_fs.close()
end

If all your files are in the global file system then place this at the top of your code:

if OneOS then
	fs = OneOS.FS
end

Programs that use this: App Store, LuaIDE, Shell, Sketch, Transmit, Files & more.

OSRun

A global version of os.run. If you need to use os.run on a global file, this is for you. Otherwise just use os.run.

Usage:

if OneOS then
	OneOS.OSRun(getfenv(), '/System/main.lua')
end

Shell

A global version of the shell API. If you need to use shell on a global file, this is for you. Otherwise just use shell.

Usage:

if OneOS then
	shell.run('clear')
end

ProgramLocation

Returns the global path of your program.

Usage:

if OneOS then
	OneOS.ProgramLocation
end

CanClose

Allows you to block your program from being closed (for unedited work, etc). This is called everytime the user tries to close the program.

To prevent closing:

--put this at the top of your code (before your main function)
if OneOS then
	OneOS.CanClose = function()
		if modified then
			return false
		else
			return true
		end
	end
end

If all your files are in the global file system then place this at the top of your code:

if OneOS then
	fs = OneOS.FS
end

Programs that use this: Sketch

Close

Closes your program, will not call CanClose.

Usage:

if OneOS then
	OneOS.Close()
end

Programs that use this: App Store, Sketch, Transmit, Unpackager

Run

Runs a program at the given path. Allows you to pass arguments as extra parameters

Usage:

if OneOS then
	OneOS.Run('/exampleprogram', 'arg1', 'arg2')
end

Programs that use this: Files

LoadAPI

A global version of os.loadAPI. If you need to use os.loadAPI on a global file, this is for you. Otherwise just use os.loadAPI.

Usage:

if OneOS then
	OneOS.LoadAPI('/System/API/Drawing.lua')
end

Programs that use this: Files, Transmit, About OneOS, Settings & more

LoadFile

A global version of loadfile. If you need to use loadfile on a global file, this is for you. Otherwise just use loadfile.

Usage:

if OneOS then
	OneOS.LoadFile('/System/API/Drawing.lua')
end

Programs that use this: LuaIDE, Shell, Unpackager & more

IO

A global version of the io API. If you need to use io on a global file, this is for you. Otherwise just use io.

Usage:

if OneOS then
	local f = OneOS.IO.open('/myfile', "r")
end

If all your files are global use this:

if OneOS then
	io = OneOS.IO
end

Programs that use this: LuaIDE, Sketch, Shell

RequestRunAtStartup

Asks the user if they'd like to run your program at startup. This is run asynchronously, you will not know when what the click. They can select 'Never Ask', so they will not always see the window.

Usage:

if OneOS then
	OneOS.RequestRunAtStartup()
end

*Programs that use this: Ultimate Door Lock

DoesRunAtStartup

Returns true if your program will run at startup.

Usage:

if OneOS and OneOS.DoesRunAtStartup() then
        --Runs at startup
end

*Programs that use this: Ultimate Door Lock