Display & Keyboard

Reference ❯ Using the Viewer's Display Modes

Display Modes

displayMode( MODE ) top ↑

Syntax

displayMode( STANDARD |
             OVERLAY |
             FULLSCREEN |
             FULLSCREEN_NO_BUTTONS )

Changes the display mode of the viewer. You can use this to render your games and simulations in fullscreen mode, fullscreen mode without buttons, standard mode, or overlay mode.

mode

Either STANDARD, OVERLAY, FULLSCREEN or FULLSCREEN_NO_BUTTONS

Examples

function setup() --Set the viewer to fullscreen displayMode( FULLSCREEN ) end
function setup() --Set the viewer to standard --i.e. visible parameters and output displayMode( STANDARD ) end
function setup() --Set the viewer to overlay displayMode( OVERLAY ) end
function setup() --Set the viewer to fullscreen --Hide back/pause/play buttons displayMode( FULLSCREEN_NO_BUTTONS ) end

Returns

The current display mode if called with no arguments. Otherwise this function returns nothing.

FULLSCREEN top ↑

Syntax

FULLSCREEN

Use this value in displayMode() to set the viewer to fullscreen mode. The Back, Pause, Play and Reset buttons will still be visible in the lower left corner of the screen.

STANDARD top ↑

Syntax

displayMode( STANDARD )
backingMode( STANDARD )

Use this value in displayMode() or backingMode()

When used with displayMode() this sets the viewer to standard screen mode. You will be able to see the output and parameters panes to the left of the viewer, and the Back, Pause, Play and Reset buttons will be visible in the lower left corner of the screen.

When used with backingMode() this tells the viewer to render without using a retained backing, this means that the contents of the previous frame are not guaranteed to be preserved when entering the draw() call. This offers the best drawing performance.

OVERLAY top ↑

Syntax

displayMode( OVERLAY )

This value is used with displayMode() to set the viewer to overlay screen mode. In this mode you will be able to see the output and parameter panes overlaid on the viewer, the panes are semi-transparent in this mode so that you can see your content through them.

FULLSCREEN_NO_BUTTONS top ↑

Syntax

FULLSCREEN_NO_BUTTONS

Use this value in displayMode() to set the viewer to fullscreen mode and hide all buttons on the screen. Note: you will not be able to exit the viewer unless you implement your own call to the close() function. You can force the standard Back button to appear by triple-tapping the screen with three fingers.

Layout

Layout Overview top ↑

Codea will run your projects in any configuration your device supports, this could be in portrait or landscape orientation, in a split-view environment, or with the sidebar taking up space in your view.

Some devices include "safe areas," these areas are regions of the screen in which you should avoid rendering your content. You can access the safe area insets through the layout.safeArea property. These values are insets, and represent how much you should inset your content from the respective edge of the view in order to ensure it remains visible and interactive.

When the view size changes, Codea calls the global function sizeChanged( width, height ) and passes it the new view size.

Examples

function setup() end function sizeChanged( newWidth, newHeight ) -- This function gets called when -- the view size changes end

layout.safeArea top ↑

This property contains a table specifying the current safe area insets of the viewer, access them by using layout.safeArea.top, layout.safeArea.bottom, layout.safeArea.left, and layout.safeArea.right

The safe area insets indicate how far from the respective edge of the screen you should avoid rendering your content into. For example, a safe area inset of 60 on the top edge might indicate your code is running on a device with a notched display, and so you should offset your interactive content 60 points from the top of the view in order to ensure its visibility.

top

number, the safe area inset for the top of the viewer

left

number, the safe area inset for the left of the viewer

bottom

number, the safe area inset for the bottom of the viewer

right

number, the safe area inset for the right of the viewer

Examples

function setup() -- We might have a bottom safe area -- inset if we are running on a -- device with an on-screen home -- indicator print(layout.safeArea.bottom) end

layout.horizontal top ↑

This property specifies whether the viewer is running in a regular or compact horizontal layout mode. For example, when running Codea in split-view the horizontal layout mode of the viewer may switch to compact. You can use this property to switch your application into a state which may better deal with a smaller screen area.

The value of this property can be layout.COMPACT, layout.REGULAR, or layout.UNSPECIFIED

Examples

-- This example prints the size class whenever -- the viewer size changes, try adjusting into -- split-view and back to see the mode change function sizeChanged(w, h) printSizeClass() end function printSizeClass() if layout.horizontal == layout.REGULAR then print("Regular size") else print("Compact size") end end

layout.vertical top ↑

This property specifies whether the viewer is running in a regular or compact vertical layout mode. The vertical layout class may change when switching from portrait to landscape orientation on certain devices. Use this property to react accordingly.

The value of this property can be layout.COMPACT, layout.REGULAR, or layout.UNSPECIFIED

layout.COMPACT top ↑

This value indicates a compact layout environment for the specified dimension

layout.REGULAR top ↑

This value indicates a regular layout environment for the specified dimension

CurrentOrientation top ↑

This global contains the current orientation and can be one of the following: PORTRAIT, PORTRAIT_UPSIDE_DOWN, LANDSCAPE_LEFT, LANDSCAPE_RIGHT.

PORTRAIT top ↑

Syntax

CurrentOrientation == PORTRAIT

Check for this value in CurrentOrientation to detect if the device is in standard portrait orientation (home button at the bottom).

