Term

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.

Functionterm.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(

text : string
textColour : string
backgroundColour : string

)

Returns

nil

Part of

CC:Tweaked (source)

API

term

ExamplePrint rainbow text

Prints "Hello world!" in 11-color text.

Code

<nowiki>
term.blit("Hello world!","01234456789a","f00000000000")
</nowiki>

Output

Hello world!

Functionterm.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

ExampleClear a terminal

Clears the current term.

Code

<nowiki>
print("Hello, world!")
sleep(1)
term.clear()
    </nowiki>

Output Hello, world! is printed, and then disappears after 1 second.

ExampleClear a terminal with a colour

Clears the current term with a red background colour.

Code

<nowiki>
term.setBackgroundColour(colours.red)
term.clear()
    </nowiki>

Output

The screen is cleared and filled with red.

Functionterm.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

ExampleClear a line

Writes a line, waits, and then clears it.

Code

<nowiki>
write("Hello, world!")
term.clearLine()
  </nowiki>

Output Hello, world! is printed, and then disappears after 1 second.

ExampleClear a specific line with a colour

Clears the top line of the current term with a red colour.

Code

<nowiki>
term.setBackgroundColour(colours.red)
term.setCursorPos(1, 1)
term.clearLine()
  </nowiki>

Output

The top line of the screen is cleared and filled with red.

ExampleClear many lines with different colours

Draws a line which each colour to the screen, clearing everything between.

Code

<nowiki>
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 </nowiki>[[Colours]]<nowiki> 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
  </nowiki>

Output

Functionterm.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

ExampleGet background colour

Prints the numerical value of the current term's background colour.

Code

<nowiki>
print(term.getBackgroundColour())
  </nowiki>

Output

ExampleGet background colour name

Gets the current term's background colour, and then matches it against a lookup table to get its name.

Code

<nowiki>
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])
  </nowiki>

Output

black

Functionterm.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

ExampleGet cursor pos

Prints the cursor position of the current term.

Code

<nowiki>
local x, y = term.getCursorPos()
print(x, y)
  </nowiki>

Output

1, 3

Functionterm.getPaletteColour

Returns the RGB values (0–1) of the specified palette colour of the terminal object.

Syntax

term.getPaletteColour(

colour : number

)

Returns number red, number green, number blue

Part of CC:Tweaked (source)

API term

ExampleGet specific palette colour

Prints the decimal RGB value of the colour red in the current term's palette.

Code

<nowiki>
local red, green, blue = term.getPaletteColour(colours.red)
print(red, green, blue)
  </nowiki>

Output 0.80000001192093 0.29803922772408 0.29803922772408 (equivalent to #cc4c4c)

ExampleGet current palette colour

Prints the decimal RGB value of the current term's text colour.

Code

<nowiki>
local colour = term.getTextColour()
local red, green, blue = term.getPaletteColour(colour)
print(red, green, blue)
  </nowiki>

Output 0.94117647409439 0.94117647409439 0.94117647409439 (equivalent to #f0f0f0)

Functionterm.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

ExampleGet term size

Prints the width and height of the current term.

Code

<nowiki>
local width, height = term.getSize()
print(width, height)
  </nowiki>

Output On computers, 51 19

Functionterm.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

ExampleGet text colour

Prints the numerical value of the current term's text colour.

Code

<nowiki>
print(term.getTextColour())
  </nowiki>

Output

ExampleGet text colour name

Gets the current term's text colour, and then matches it against a lookup table to get its name.

Code

<nowiki>
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])
  </nowiki>

Output

white

Functionterm.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

ExampleCheck if colour is supported

Prints whether or not the current term supports colour.

Code

<nowiki>
print(term.isColour())
  </nowiki>

Output

true

Functionterm.scroll

Moves everything on the screen up distance pixels.

Syntax

term.scroll(

distance : number

)

Returns

nil

Part of

CC:Tweaked (source)

API

term

ExampleMoves "Hello World!" up 3 pixels, and then prints "This text was printed 3 pixels below 'Hello World!"

Code

<nowiki>
term.clear()
term.setCursorPos(1,4)
print("Hello World!")
term.scroll(3)
print("This text was printed 3 pixels below 'Hello World!'")
    </nowiki>

Output

Hello World!



This text was printed 3 pixels below 'Hello World!'

Functionterm.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(

colour : number

)

Returns

nil

Part of

CC:Tweaked (source)

API

term

ExampleSet background colour

Prints "Hello, world!" with a green background.

Code

<nowiki>
term.setBackgroundColour(colours.green)
print("Hello, world!")
  </nowiki>

Output

Functionterm.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(

blink : boolean

)

Returns

nil

Part of

CC:Tweaked (source)

API

term

ExampleToggle blinking cursor

Lets the user press enter to toggle whether or not the cursor is blinking.

Code

