widget.newScrollView()

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 visible (on screen) width and height of the scroll view.

scrollWidth, scrollHeight _^(optional)

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. Note that these values automatically update when you insert objects into the scroll view.

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.

isBounceEnabled _^(optional)

Boolean. If set to false, the bounce effect at the limits of the scrolling will be disabled. Default is true.

listener _^(optional)

Listener. The function used to listen for ScrollViewWidget motion/scroll events. In this listener function, event.phase returns the expected touch interaction phases of "began", "moved", or "ended". In addition, a "stopped" phase can be detected when the scroll view flick/swipe momentum naturally comes to a stop. Finally, 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.

object:getContentPosition()

object:getView()

object:scrollToPosition()

object:scrollTo()

object:setIsLocked()

object:setScrollWidth()

object:setScrollHeight()

object:takeFocus()

object:setSize()

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. 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.

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 bottom limit" )
        elseif ( event.direction == "down" ) then print( "Reached top limit" )
        elseif ( event.direction == "left" ) then print( "Reached right limit" )
        elseif ( event.direction == "right" ) then print( "Reached left 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 + 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 bottom limit" )
        elseif ( event.direction == "down" ) then print( "Reached top limit" )
        elseif ( event.direction == "left" ) then print( "Reached right limit" )
        elseif ( event.direction == "right" ) then print( "Reached left 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 )