PORTRAIT_UPSIDE_DOWN top ↑

Syntax

CurrentOrientation == PORTRAIT_UPSIDE_DOWN

Check for this value in CurrentOrientation to detect if the device is in inverted portrait orientation (home button at the top).

LANDSCAPE_LEFT top ↑

Syntax

CurrentOrientation == LANDSCAPE_LEFT

Check for this value in CurrentOrientation to detect if the device is in landscape left orientation (home button on left).

LANDSCAPE_RIGHT top ↑

Syntax

CurrentOrientation == LANDSCAPE_RIGHT

Check for this value in CurrentOrientation to detect if the device is in landscape right orientation (home button on right).

Showing and Hiding the Keyboard

Using the Keyboard top ↑

You can use the keyboard in Codea to receive text input in your projects. In order to begin receiving keyboard events, call the showKeyboard() function. This will show the on-screen keyboard, unless an external keyboard is present. When key presses are made Codea calls the global function keyboard( key ). You must implement this function to receive keyboard events.

function keyboard( key )
    print("Key pressed: '".. key .."'")
end

Alternatively you can read the current keyboard buffer by calling keyboardBuffer(). See the keyboardBuffer() documentation for an example.

showKeyboard() top ↑

Syntax

showKeyboard()

This function enables keyboard input and displays the software keyboard if necessary. After calling showKeyboard(), keyboard events will be delivered to a global function keyboard( key ). The current keyboard buffer can be read with the keyboardBuffer() function.

Examples

function touched(touch) --Show keyboard when the screen is touched showKeyboard() end

hideKeyboard() top ↑

Syntax

hideKeyboard()

This function disables keyboard input and hides the software keyboard if necessary.

isKeyboardShowing() top ↑

Syntax

isKeyboardShowing()

This function returns whether the keyboard is currently active in the viewer.

Returns

true if the keyboard is showing, false if not

keyboardBuffer() top ↑

Syntax

buffer = keyboardBuffer()

This function reads the current keyboard buffer. Note that the keyboard buffer is cleared when the keyboard is shown.

Examples

function touched(touch) --Show keyboard when the screen is touched showKeyboard() end function draw() background(40,40,50) fill(255) textMode(CORNER) buffer = keyboardBuffer() _,bufferHeight = textSize(buffer) if buffer then text( buffer, 10, HEIGHT - 30 - bufferHeight ) end end

Returns

Contents of keyboard buffer as a string

BACKSPACE top ↑

Syntax

BACKSPACE

You can use this to check whether the key delivered to the global keyboard( key ) function was the backspace key..

Examples

function keyboard(key) -- Did the user press backspace? if key == BACKSPACE then -- Do something end end

Recording Video of Your Project

startRecording() top ↑

Syntax

startRecording()

This function initiates the video recording feature of Codea. To stop video recording use the stopRecording() function. This function is identical to pressing the video record button in the viewer interface. Do not call this function in your setup() function.

stopRecording() top ↑

Syntax

stopRecording()

Use this function to stop Codea's video recording feature and save the recorded video to the device's camera roll.

isRecording() top ↑

Syntax

isRecording()

Use this function to programatically determine whether Codea is currently recording the screen.

Returns

Boolean, whether Codea is recording the screen

Backing Types

backingMode( MODE ) top ↑

Syntax

backingMode( STANDARD|RETAINED )

Changes the backing mode of the viewer. The default, STANDARD, is the fastest drawing mode and may not preserve the contents of the previously drawn frame when setting up next frame.

Use the RETAINED backing mode to force the viewer to copy the contents of the previous frame into the current frame each time draw() is called. This is useful for projects that need to paint onto the screen and preserve the screen's contents, for example, painting or drawing applications.

mode

Either STANDARD or RETAINED

Examples

function setup() --Use a standard backing mode (default) backingMode( STANDARD ) end
function setup() --Use a retained backing mode backingMode( RETAINED ) end

RETAINED top ↑

Syntax

backingMode( RETAINED )

Use this value in backingMode() to set the viewer to draw with a retained backing mode. This forces the viewer to copy the contents of the previous frame into the current frame each time draw() is called. This is useful for projects that need to paint onto the screen and preserve the screen's contents, for example, painting or drawing applications.

Viewer Actions

close() top ↑

Syntax

close()

Closes the viewer and returns to the editor. Calling close() is functionally the same as pressing the on-screen Back button. This function is useful if you are using displayMode() with the FULLSCREEN_NO_BUTTONS mode

Examples

function touched(touch) --Exit if user taps if touch.tapCount == 1 and touch.state == ENDED then close() end end

restart() top ↑

Syntax

restart()

Restarts the viewer, starting your project again. Calling restart() is functionally the same as pressing the on-screen Restart button. You can use this function to restart your game, for example.

Examples

function touched(touch) --Restart if user taps if touch.tapCount == 1 and touch.state == ENDED then restart() end end

alert() top ↑

Syntax

alert( message )
alert( message, title )

Brings up a system alert view. The message parameter specifies the message to display. The optional title parameter provides the title of the alert view. If no title is specified, the title "Alert" is used.

message

string, message to display

title

string, title of alert view

Examples

function touched(touch) --Show alert if user taps if touch.tapCount == 1 and touch.state == ENDED then alert( "Hello World" ) end end