Scroll Synchronization

When we have scrolling content, we frequently want some sort of visual indication of where we are within the context of that content, like a scrollbar. Storyboard doesn't dictate what type of visual presentation is used for this tracking, but we'll describe here how you might make a scrollbar using a simple fill render extension. This technique can be readily applied to any other visual representation and is demonstrated in the Scrollbar > Storyboard Sample as well as the Address Book Sample

The first thing that we want to consider is what information we want to convey to the user. For a simple scrollbar we will use a proportional measurement that represents the percentage that our y offset

    positionPercent = (-1 * objectYOffset) / (contentTotalHeight - objectHeight)                   

Here, we'll assumed a vertically scrolling list, but the same principle applies for horizontally scrolling. With this positionPercent we have a representation of where our viewport is with respect to the total content available.

In order to apply this formula to synchronize a scrollbar representation with the content as it scrolls, we need to have a notification of the scroll change. This can be accomplished by making an event association with a variable as described in the section called “Triggering Events on Variable Changes”. The variable that we want to bind an event to will be the internal variable grd_yoffset on the model object that we are scrolling.

With an event bound to an action, we might structure a synchronization function that might look something like the following:

-- Assume we are synchronizing a table named Layer.MyTable
function CBSyncScrollIndicator()
    -- These values could be cached, only yoffset would be changing normally
    local tableInfo = gre.get_table_attrs
    ("Layer.MyTable", "height", "yoffset", "rows")
    local cellInfo = gre.get_table_cell_attrs("Layer.MyTable", 1, 1, "height")
    local totalHeight = tableInfo.rows * cellInfo.height
    
    local positionPercent = (-1 * tablInfo.yoffset) / 
    (totalHeight - tableInfo.height)
    
    -- Now apply the position_percent to your scrollbar object
end