Term

From ComputerCraft
(Redirected from Terminal)
Jump to: navigation, search

A term (short for terminal) is a standardised data structure in ComputerCraft. It describes anything that can be drawn to, e.g. the screen of a Computer, a Window, or an Advanced Monitor. All term objects must implement the same functions, but can also add their own.

Term functions

These functions are shared by all term objects.

FunctionFunctionterm.blit
Writes text at the current cursor position in the current term, using foreground colors from textColour (a string containing colors as used in images loadable by paintutils functions) and background colors from backgroundColour (same as textColour). All characters represent a single hexadecimal digit which is then plugged into the equation c=2^(h-1) where h is the hexadecimal plugged in and c is a the equivalent color that would be plugged into term.setTextColor.
Syntax term.blit()
Returns nil
Part of CC:Tweaked (source)
API term
ExampleExamplePrint rainbow text
Prints "Hello world!" in 11-color text.
Code
term.blit("Hello world!","01234456789a","f00000000000")
Output Hello world!


FunctionFunctionterm.clear
Clears the terminal object using the current background colour. The term's cursor position, text colour and background colour states remain unchanged.
Syntax term.clear()
Returns nil
Part of CC:Tweaked (source)
API term
ExampleExampleClear a terminal
Clears the current term.
Code
print("Hello, world!")
sleep(1)
term.clear()
Output Hello, world! is printed, and then disappears after 1 second.
ExampleExampleClear a terminal with a colour
Clears the current term with a red background colour.
Code
term.setBackgroundColour(colours.red)
term.clear()
Output The screen is cleared and filled with red.


FunctionFunctionterm.clearLine
Clears the line on a terminal object using the current Y cursor position and background colour. The term's cursor position, text colour and background colour states remain unchanged.
Syntax term.clearLine()
Returns nil
Part of CC:Tweaked (source)
API term
ExampleExampleClear a line
Writes a line, waits, and then clears it.
Code
write("Hello, world!")
term.clearLine()
Output Hello, world! is printed, and then disappears after 1 second.
ExampleExampleClear a specific line with a colour
Clears the top line of the current term with a red colour.
Code
term.setBackgroundColour(colours.red)
term.setCursorPos(1, 1)
term.clearLine()
Output The top line of the screen is cleared and filled with red.
ExampleExampleClear many lines with different colours
Draws a line which each colour to the screen, clearing everything between.
Code
for i = 1, 16 do -- There are 16 colours.
  -- Colours in CC are a bitfield, so raising two to the power of n will give the nth colour.
  -- See [[Colours]] for more information.
  local colour = math.pow(2, i - 1) -- Subtract 1 as colours start from 0
  term.setBackgroundColour(colour)
  term.setCursorPos(1, i)
  term.clearLine()
end
Output Demo term.clearLine multiple.png


FunctionFunctionterm.getBackgroundColour
Returns the numerical value of the current background colour of the terminal object.
Syntax term.getBackgroundColour()
Returns number colour
Part of CC:Tweaked (source)
API term
ExampleExampleGet background colour
Prints the numerical value of the current term's background colour.
Code
print(term.getBackgroundColour())
Output
32768
ExampleExampleGet background colour name
Gets the current term's background colour, and then matches it against a lookup table to get its name.
Code
local lookup = { 
    [1] = "white", [2] = "orange", [4] = "magenta", [8] = "lightBlue", 
    [16] = "yellow", [32] = "lime", [64] = "pink", [128] = "gray", 
    [256] = "lightGray",  [512] = "cyan", [1024] = "purple", [2048] = "blue", 
    [4096] = "brown",  [8192] = "green", [16384] = "red", [32768] = "black" 
}
local colour = term.getBackgroundColour()
print(lookup[colour])
Output
black


FunctionFunctionterm.getCursorPos
Returns the current X and Y position of the cursor of the terminal object.
Syntax term.getCursorPos()
Returns number x, number y
Part of CC:Tweaked (source)
API term
ExampleExampleGet cursor pos
Prints the cursor position of the current term.
Code
local x, y = term.getCursorPos()
print(x, y)
Output
1, 3