<nowiki>
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
  </nowiki>

Output

Functionterm.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(

x : number
y : number

)

Returns

nil

Part of

CC:Tweaked (source)

API

term

ExampleSet cursor pos

Clears the bottom line of the screen with a red colour, and prints "Hello, world!" in white text.

Code

<nowiki>
local width, height = term.getSize()

term.setBackgroundColour(colours.red)
term.setTextColour(colours.white)
term.setCursorPos(1, height - 1)
term.clearLine()
term.write("Hello, world!")
  </nowiki>

Output

Functionterm.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(

colour : number
rgb : number

)

term.setPaletteColour(

colour : number
red : number
green : number
blue : number

)

Returns nil

Part of CC:Tweaked (source)

API term

ExampleUsing hex code

Changes the red colour from the default (#cc4c4c) to #FF0000.

Code

<nowiki>
term.setPaletteColour(colours.red, 0xFF0000)
term.setTextColour(colours.red)
print("Hello, world!")
  </nowiki>

Output

ExampleUsing separate RGB floats

Changes the red colour from the default (#cc4c4c) to #FF0000.

Code

<nowiki>
term.setPaletteColour(colours.red, 1, 0, 0)
term.setTextColour(colours.red)
print("Hello, world!")
  </nowiki>

Output

Functionterm.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(

colour : number

)

Returns

nil

Part of

CC:Tweaked (source)

API

term

ExampleSet text colour

Prints "Hello, world!" in green.

Code

<nowiki>
term.setTextColour(colours.green)
print("Hello, world!")
  </nowiki>

Output

Functionterm.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(

text : string

)

Returns

nil

Part of

CC:Tweaked (source)

API

term

ExampleWrite to the term

Writes "Hello, world!" to the current term.

Code

<nowiki>
term.write("Hello, world!")
    </nowiki>

Output

Hello, world!

ExampleWrite multiple strings the term

Writes "foobar" to the current term. Note how there is no space between writes.

Code

<nowiki>
term.write("foo")
term.write("boo")
    </nowiki>

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.

Eventchar

Occurs every time the user typed a letter.

Returns

character : string The character the user typed

Part of

CC:Tweaked

ExampleUsing char event

Ask a question that can be answered based on typing a character.

Code

<nowiki>
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
    </nowiki>

Eventkey

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

ExampleUsing key event

Showing what key the user is interacting with and telling if it's being held down.

Code

<nowiki>
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
    </nowiki>

Eventkey_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

ExampleUsing key_up event

Shows what key the player released.

Code

<nowiki>
while true do
  local event, key_code = os.pullEvent("key_up")

  print("The player released the", keys.getName(key_code), "key")
end
    </nowiki>

Eventmouse_click

Occurs every time a mouse button is pressed.

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

ExamplePrint coordinates

Prints the mouse coordinates and button name every time a mouse button is pressed.

Code

<nowiki>
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
    </nowiki>

Eventmouse_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: 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

ExamplePrint coordinates

Prints the mouse coordinates every time the mouse is dragged on the screen.

Code

<nowiki>
while true do
  local event, button, x, y = os.pullEvent("mouse_drag")
  print("Dragged to:", x, y)
end
    </nowiki>

Eventmouse_scroll

Occurs every time a mousewheel scrolls.

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

ExamplePrint coordinates

Prints the scroll direction and mouse coordinates every time the user scrolled.

Code

<nowiki>
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
    </nowiki>

Eventmouse_up

Occurs every time a mouse button is released after it was pressed down.

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

ExamplePrint coordinates

Prints the mouse coordinates and button name every time a mouse button is released.

Code

<nowiki>
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
    </nowiki>

Eventpaste

Occurs every time the user pastes text into a terminal, with Ctrl-V

Returns

text : string The pasted text

Part of

CC:Tweaked

ExampleUsing paste event

Printing everything the user pastes.

Code

<nowiki>
while true do
  local event, text = os.pullEvent('paste')
  print('Player pasted ' .. text)
end
    </nowiki>

ExampleUsing paste event

Saves everything that the user pastes to a file.

Code

<nowiki>
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()
    </nowiki>

Eventterm_resize

Occurs every time the term resizes.

Returns

nothing

Part of

CC:Tweaked

ExampleNotify about resize

Notifies the user when the term has been resized.

Code

<nowiki>
while true do
  local event = os.pullEvent("term_resize")
  local x, y = term.getSize()
  print("The term has been resized to", x, ",", y)
end
    </nowiki>

gollark: Kit imploded?

gollark: Well, the obvious solution is to make a separate "serious esolangs" and transfer executive authority over this one to me imminently.

gollark: What?

gollark: Since shiny machine learning™ things exist.

gollark: Anyway, the GPU thing is very annoying because I "need" arbitrarily large quantities of GPU power for things now.

This article is issued from Computercraft. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.