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.

Orientation Support

Orientation Overview top ↑

Codea allows your projects to run in any orientation your device supports. However, you can limit supported orientations by using the supportedOrientations() function. You might want to do this if you only want your project to run in landscape mode, or if you want to make use of the accelerometer and do not want the user to inadvertently rotate the screen.

This function is not supported in Codea Scratchpad.

When the device orientation changes, Codea calls the global function orientationChanged( orientation ) and passes it the new orientation.

Examples

supportedOrientations(ANY) function setup() --Any orientation supported (default) end function orientationChanged( newOrientation ) -- This function gets called when -- the device orientation changes end

CurrentOrientation top ↑

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

supportedOrientations( ORIENTATION, ... ) top ↑

Syntax

supportedOrientations()
supportedOrientations( orient1, orient2, ... )

Use this function to tell Codea which orientations the viewer should support for your project. This function accepts a variable number of arguments, each one specifying an orientation you wish to support. If you call this function with no arguments it will return all the currently supported orientations.

Note that while you are allowed to call this function from within your setup() function, it is recommended that you call this function from outside your setup() function, as indicated by the above examples. This is because by the time setup() is executed the viewer has already assumed an orientation and will only lock into a new orientation once the device is rotated. If called in the global scope the viewer will be configured in advance to support the orientation(s) you desire.

orientation

Can be one of the following values:

ANY

PORTRAIT            
PORTRAIT_UPSIDE_DOWN            
PORTRAIT_ANY

LANDSCAPE_LEFT            
LANDSCAPE_RIGHT            
LANDSCAPE_ANY

Examples

supportedOrientations(PORTRAIT_ANY) function setup() --Only support portrait orientations end
supportedOrientations(LANDSCAPE_LEFT) function setup() --Only support landscape left orientation end

Returns

All the currently supported orientations if called with no arguments. Otherwise this function returns nothing.

ANY top ↑

Syntax

supportedOrientation( ANY )

Use this value in supportedOrientation() to allow the viewer to assume any orientation when the device is rotated.

PORTRAIT_ANY top ↑

Syntax

supportedOrientation( PORTRAIT_ANY )

Use this value in supportedOrientation() to allow the viewer to assume either of the two portrait orientations (PORTRAIT, PORTRAIT_UPSIDE_DOWN) when the device is rotated.

PORTRAIT top ↑

Syntax

supportedOrientation( PORTRAIT )

Use this value in supportedOrientation() to allow the viewer to assume the standard portrait orientation (home button at the bottom).

PORTRAIT_UPSIDE_DOWN top ↑

Syntax

supportedOrientation( PORTRAIT_UPSIDE_DOWN )

Use this value in supportedOrientation() to allow the viewer to assume an inverted portrait orientation (home button at the top).

LANDSCAPE_ANY top ↑

Syntax

supportedOrientation( LANDSCAPE_ANY )

Use this value in supportedOrientation() to allow the viewer to assume either of the two landscape orientations (LANDSCAPE_LEFT, LANDSCAPE_RIGHT) when the device is rotated.

LANDSCAPE_LEFT top ↑

Syntax

supportedOrientation( LANDSCAPE_LEFT )

Use this value in supportedOrientation() to allow the viewer to assume the landscape left orientation (home button on left).

LANDSCAPE_RIGHT top ↑

Syntax

supportedOrientation( LANDSCAPE_RIGHT )

Use this value in supportedOrientation() to allow the viewer to assume the 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