# Display & Viewer User interface components and display settings [Reference](index.md) ## Guides ### Display and Interaction 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](#viewer) for display settings, [User Interface](#ui) for scene controls, and [Inspector](#inspector) for inspecting objects. Use [Device](#device) and [Hinge](#hinge) to read device information and the fold angle on supported devices. ## Layout ### Adapting to the Viewer Bounds 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. ```lua function draw() background(30) local inset = layout.safeArea shapeMode(CORNER) fill(255) text("Score: 120", inset.left + 16, inset.bottom + 16) end ``` ### WIDTH ```lua WIDTH ``` Current width of the drawing area in points. current width of the drawing area in points ### HEIGHT ```lua HEIGHT ``` Current height of the drawing area in points. current height of the drawing area in points ### layout ### layout.safeArea ```lua layout.safeArea ``` Read-only insets in points: `left`, `right`, `top`, and `bottom`. Read them again after the viewer changes size. read-only insets in points: ``left``, ``right``, ``top``, and ``bottom`` ### layout.horizontal ```lua layout.horizontal ``` Horizontal size class: `layout.COMPACT`, `layout.REGULAR`, or `layout.UNSPECIFIED`. horizontal size class: ``layout ### layout.vertical ```lua layout.vertical ``` Vertical size class, using the same constants as `horizontal`. vertical size class, using the same constants as ``horizontal`` ### layout.orientation ```lua layout.orientation ``` Current interface orientation, or nil when unknown. Compare with the orientation constants; use viewer dimensions for layout decisions. current interface orientation, or nil when unknown ### layout.COMPACT ```lua layout.COMPACT ``` Compact size class. compact size class ### layout.REGULAR ```lua layout.REGULAR ``` Regular size class. regular size class ### layout.UNSPECIFIED ```lua layout.UNSPECIFIED ``` Unspecified size class. unspecified size class ### layout.portrait ```lua layout.portrait ``` Upright portrait orientation. upright portrait orientation ### layout.portraitUpsideDown ```lua layout.portraitUpsideDown ``` Upside-down portrait orientation. upside-down portrait orientation ### layout.landscapeLeft ```lua layout.landscapeLeft ``` Landscape-left interface orientation. landscape-left interface orientation ### layout.landscapeRight ```lua layout.landscapeRight ``` Landscape-right interface orientation. landscape-right interface orientation ## Viewer ### viewer Control the window where your project runs, including its display mode and layout. ### viewer.mode ```lua viewer.mode = STANDARD viewer.mode = FULLSCREEN viewer.mode = FULLSCREEN_NO_BUTTONS ``` Changes 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. current viewer display mode ### viewer.framerate ```lua viewer.framerate = 30 ``` Sets 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. preferred viewer framerate ### viewer.pointerLocked ```lua viewer.pointerLocked = true ``` Setting 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. whether pointer locking is desired ### viewer.runtime ```lua if viewer.runtime == viewer.MODERN then strokeWidth(5) end ``` The active runtime type, either `LEGACY` or `MODERN`. current runtime type ### viewer.safeArea ```lua 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. safe area insets of the viewer ### viewer.uniformResizing ```lua viewer.uniformResizing ``` Controls whether the viewer preserves a uniform resizing behavior when the view changes size. This is only supported on platforms where the viewer is resizable. use uniform viewer resizing ### viewer.resize(width, height) ```lua viewer.resize(800, 600) ``` Resizes the viewer to the specified width and height. This is only supported on platforms where the viewer is resizable. resize the viewer #### Parameters - **width** (number): The new viewer width. - **height** (number): The new viewer height. ### viewer.paused ```lua viewer.paused ``` A boolean value that indicates whether the viewer is paused. paused state of the viewer ### viewer.displayStats ```lua viewer.displayStats ``` Controls whether runtime statistics are displayed in the viewer. show viewer statistics ### viewer.drawOnRequest ```lua viewer.drawOnRequest ``` Controls whether the viewer draws only when a redraw is requested. draw only when requested ### viewer.showWarnings ```lua viewer.showWarnings ``` Determines whether warnings should be displayed in the viewer. For example, warnings will be printed when using deprecated Codea APIs. show viewer warnings ### viewer.close() ```lua viewer.close() ``` Closes the viewer and returns to the editor. Calling `viewer.close()` is functionally the same as pressing the on-screen Back button. close the viewer ### viewer.restart() ```lua viewer.restart() ``` Restarts the viewer, starting your project again. Calling `viewer.restart()` is functionally the same as pressing the on-screen Restart button. restart the viewer ### viewer.snapshot() ```lua 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. capture the viewer as an image #### Returns - **image**: The rendered viewer contents. ### viewer.alert(message, title) ```lua 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. show a system alert #### Parameters - **message** (string): Message to display. - **title** (string, optional): Alert title. ### viewer.share(data) ```lua viewer.share(viewer.snapshot()) ``` Shows a system share view for an image, string, or table of shareable items. This allows you to share content to a third-party service, save it to your device, or copy it to the pasteboard. share viewer content #### Parameters - **data** (image | string | table): Content to share. ### viewer.isPresenting ```lua if not viewer.isPresenting then viewer.alert("Ready") end ``` Returns whether the viewer is presenting an alert, share sheet, or another view that obscures the viewer. whether the viewer is presenting another view ### STANDARD ```lua STANDARD ``` Standard display mode. The output and parameters panes are visible, and the Back, Pause, Play and Reset buttons are shown. standard viewer mode ### FULLSCREEN ```lua FULLSCREEN ``` Fullscreen display mode. An exit fullscreen button remains visible. fullscreen viewer mode ### FULLSCREEN_NO_BUTTONS ```lua FULLSCREEN_NO_BUTTONS ``` Fullscreen display mode with all buttons hidden. Use `viewer.close()` if your project needs an explicit way to leave the viewer. fullscreen viewer mode without buttons ### LEGACY ```lua LEGACY ``` Legacy runtime identifier. legacy renderer ### MODERN ```lua MODERN ``` Identifier for the current Codea renderer. current Codea renderer ## Hinge ### hinge 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 ```lua local angle = hinge.angle if angle ~= nil then local radians = math.rad(angle) end ``` The hinge angle, in degrees. The value may be `nil` if no hinge angle is available yet or the device is not supported. current hinge angle in degrees, or nil when unavailable ### hingeChanged(current, previous) ```lua 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 end ``` Use 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. called before drawing when the hinge angle changes #### 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 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 ```lua device.id ``` The identifierForVendor UUID string of the device. vendor identifier of the device ### device.name ```lua device.name ``` The user provided name of the device. user-defined device name ### device.systemName ```lua device.systemName ``` The name of the operating system running on the device. operating system name ### device.systemVersion ```lua device.systemVersion ``` The version of the operating system running on the device. operating system version ### device.model ```lua device.model ``` The model of the device. device model ### device.localizedModel ```lua device.localizedModel ``` The localized model of the device. localized device model ### device.batteryLevel ```lua device.batteryLevel ``` The battery level of the device, from 0.0 to 1.0. -1.0 if the battery state is unknown. current battery level ### device.batteryState ```lua device.batteryState ``` The battery state of the device. One of “unknown”, “unplugged”, “charging”, “full”. current battery state ## Inspector ### inspector 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) ```lua inspector.set(object) ``` Displays any viewable/editable properties and actions for `object` replace the inspector contents #### Parameters - **object** (table or userdata): Object whose inspectable properties and actions are displayed. ### inspector.add(object) ```lua inspector.add(object) ``` Appends `object`’s data to the inspector add an object to the inspector #### Parameters - **object** (table or userdata): Object whose inspectable properties and actions are displayed. ### inspector.push(object) ```lua inspector.push(object) ``` Pushes a new page onto the inspector stack and adds `object` to it push a new inspector page #### Parameters - **object** (table or userdata): Object whose inspectable properties and actions are displayed. ### inspector.pop() ```lua inspector.pop() ``` pop the current inspector page ### inspector.clear() ```lua inspector.clear() ``` clear the inspector ## User Interface ### ui 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 ```lua ui.canvas ``` Provides 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 units - `entity.pivot`, `vec2` - the centre privot point of the entity - `entity.anchorX`, `enum` - the horizontal alignment of the entity - `entity.anchorY`, `enum` - the vertical alignment of the entity - `entity:anchor(x, y)` - shortcut for setting `anchorX`, `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 entity - `RIGHT` - Align relative to the right side of the parent entity - `CENTER` - Align relative to the center of the parent entity For vertical alignment use: - `BOTTOM` - Align relative to the bottom of the parent entity - `MODDLE` - Align relative to the middle of the parent entity - `TOP` - 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 get the entity associated to this canvas #### Example ```lua 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!") end ``` ### ui.canvas.entity ```lua ui.canvas.entity ``` The entity for this canvas get the entity associated to this canvas ### ui.canvas.scale ```lua ui.canvas.scale ``` Scale factor for canvas drawing get or set the canvas scale ### ui.label ```lua ui.label ``` Draws text on a canvas entity get or set the label text ### ui.label.text ```lua ui.label.text ``` The text to render on the label get or set the label text ### ui.label.color ```lua ui.label.color ``` The label’s text color get or set the label text color ### ui.label.font ```lua ui.label.font ``` Optional system font name. Use a face such as `"Helvetica-Bold"` for a bold label. When omitted, the label uses the current style font. get or set the label font ### ui.label.fontSize ```lua ui.label.fontSize ``` The label’s font size get or set the font size ### ui.label.align ```lua ui.label.align ``` The label’s text alignment get or set the text alignment flags ### ui.label.textRenderer ```lua ui.label.textRenderer ``` The label’s renderer: `style.native` (the default) or `style.atlas`. Atlas labels interpret tags; native labels support color emoji. get or set the label text renderer ### ui.label.shadowOffset ```lua ui.label.shadowOffset ``` The offset of the labels text shadow get or set the text shadow offset ### ui.label.shadowRadius ```lua ui.label.shadowRadius ``` The blur radius of the label’s text shadow, in points get or set the text shadow blur radius ### ui.image ```lua ui.image ``` Draws an image on a canvas entity get or set the image to draw ### ui.image.image ```lua ui.image.image ``` The image to draw get or set the image to draw ### ui.button ```lua ui.button ``` Makes a canvas entity into an interactive button get or set the style flags or table ### ui.button.style ```lua ui.button.style ``` The button’s style. Background image and color tint can be set for each button state get or set the style flags or table #### Button table structure ```lua btn.style = { normal = { sprite = ..., color = ... }, pressed = { sprite = ..., color = ... }, disabled = { sprite = ..., color = ... }, selected = { sprite = ..., color = ... } } ``` ### ui.vstack ```lua ui.vstack ``` Lays out child entities in a vertical stack get or set the padding ### ui.vstack.padding ```lua ui.vstack.padding ``` The outer padding for the stack, used to create a border around the edge get or set the padding ### ui.vstack.spacing ```lua ui.vstack.spacing ``` The spacing between each item in the stack get or set the spacing ### ui.hstack ```lua ui.hstack ``` Lays out child entities in a horizontal stack get or set the padding ### ui.hstack.padding ```lua ui.hstack.padding ``` The outer padding for the stack, used to create a border around the edge get or set the padding ### ui.hstack.spacing ```lua ui.hstack.spacing ``` The spacing between each item in the stack get or set the spacing