Display & Viewer
Reference User interface components and display settings
Guides
Display and Interaction top ↑
Use viewer to change how your project appears on screen, inspector to adjust values while it runs, and ui to add menus and controls to a scene.
Fit the screen
Read WIDTH and HEIGHT when positioning your drawings. These values can change when the device rotates or the window is resized. Leave space around screen edges so controls stay clear of rounded corners and system gestures.
Adjust values while running
Use the inspector to try different colors, sizes, or speeds without restarting the project. Add objects when you create them; changes in the inspector update the same objects your drawing code uses.
See Viewer for display settings, User Interface for scene controls, and Inspector for inspecting objects. Use Device and Hinge to read device information and the fold angle on supported devices.
Layout
Adapting to the Viewer Bounds top ↑
Use WIDTH and HEIGHT for the current drawing area. Read these values when drawing or handling a resize; the window can change size without changing device orientation. Safe-area insets identify the space occupied by system UI, rounded corners, or other obstructions. Draw backgrounds edge to edge, but keep interactive controls inside the safe area.
function draw()
background(30)
local inset = layout.safeArea
shapeMode(CORNER)
fill(255)
text("Score: 120", inset.left + 16, inset.bottom + 16)
endlayout.safeArea
Syntax
layout.safeAreaRead-only insets in points: left, right, top, and bottom. Read them again after the viewer changes size.
layout.horizontal
Syntax
layout.horizontalHorizontal size class: layout.COMPACT, layout.REGULAR, or layout.UNSPECIFIED.
layout.vertical
Syntax
layout.verticalVertical size class, using the same constants as horizontal.
layout.orientation
Syntax
layout.orientationCurrent interface orientation, or nil when unknown. Compare with the orientation constants; use viewer dimensions for layout decisions.
layout.COMPACT
Syntax
layout.COMPACTCompact size class.
layout.REGULAR
Syntax
layout.REGULARRegular size class.
layout.UNSPECIFIED
Syntax
layout.UNSPECIFIEDUnspecified size class.
layout.portrait
Syntax
layout.portraitUpright portrait orientation.
layout.portraitUpsideDown
Syntax
layout.portraitUpsideDownUpside-down portrait orientation.
layout.landscapeLeft
Syntax
layout.landscapeLeftLandscape-left interface orientation.
layout.landscapeRight
Syntax
layout.landscapeRightLandscape-right interface orientation.
Viewer
viewer top ↑
Control the window where your project runs, including its display mode and layout.
viewer.mode
Syntax
viewer.mode = STANDARD
viewer.mode = FULLSCREEN
viewer.mode = FULLSCREEN_NO_BUTTONSChanges the display mode of the viewer. Use this to render your games and simulations in fullscreen mode, fullscreen mode without buttons, or standard mode. Standard mode includes the sidebar with output and parameters, plus controls for project execution.
viewer.framerate
Syntax
viewer.framerate = 30Sets the preferred framerate of the viewer. You can set this to 0, 15, 30, 60 or 120. The value 0 uses the maximum framerate of your device.
Note that this sets the preferred framerate. If the framerate cannot be maintained, it may drop below your preferred setting to the next lower value.
viewer.pointerLocked
Syntax
viewer.pointerLocked = trueSetting this property to true indicates the renderer’s preference to lock the pointer, although the system may not honor the request. For the system to consider locking the pointer, the viewer must be running fullscreen on your device.
viewer.runtime
Syntax
if viewer.runtime == viewer.MODERN then
strokeWidth(5)
endThe active runtime type, either LEGACY or MODERN.
viewer.safeArea
Syntax
print(viewer.safeArea.bottom)A table specifying the current safe area insets of the viewer. Use these values to avoid rendering important visible or interactive content under system interface areas.
viewer.uniformResizing
Syntax
viewer.uniformResizingControls whether the viewer preserves a uniform resizing behavior when the view changes size. This is only supported on platforms where the viewer is resizable.
viewer.resize(width, height)
Syntax
viewer.resize(800, 600)Resizes the viewer to the specified width and height. This is only supported on platforms where the viewer is resizable.
Parameters
| width | number. The new viewer width. |
| height | number. The new viewer height. |
viewer.paused
Syntax
viewer.pausedA boolean value that indicates whether the viewer is paused.
viewer.displayStats
Syntax
viewer.displayStatsControls whether runtime statistics are displayed in the viewer.
viewer.drawOnRequest
Syntax
viewer.drawOnRequestControls whether the viewer draws only when a redraw is requested.
viewer.showWarnings
Syntax
viewer.showWarningsDetermines whether warnings should be displayed in the viewer. For example, warnings will be printed when using deprecated Codea APIs.
viewer.close()
Syntax
viewer.close()Closes the viewer and returns to the editor. Calling viewer.close() is functionally the same as pressing the on-screen Back button.
viewer.restart()
Syntax
viewer.restart()Restarts the viewer, starting your project again. Calling viewer.restart() is functionally the same as pressing the on-screen Restart button.
viewer.snapshot()
Syntax
local img = viewer.snapshot()Captures the rendered contents of the viewer and returns them as an image. This captures the rendered scene and does not include the sidebar UI.
Returns
image |
The rendered viewer contents. |
viewer.alert(message, title)
Syntax
viewer.alert("Hello World")
viewer.alert("Hello World", "Title")Shows a system alert. The message parameter specifies the message to display. The optional title parameter provides the title of the alert. If no title is specified, "Alert" is used.
Parameters
| message | string. Message to display. |
| title | string, optional. Alert title. |
viewer.isPresenting
Syntax
if not viewer.isPresenting then
viewer.alert("Ready")
endReturns whether the viewer is presenting an alert, share sheet, or another view that obscures the viewer.
STANDARD top ↑
Syntax
STANDARDStandard display mode. The output and parameters panes are visible, and the Back, Pause, Play and Reset buttons are shown.
FULLSCREEN top ↑
Syntax
FULLSCREENFullscreen display mode. An exit fullscreen button remains visible.
FULLSCREEN_NO_BUTTONS top ↑
Syntax
FULLSCREEN_NO_BUTTONSFullscreen display mode with all buttons hidden. Use viewer.close() if your project needs an explicit way to leave the viewer.
Hinge
hinge top ↑
Read hinge.angle to get the fold angle on supported devices, or define hingeChanged to respond as the device folds.
The angle is nil when no reading is available. Choose a fallback before using it in calculations, such as local angle = hinge.angle or 0.
hinge.angle
Syntax
local angle = hinge.angle
if angle ~= nil then
local radians = math.rad(angle)
endThe hinge angle, in degrees. The value may be nil if no hinge angle is available yet or the device is not supported.
hingeChanged(current, previous) top ↑
Syntax
function hingeChanged(current, previous)
if current == nil then
print("Hinge input unavailable")
elseif previous == nil then
print("Hinge angle:", current)
else
print("Hinge angle change:", current - previous)
end
endUse this global function to receive changes to the hinge angle. Codea calls it before drawing with the new and previous angles in degrees.
previous is nil for the first reading and when readings resume after being unavailable. current is nil when hinge input becomes unavailable. The function is not called while both values are nil.
In draw-on-request mode, a hinge change causes Codea to draw a frame and call this function.
Parameters
| current | number | nil. The new angle in degrees, or nil when unavailable. |
| previous | number | nil. The previous angle in degrees, or nil if none was available. |
Device
device top ↑
Use device to read the model, operating system, and device name. For screen layout, use WIDTH and HEIGHT: a window’s size can change.
device.id
Syntax
device.idThe identifierForVendor UUID string of the device.
device.name
Syntax
device.nameThe user provided name of the device.
device.systemName
Syntax
device.systemNameThe name of the operating system running on the device.
device.systemVersion
Syntax
device.systemVersionThe version of the operating system running on the device.
device.model
Syntax
device.modelThe model of the device.
device.localizedModel
Syntax
device.localizedModelThe localized model of the device.
device.batteryLevel
Syntax
device.batteryLevelThe battery level of the device, from 0.0 to 1.0. -1.0 if the battery state is unknown.
device.batteryState
Syntax
device.batteryStateThe battery state of the device. One of “unknown”, “unplugged”, “charging”, “full”.
Inspector
inspector top ↑
Use the inspector to change an object’s values while your project runs. Call inspector.set(object) to show it, or inspector.add(object) to add it alongside other objects. Changes take effect in your project immediately.
Use push and pop to move between inspector pages, and clear to remove the contents. Add objects once when creating or selecting them.
inspector.set(object)
Syntax
inspector.set(object)Displays any viewable/editable properties and actions for object
Parameters
| object | table or userdata. Object whose inspectable properties and actions are displayed. |
inspector.add(object)
Syntax
inspector.add(object)Appends object’s data to the inspector
Parameters
| object | table or userdata. Object whose inspectable properties and actions are displayed. |
inspector.push(object)
Syntax
inspector.push(object)Pushes a new page onto the inspector stack and adds object to it
Parameters
| object | table or userdata. Object whose inspectable properties and actions are displayed. |
inspector.pop()
Syntax
inspector.pop()inspector.clear()
Syntax
inspector.clear()User Interface
ui top ↑
Add menus, labels, and controls to a scene with ui.canvas. Use anchors and pivots to position them relative to their container, and set their size in canvas units.
ui.canvas
Syntax
ui.canvasProvides a 2D layer for rendering UI elements within a scene
Canvas Entities
Child entities created with ui.canvas, are 2D elements that use an automatic layout system
Canvas children have additional properties and methods:
entity.size,vec2- the 2D size of the entity in canvas unitsentity.pivot,vec2- the centre privot point of the entityentity.anchorX,enum- the horizontal alignment of the entityentity.anchorY,enum- the vertical alignment of the entityentity:anchor(x, y)- shortcut for settinganchorX,anchorY
Anchors
Canvas entities are laid out using an anchor and pivot system
For horizontal alignment use:
LEFT- Align relative to the left side of the parent entityRIGHT- Align relative to the right side of the parent entityCENTER- Align relative to the center of the parent entity
For vertical alignment use:
BOTTOM- Align relative to the bottom of the parent entityMODDLE- Align relative to the middle of the parent entityTOP- Align relative to the top of the parent entity
Both horizonal and vertical alignment can be stretched
STRETCH- Stretch the component relative to it’s parent
scn = scene()
-- Create an entity to contain the button
ent = scn.canvas:child("button")
-- Adjust the button size
ent.size = vec2(300, 150)
-- Add a button component
btn = ent:add(ui.button)
btn.label.text = "Press Me!"
-- Add a callback function to react to button taps
function ent:tapped()
print("Tapped!")
endui.canvas.entity
Syntax
ui.canvas.entityThe entity for this canvas
ui.canvas.scale
Syntax
ui.canvas.scaleScale factor for canvas drawing
ui.label
Syntax
ui.labelDraws text on a canvas entity
ui.label.text
Syntax
ui.label.textThe text to render on the label
ui.label.color
Syntax
ui.label.colorThe label’s text color
ui.label.font
Syntax
ui.label.fontOptional system font name. Use a face such as "Helvetica-Bold" for a bold label. When omitted, the label uses the current style font.
ui.label.fontSize
Syntax
ui.label.fontSizeThe label’s font size
ui.label.align
Syntax
ui.label.alignThe label’s text alignment
ui.label.textRenderer
Syntax
ui.label.textRendererThe label’s renderer: style.native (the default) or style.atlas. Atlas labels interpret tags; native labels support color emoji.
ui.label.shadowOffset
Syntax
ui.label.shadowOffsetThe offset of the labels text shadow
ui.label.shadowRadius
Syntax
ui.label.shadowRadiusThe blur radius of the label’s text shadow, in points
ui.image
Syntax
ui.imageDraws an image on a canvas entity
ui.image.image
Syntax
ui.image.imageThe image to draw
ui.button
Syntax
ui.buttonMakes a canvas entity into an interactive button
ui.button.style
Syntax
ui.button.styleThe button’s style. Background image and color tint can be set for each button state
Button table structure
btn.style =
{
normal = { sprite = ..., color = ... },
pressed = { sprite = ..., color = ... },
disabled = { sprite = ..., color = ... },
selected = { sprite = ..., color = ... }
}ui.vstack
Syntax
ui.vstackLays out child entities in a vertical stack
ui.vstack.padding
Syntax
ui.vstack.paddingThe outer padding for the stack, used to create a border around the edge
ui.vstack.spacing
Syntax
ui.vstack.spacingThe spacing between each item in the stack
ui.hstack
Syntax
ui.hstackLays out child entities in a horizontal stack
ui.hstack.padding
Syntax
ui.hstack.paddingThe outer padding for the stack, used to create a border around the edge
ui.hstack.spacing
Syntax
ui.hstack.spacingThe spacing between each item in the stack