FunctionFunctionterm.getPaletteColour
Returns the RGB values (0–1) of the specified palette colour of the terminal object.
Syntax term.getPaletteColour()
Returns number red, number green, number blue
Part of CC:Tweaked (source)
API term
ExampleExampleGet specific palette colour
Prints the decimal RGB value of the colour red in the current term's palette.
Code
local red, green, blue = term.getPaletteColour(colours.red)
print(red, green, blue)
Output 0.80000001192093 0.29803922772408 0.29803922772408 (equivalent to #cc4c4c)
ExampleExampleGet current palette colour
Prints the decimal RGB value of the current term's text colour.
Code
local colour = term.getTextColour()
local red, green, blue = term.getPaletteColour(colour)
print(red, green, blue)
Output 0.94117647409439 0.94117647409439 0.94117647409439 (equivalent to #f0f0f0)


FunctionFunctionterm.getSize
Returns the width and height (in characters) of the terminal object.
Standard terminal sizes
Device Width Height
Computer 51 19
Turtle 39 13
Pocket Computer 26 20
Neural Interface 39 13
Syntax term.getSize()
Returns number width, number height
Part of CC:Tweaked (source)
API term
ExampleExampleGet term size
Prints the width and height of the current term.
Code
local width, height = term.getSize()
print(width, height)
Output On computers, 51 19


FunctionFunctionterm.getTextColour
Returns the numerical value of the current text colour of the terminal object.
Syntax term.getTextColour()
Returns number colour
Part of CC:Tweaked (source)
API term
ExampleExampleGet text colour
Prints the numerical value of the current term's text colour.
Code
print(term.getTextColour())
Output
1
ExampleExampleGet text colour name
Gets the current term's text colour, and then matches it against a lookup table to get its name.
Code
local lookup = { 
    [1] = "white", [2] = "orange", [4] = "magenta", [8] = "lightBlue", 
    [16] = "yellow", [32] = "lime", [64] = "pink", [128] = "gray", 
    [256] = "lightGray",  [512] = "cyan", [1024] = "purple", [2048] = "blue", 
    [4096] = "brown",  [8192] = "green", [16384] = "red", [32768] = "black" 
}
local colour = term.getTextColour()
print(lookup[colour])
Output
white


FunctionFunctionterm.isColour
Returns whether or not this terminal object supports colour.

This returns true for Advanced Computers, Advanced Turtles, Advanced Pocket Computers, Advanced Monitors and Neural Interfaces.

This returns false for Basic Computers, Basic Turtles, Basic Monitors and Basic Pocket Computers.
Syntax term.isColour()
Returns boolean
Part of CC:Tweaked (source)
API term
ExampleExampleCheck if colour is supported
Prints whether or not the current term supports colour.
Code
print(term.isColour())
Output
true

Term.scroll

FunctionFunctionterm.setBackgroundColour
Sets the background colour of the terminal object. All text written after calling this function will have this background colour, until it is changed again.
Syntax term.setBackgroundColour()
Returns nil
Part of CC:Tweaked (source)
API term
ExampleExampleSet background colour
Prints "Hello, world!" with a green background.
Code
term.setBackgroundColour(colours.green)
print("Hello, world!")
Output Demo term.setBackgroundColour.png


FunctionFunctionterm.setCursorBlink
Sets whether or not a blinking cursor should appear at the current cursor pos in the terminal object. When the cursor moves, the blinking cursor will move too, and it will continue to blink until it is manually turned off.
Syntax term.setCursorBlink()
Returns nil
Part of CC:Tweaked (source)
API term
ExampleExampleToggle blinking cursor
Lets the user press enter to toggle whether or not the cursor is blinking.
Code
local blinking = false

print("Press enter to toggle whether or not the cursor is blinking.")
while true do
  local event, key = os.pullEvent("key")

  if key == keys.enter then
    blinking = not blinking -- Toggle blinking state.
    term.setCursorBlink(blinking)
    print("Blinking:", blinking)
  end
end
Output Demo term.setCursorBlink.gif


FunctionFunctionterm.setCursorPos
Sets the X and Y position of the cursor on the terminal object. The next write on this terminal object will begin from the new cursor position.
Syntax term.setCursorPos()
Returns nil
Part of CC:Tweaked (source)
API term
ExampleExampleSet cursor pos
Clears the bottom line of the screen with a red colour, and prints "Hello, world!" in white text.
Code
local width, height = term.getSize()

term.setBackgroundColour(colours.red)
term.setTextColour(colours.white)
term.setCursorPos(1, height - 1)
term.clearLine()
term.write("Hello, world!")
Output Demo term.setCursorPos.png


FunctionFunctionterm.setPaletteColour
Sets the RGB value of the specified palette colour of the terminal object. This allows you to change the appearance of all text and background using this colour.

The first argument is the colour that you want to change, e.g. colours.red. The arguments after that can either be:

  • An integer representing the hexadecimal RGB8 value of the colour, e.g. 0xFF0000 to produce the colour .
  • Three floats (0–1) representing the red, green and blue channels individually, e.g. 1.0, 0.0, 0.0 to produce the colour .
Syntax term.setPaletteColour(
)

term.setPaletteColour(
)
Returns nil
Part of CC:Tweaked (source)
API term
ExampleExampleUsing hex code
Changes the red colour from the default (#cc4c4c) to #FF0000.
Code
term.setPaletteColour(colours.red, 0xFF0000)
term.setTextColour(colours.red)
print("Hello, world!")
Output Demo term.setPaletteColour.png
ExampleExampleUsing separate RGB floats
Changes the red colour from the default (#cc4c4c) to #FF0000.
Code
term.setPaletteColour(colours.red, 1, 0, 0)
term.setTextColour(colours.red)
print("Hello, world!")
Output Demo term.setPaletteColour.png


FunctionFunctionterm.setTextColour
Sets the text colour of the terminal object. All text written after calling this function will have this colour, until it is changed again.
Syntax term.setTextColour()
Returns nil
Part of CC:Tweaked (source)
API term
ExampleExampleSet text colour
Prints "Hello, world!" in green.
Code
term.setTextColour(colours.green)
print("Hello, world!")
Output Demo term.setTextColour.png


FunctionFunctionterm.write
Writes text at the current cursor position in the current term. Unlike print, this function does not automatically move to the next line after writing. Additionally, unlike write and print, it does not perform any text wrapping.
Syntax term.write()
Returns nil
Part of CC:Tweaked (source)
API term
ExampleExampleWrite to the term
Writes "Hello, world!" to the current term.
Code
term.write("Hello, world!")
Output
Hello, world!
ExampleExampleWrite multiple strings the term
Writes "foobar" to the current term. Note how there is no space between writes.
Code
term.write("foo")
term.write("boo")
Output
foobar


Term events

Most of these events are shared by all term objects, but some, such as mouse events, are available exclusively for Advanced Interfaces.

EventEventchar
Occurs every time the user typed a letter.
Returns
  • character : string The character the user typed
Part of CC:Tweaked
ExampleExampleUsing char event
Ask a question that can be answered based on typing a character.
Code
while true do
  print("Do you like pancakes? Press Y/N for yes or no.")

  local event, character = os.pullEvent("char")

  if character == "y" or character == "Y" then
    print("Great! I like pancakes aswell!")
    break
  elseif character == "n" or character == "N" then
    print("Ahw. Perhaps some soup then?")
    break
  else
    print("Sorry, but", character, "is not a valid answer!")
  end
end
EventEventkey
Occurs every time the user presses down a key or when a key is being repeated because it's being held down.
Returns
  • keycode : number The keycode of the key being pressed
  • held : boolean Wether or not the key was already pressed earlier and is currently being held down
Part of CC:Tweaked
ExampleExampleUsing key event
Showing what key the user is interacting with and telling if it's being held down.
Code
while true do
  local event, key_code, being_hold = os.pullEvent("key")

  if being_hold then
    print("The player is holding", keys.getName(key_code), "down.")
  else
    print("The player pressed", keys.getName(key_code))
end
EventEventkey_up
Occurs every time the user releases a previously pressed down key.
Returns
  • keycode : number The keycode of the key being released
Part of CC:Tweaked
ExampleExampleUsing key_up event
Shows what key the player released.
Code
while true do
  local event, key_code = os.pullEvent("key_up")

  print("The player released the", keys.getName(key_code), "key")
end
EventEventmouse_click
Occurs every time a mouse button is pressed. Note Note: This event is only called on advanced terms, such as an Advanced Computer, Advanced Pocket Computer or Neural Interface.
Returns
  • button : number The mouse button that was pressed
  • x : number The X position of the mouse in the term
  • y : number The Y position of the mouse in the term
Part of CC:Tweaked
ExampleExamplePrint coordinates
Prints the mouse coordinates and button name every time a mouse button is pressed.
Code
local button_names = { [1] = "left", [2] = "right", [3] = "middle" }

while true do
  local event, button, x, y = os.pullEvent("mouse_click")
  print("The", button_names[button], "mouse button has been pressed at", x, ",", y)
end
EventEventmouse_drag
Occurs every time the mouse moves to a different position while a mouse button is held down (e.g. left click dragging). It will always be called after a mouse_click event. Note Note: This event is only called on advanced terms, such as an Advanced Computer, Advanced Pocket Computer or Neural Interface.
Returns
  • button : number The mouse button that was pressed
  • x : number The X position of the mouse in the term
  • y : number The Y position of the mouse in the term
Part of CC:Tweaked
ExampleExamplePrint coordinates
Prints the mouse coordinates every time the mouse is dragged on the screen.
Code
while true do
  local event, button, x, y = os.pullEvent("mouse_drag")
  print("Dragged to:", x, y)
end
EventEventmouse_scroll
Occurs every time a mousewheel scrolls. Note Note: This event is only called on advanced terms, such as an Advanced Computer, Advanced Pocket Computer or Neural Interface.
Returns
  • direction : number The direction that was being scrolled in. -1 is up and 1 is down.
  • x : number The X position of the mouse in the term
  • y : number The Y position of the mouse in the term
Part of CC:Tweaked
ExampleExamplePrint coordinates
Prints the scroll direction and mouse coordinates every time the user scrolled.
Code
local scroll_directions = { [-1] = "up", [1] = "down" }

while true do
  local event, direction, x, y = os.pullEvent("mouse_scroll")
  print("The mousewheel scrolled", scroll_directions[direction], "at", x, ",", y)
end
EventEventmouse_up
Occurs every time a mouse button is released after it was pressed down. Note Note: This event is only called on advanced terms, such as an Advanced Computer, Advanced Pocket Computer or Neural Interface.
Returns
  • button : number The mouse button that was released
  • x : number The X position of the mouse in the term
  • y : number The Y position of the mouse in the term
Part of CC:Tweaked
ExampleExamplePrint coordinates
Prints the mouse coordinates and button name every time a mouse button is released.
Code
local button_names = { [1] = "left", [2] = "right", [3] = "middle" }

while true do
  local event, button, x, y = os.pullEvent("mouse_up")
  print("The", button_names[button], "mouse button has been released at", x, ",", y)
end
EventEventpaste
Occurs every time the user pastes text into a terminal, with Ctrl-V
Returns
  • text : string The pasted text
Part of CC:Tweaked
ExampleExampleUsing paste event
Printing everything the user pastes.
Code
while true do
  local event, text = os.pullEvent('paste')
  print('Player pasted ' .. text)
end
ExampleExampleUsing paste event
Saves everything that the user pastes to a file.
Code
local f = fs.open("pasted_contents","w")
while true do
  local event, text = os.pullEventRaw()
  if event == 'paste' then
    f.writeLine(text)
  elseif event == 'terminate' then
    break
  end
end
f.close()
EventEventterm_resize
Occurs every time the term resizes.
Returns
    nothing
Part of CC:Tweaked
ExampleExampleNotify about resize
Notifies the user when the term has been resized.
Code
while true do
  local event = os.pullEvent("term_resize")
  local x, y = term.getSize()
  print("The term has been resized to", x, ",", y)
end