widget.newScrollView()

Type Function
Library widget.*
Return value ScrollViewWidget
Revision Current Public Release (2014.2189)
Keywords widget, scrollview, scrollbox, scrolling content
See also ScrollViewWidget

Overview

Creates a ScrollView object.

Gotchas

The ScrollView widget contains a mask which constrains its view to the defined width and height. There is a nested masking limit of three on all platforms, so be careful when nesting other masked objects inside a ScrollView. Other display objects that contain masks include display.newContainer, display.newText, display.newEmbossedText, widget.newTableView, and any other masked image, masked vector object, or masked display group.

The ScrollView widget does not support scaling.

Syntax

widget.newScrollView( options )

This function takes a single argument, options, which is a table that accepts the following parameters:

id (optional)

String. An optional identification string to assign to the scroll view. Default is widget_scrollView.

x / y (optional)

Numbers. Coordinates for the widget's x and y center point. These values will be overridden by left and top if those values are defined.

left / top (optional)

Numbers. The left and top position where the widget will be created. If specified, these values override the x and y parameters.

width / height (required)

Numbers. The width and height of the scroll view.

scrollWidth / scrollHeight (required)

Numbers. The width and height of the total scrollable content area. This can be changed after the scroll view widget has been created via the object:setScrollWidth() and object:setScrollHeight() methods.

friction (optional)

Number. Determines how fast the content travels when it is flicked. The default value is 0.972.

horizontalScrollDisabled (optional)

Boolean. If set to true, the scroll view will not scroll horizontally.

verticalScrollDisabled (optional)

Boolean. If set to true, the scroll view will not scroll vertically.

isLocked (optional)

Boolean. If set to true, the scroll view will be locked, meaning it cannot be scrolled.

listener (optional)

Listener. The function used to listen for ScrollView motion/scroll events. In this listener function, event.phase returns the expected touch interaction phases of "began", "moved", or "ended". In addition, the scroll limit in any direction can be detected by event.limitReached. If this occurs, event.direction returns the direction in which the scroll view was moving when the limit was reached.

Methods

Visual Options

backgroundColor (optional)

Table. Table containing the RGB+A background color setting. Default is white.

backgroundColor = { 0.8, 0.8, 0.8 }
hideBackground (optional)

Boolean. If true, the background of the scroll view will be hidden, but it still receives touches.

hideScrollBar (optional)

Boolean. If set to true, the scroll bar will not appear for the scroll view.

scrollBarOptions (optional)

Table. Table containing the image sheet specifications for a custom scroll bar. Customizing the scroll bar requires 3 frames from an image sheet. Each frame needs to be a square of equal size. These frames represent the top of the bar (red), the middle of the bar (green), and the bottom of the bar (yellow).

Inside the scrollBarOptions table, you must specify 4 required parameters: sheet, topFrame, middleFrame, and bottomFrame.

scrollBarOptions = {
    sheet = scrollBarSheet,  --reference to the image sheet
    topFrame = 1,            --number of the "top" frame
    middleFrame = 2,         --number of the "middle" frame
    bottomFrame = 3          --number of the "bottom" frame
}
topPadding / bottomPadding (optional)

Numbers. The number of pixels from the top and bottom of the scroll view at which the scrollable content area will stop when it reaches the top/bottom limits. The default value for both is 0.

leftPadding / rightPadding (optional)

Numbers. The number of pixels from the left and right of the scroll view at which the scrollable content area will stop when it reaches the left/right limits. The default value for both is 0.

Inserting Content

Because the scroll view is technically a display group, visual content can be added to or removed from a scroll view in the same manner as a standard display group. Please refer to the usage examples below.

Examples

Basic ScrollView
local widget = require( "widget" )

-- ScrollView listener
local function scrollListener( event )

    local phase = event.phase
    if ( phase == "began" ) then print( "Scroll view was touched" )
    elseif ( phase == "moved" ) then print( "Scroll view was moved" )
    elseif ( phase == "ended" ) then print( "Scroll view was released" )
    end

    -- In the event a scroll limit is reached...
    if ( event.limitReached ) then
        if ( event.direction == "up" ) then print( "Reached top limit" )
        elseif ( event.direction == "down" ) then print( "Reached bottom limit" )
        elseif ( event.direction == "left" ) then print( "Reached left limit" )
        elseif ( event.direction == "right" ) then print( "Reached right limit" )
        end
    end

    return true
end

-- Create the widget
local scrollView = widget.newScrollView
{
    top = 100,
    left = 10,
    width = 300,
    height = 400,
    scrollWidth = 600,
    scrollHeight = 800,
    listener = scrollListener
}

-- Create a image and insert it into the scroll view
local background = display.newImageRect( "assets/scrollimage.png", 768, 1024 )
scrollView:insert( background )
ScrollView with Custom Scroll Bar
local widget = require( "widget" )

-- ScrollView listener
local function scrollListener( event )

    local phase = event.phase
    if ( phase == "began" ) then print( "Scroll view was touched" )
    elseif ( phase == "moved" ) then print( "Scroll view was moved" )
    elseif ( phase == "ended" ) then print( "Scroll view was released" )
    end

    -- In the event a scroll limit is reached...
    if ( event.limitReached ) then
        if ( event.direction == "up" ) then print( "Reached top limit" )
        elseif ( event.direction == "down" ) then print( "Reached bottom limit" )
        elseif ( event.direction == "left" ) then print( "Reached left limit" )
        elseif ( event.direction == "right" ) then print( "Reached right limit" )
        end
    end

    return true
end

-- Create image sheet for custom scroll bar
local scrollBarOpt = {
    width = 20,
    height = 20,
    numFrames = 3,
    sheetContentWidth = 20,
    sheetContentHeight = 60
}
local scrollBarSheet = graphics.newImageSheet( "scrollBar.png", scrollBarOpt )

-- Create the widget
local scrollView = widget.newScrollView
{
    top = 100,
    left = 10,
    width = 300,
    height = 400,
    scrollWidth = 600,
    scrollHeight = 800,
    listener = scrollListener,
    scrollBarOptions = {
        sheet = scrollBarSheet,
        topFrame = 1,
        middleFrame = 2,
        bottomFrame = 3
    }
}

-- Create a image and insert it into the scroll view
local background = display.newImageRect( "assets/scrollimage.png", 768, 1024 )
scrollView:insert( background )