widget-v1.lua

--****************************************************************************************
--
-- ====================================================================
-- Corona SDK Widget Module
-- ====================================================================
--
-- File: widget.lua
--
-- Copyright © 2013 Corona Labs Inc. All Rights Reserved.
--
-- Redistribution and use in source and binary forms, with or without
-- modification, are permitted provided that the following conditions are met:
--
--    * Redistributions of source code must retain the above copyright
--      notice, this list of conditions and the following disclaimer.
--    * Redistributions in binary form must reproduce the above copyright
--      notice, this list of conditions and the following disclaimer in the
--      documentation and/or other materials provided with the distribution.
--    * Neither the name of the company nor the names of its contributors
--      may be used to endorse or promote products derived from this software
--      without specific prior written permission.
--
-- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-- ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-- WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-- DISCLAIMED. IN NO EVENT SHALL CORONA LABS INC. BE LIABLE FOR ANY
-- DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-- (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-- LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-- ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
--
--****************************************************************************************

local modname = ...
local widget = {}
package.loaded[modname] = widget
widget.version = "0.7"

-- cached locals
local mAbs = math.abs
local mFloor = math.floor

-- defaults
local scrollFriction = 0.935
local pickerFriction = 0.88

-- modify factory function to ensure widgets are properly cleaned on group removal
local cached_displayNewGroup = display.newGroup
function display.newGroup()
	local g = cached_displayNewGroup()
	
	-- function to find/remove widgets within group
	local function removeWidgets( group )
		if group.numChildren then
			for i=group.numChildren,1,-1 do
				if group[i]._isWidget then
					group[i]:removeSelf()
				
				elseif not group[i]._isWidget and group[i].numChildren then
					-- nested group (that is not a widget)
					removeWidgets( group[i] )
				end
			end
		end
	end
	
	-- store reference to original removeSelf method
	local cached_removeSelf = g.removeSelf
	
	-- subclass removeSelf method
	function g:removeSelf()
		removeWidgets( self )	-- remove widgets first
		
		-- continue removing group as usual
		if self.parent and self.parent.remove then
			self.parent:remove( self )
		end
	end
	return g
end

-- set current theme from external .lua module
function widget.setTheme( themeModule )
	widget.theme = require( themeModule )	-- should return table w/ theme data
end

-- add 'setText()' method to display.newText (to be consistent with display.newEmbossed text)
local cached_newText = display.newText
function display.newText( ... )
	local text = cached_newText( ... )

	function text:setText( newString )
		self.text = newString
	end

	return text
end

-- creates very sharp text for high resolution/high density displays
function widget.retinaText( ... )
	text = display.newText( ... );
	return text
end; display.newRetinaText = display.newText --widget.retinaText

-- creates sharp (retina) text with an embossed/inset effect
function widget.embossedText( ... )
	local arg = { ... }
	
	-- parse arguments
	local parentG, w, h
	local argOffset = 0
	
	-- determine if a parentGroup was specified
	if arg[1] and type(arg[1]) == "table" then
		parentG = arg[1]; argOffset = 1
	end
	
	local string = arg[1+argOffset] or ""
	local x = arg[2+argOffset] or 0
	local y = arg[3+argOffset] or 0
	local w, h = 0, 0
	
	local newOffset = 3+argOffset
	if type(arg[4+argOffset]) == "number" then w = arg[4+argOffset]; newOffset=newOffset+1; end
	if w and #arg >= 7+argOffset then h = arg[5+argOffset]; newOffset=newOffset+1; end
	
	local font = arg[1+newOffset] or native.systemFont
	local size = arg[2+newOffset] or 12
	local color = { 0, 0, 0, 255 }
	
	---------------------------------------------
	
	local r, g, b, a = color[1], color[2], color[3], color[4]
	local textBrightness = ( r + g + b ) / 3
	
	local highlight = display.newText( string, 0.5, 1, w, h, font, size )
	if ( textBrightness > 127) then
		highlight:setTextColor( 255, 255, 255, 20 )
	else
		highlight:setTextColor( 255, 255, 255, 140 )
	end
	
	local shadow = display.newText( string, -0.5, -1, w, h, font, size )
	if ( textBrightness > 127) then
		shadow:setTextColor( 0, 0, 0, 128 )
	else
		shadow:setTextColor( 0, 0, 0, 20 )
	end
	
	local label = display.newText( string, 0, 0, w, h, font, size )
	label:setTextColor( r, g, b, a )
	
	-- create display group, insert all embossed text elements, and position it
	local text = display.newGroup()
	text:insert( highlight ); text.highlight = highlight
	text:insert( shadow ); text.shadow = shadow
	text:insert( label ); text.label = label
	text.x, text.y = x, y
	text:setReferencePoint( display.CenterReferencePoint )
	
	-- setTextColor method
	function text:setTextColor( ... )
		local r, g, b, a; local arg = { ... }
		
		if #arg == 4 then
			r = arg[1]; g = arg[2]; b = arg[3]; a = arg[4]
		elseif #arg == 3 then
			r = arg[1]; g = arg[2]; b = arg[3]; a = 255
		elseif #arg == 2 then
			r = arg[1]; g = r; b = r; a = arg[2]
		elseif #arg == 1 then
			if type(arg[1]) == "number" then
				r = arg[1]; g = r; b = r; a = 255
			end
		end
		
		local textBrightness = ( r + g + b ) / 3
		if ( textBrightness > 127) then
			self.highlight:setTextColor( 255, 255, 255, 20 )
			self.shadow:setTextColor( 0, 0, 0, 128 )
		else
			self.highlight:setTextColor( 255, 255, 255, 140 )
			self.shadow:setTextColor( 0, 0, 0, 20 )
		end
		self.label:setTextColor( r, g, b, a )
	end
	
	-- setText method
	function text:setText( newString )
		local newString = newString or self.text
		self.highlight.text = newString
		self.shadow.text = newString
		self.label.text = newString
		self.text = newString
	end
	
	-- setSize method
	function text:setSize ( newSize )
		local newSize = newSize or size
		self.highlight.size = newSize
		self.shadow.size = newSize
		self.label.size = newSize
		self.size = newSize
	end
	
	if parentG then parentG:insert( text ) end
	text.text = string
	return text
end; display.newEmbossedText = widget.embossedText

-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------
--
-- button widget
--
-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------

function widget.newButton( options )
	
	local function onButtonTouch( self, event )	-- self == button
		local result = true
		local phase = event.phase
		event.name = "buttonEvent"
		event.target = self

		if phase == "began" then
			display.getCurrentStage():setFocus( self, event.id )
			self.isFocus = true

			event.phase = "press"
			if self.onEvent then
				result = self.onEvent( event )
			elseif self.onPress then
				result = self.onPress( event )
			end

			self.default.isVisible = false
			self.over.isVisible = true
			local r, g, b, a = self.label.color.over[1] or 0, self.label.color.over[2] or self.label.color.over[1], self.label.color.over[3] or self.label.color.over[1], self.label.color.over[4] or 255
			self.label:setTextColor( r, g, b, a )

		elseif self.isFocus then
			local bounds = self.contentBounds
			local x, y = event.x, event.y
			local isWithinBounds = bounds.xMin <= x and bounds.xMax >= x and bounds.yMin <= y and bounds.yMax >= y
			
			if phase == "moved" then
				if not isWithinBounds then
					self.default.isVisible = true
					self.over.isVisible = false

					local r, g, b, a = self.label.color.default[1] or 0, self.label.color.default[2] or self.label.color.default[1], self.label.color.default[3] or self.label.color.default[1], self.label.color.default[4] or 255
					self.label:setTextColor( r, g, b, a )
				else
					self.default.isVisible = false
					self.over.isVisible = true

					local r, g, b, a = self.label.color.over[1] or 0, self.label.color.over[2] or self.label.color.over[1], self.label.color.over[3] or self.label.color.over[1], self.label.color.over[4] or 255
					self.label:setTextColor( r, g, b, a )
				end

				if self.onEvent then
					result = self.onEvent( event )
				elseif self.onDrag then
					result = self.onDrag( event )
				end

			elseif phase == "ended" or phase == "cancelled" then
				if self.default and self.over then
					self.default.isVisible = true
					self.over.isVisible = false
					local r, g, b, a = self.label.color.default[1] or 0, self.label.color.default[2] or self.label.color.default[1], self.label.color.default[3] or self.label.color.default[1], self.label.color.default[4] or 255
					self.label:setTextColor( r, g, b, a )
				end
				
				-- trigger appropriate event listener if released within bounds of button
				if isWithinBounds then
					event.phase = "release"
					if self.onEvent then
						result = self.onEvent( event )
					elseif self.onRelease then
						result = self.onRelease( event )
					end
				end

				-- remove focus from button
				display.getCurrentStage():setFocus( self, nil )
				self.isFocus = false
			end
		end

		return result
	end
	
	local function setLabel( self, newLabel )	-- self == button
		if not newLabel then return; end
		
		if self.label.setText then
			self.label:setText( newLabel )
		else
			self.label.text = newLabel
		end
		
		-- re-center label on button
		self.label:setReferencePoint( display.CenterReferencePoint )
		self.label.x = (self.contentWidth*0.5) + self.label.xOffset
		self.label.y = (self.contentHeight*0.5) + self.label.yOffset
	end
	
	local function getLabel( self )
		return self.label.text
	end
	
	local function removeSelf( self )	-- self == button
		-- check to see if there is a clean method; if so, call it
		if self.clean then self:clean(); end
		
		-- remove all children of default and over
		if self.default and self.default.numChildren then
			for i=self.default.numChildren,1,-1 do
				display.remove( self.default.numChildren[i] )
			end
			display.remove( self.default )
		end
		
		if self.over and self.over.numChildren then
			for i=self.over.numChildren,1,-1 do
				display.remove( self.over.numChildren[i] )
			end
			display.remove( self.over )
		end
		
		-- remove label
		display.remove( self.label )
		
		-- remove button group
		self:cached_removeSelf()
	end
	
	local function createButton( options, theme )
		local	defaultBtnWidth = 124
		local	defaultBtnHeight = 42
		
		local 	options = options or {}
		local 	theme = theme or {}
		local	id = options.id or "widget_button"
		local	left = options.left or 0
		local	top = options.top or 0
		local	xOffset = options.xOffset or theme.xOffset or 0		-- offsets x value of the label text
		local	yOffset = options.yOffset or options.offset or theme.yOffset or theme.offset or 0		-- offsets y value of the label text
		local	label = options.label or ""
		local 	font = options.font or theme.font or native.systemFont
		local 	fontSize = options.fontSize or theme.fontSize or 14
		local	emboss = options.emboss or theme.emboss
		local	textFunction = display.newText; if emboss then textFunction = widget.embossedText; end
		local 	labelColor = options.labelColor or theme.labelColor or { default={ 0 }, over={ 255 } }
		local   onPress = options.onPress
		local 	onRelease = options.onRelease
		local 	onDrag = options.onDrag
		local 	onEvent = options.onEvent
		local 	default = options.default or theme.default
		local 	defaultColor = options.defaultColor or theme.defaultColor
		local	over = options.over or theme.over
		local 	overColor = options.overColor or theme.overColor
		local 	strokeColor = options.strokeColor or theme.strokeColor
		local 	strokeWidth = options.strokeWidth or theme.strokeWidth
		local 	cornerRadius = options.cornerRadius or theme.cornerRadius
		local 	width = options.width or theme.width
		local 	height = options.height or theme.height
		local 	sheet = options.sheet or theme.sheet
		local 	defaultIndex = options.defaultIndex or theme.defaultIndex
		local 	overIndex = options.overIndex or theme.overIndex
		local 	baseDir = options.baseDir or theme.baseDir or system.ResourceDirectory
		
		local button = display.newGroup()
		
		if default or sheet then

			-- user-provided image for default and over state
			if sheet and defaultIndex and width and height then
				-- image sheet option
				button.default = display.newImageRect( button, sheet, defaultIndex, width, height )
				button.default:setReferencePoint( display.TopLeftReferencePoint )
				button.default.x, button.default.y = 0, 0

				local over = overIndex or defaultIndex
				button.over = display.newImageRect( button, sheet, over, width, height )
				button.over:setReferencePoint( display.TopLeftReferencePoint )
				button.over.x, button.over.y = 0, 0

			elseif width and height then
				-- display.newImageRect() option (non)
				button.default = display.newImageRect( button, default, baseDir, width, height )
				button.default:setReferencePoint( display.TopLeftReferencePoint )
				button.default.x, button.default.y = 0, 0

				local over = over or default
				button.over = display.newImageRect( button, over, baseDir, width, height )
				button.over:setReferencePoint( display.TopLeftReferencePoint )
				button.over.x, button.over.y = 0, 0
			else
				-- display.newImage() option
				button.default = display.newImage( button, default, baseDir, true )
				button.default:setReferencePoint( display.TopLeftReferencePoint )
				button.default.x, button.default.y = 0, 0

				local over = over or default
				button.over = display.newImage( button, over, baseDir, true )
				button.over:setReferencePoint( display.TopLeftReferencePoint )
				button.over.x, button.over.y = 0, 0
				
				width, height = button.default.contentWidth, button.default.contentHeight
			end

			if defaultColor then
				if defaultColor[1] then
					button.default:setFillColor( defaultColor[1], defaultColor[2] or defaultColor[1], defaultColor[3] or defaultColor[1], defaultColor[4] or 255 )
				end
			end

			if overColor then
				if overColor[1] then
					button.over:setFillColor( overColor[1], overColor[2] or overColor[1], overColor[3] or overColor[1], overColor[4] or 255 )
				end
			end
		else
			-- no images; construct button using newRoundedRect
			if not width then width = defaultBtnWidth; end
			if not height then height = defaultBtnHeight; end
			if not cornerRadius then cornerRadius = 8; end

			button.default = display.newRoundedRect( button, 0, 0, width, height, cornerRadius )
			button.over = display.newRoundedRect( button, 0, 0, width, height, cornerRadius )

			if defaultColor and defaultColor[1] then
				button.default:setFillColor( defaultColor[1], defaultColor[2] or defaultColor[1], defaultColor[3] or defaultColor[1], defaultColor[4] or 255 )
			else
				button.default:setFillColor( 255 )
			end

			if overColor and overColor[1] then
				button.over:setFillColor( overColor[1], overColor[2] or overColor[1], overColor[3] or overColor[1], overColor[4] or 255 )
			else
				button.over:setFillColor( 128 )
			end

			if strokeColor and strokeColor[1] then
				button.default:setStrokeColor( strokeColor[1], strokeColor[2] or strokeColor[1], strokeColor[3] or strokeColor[1], strokeColor[4] or 255 )
				button.over:setStrokeColor( strokeColor[1], strokeColor[2] or strokeColor[1], strokeColor[3] or strokeColor[1], strokeColor[4] or 255 )
			else
				button.default:setStrokeColor( 0 )
				button.over:setStrokeColor( 0 )
			end

			if not strokeWidth then
				button.default.strokeWidth = 1
				button.over.strokeWidth = 1
			else
				button.default.strokeWidth = strokeWidth
				button.over.strokeWidth = strokeWidth
			end
		end
		button.over.isVisible = false	-- hide "down/over" state of button
		
		-- create the label
		if not labelColor then labelColor = {}; end
		if not labelColor.default then labelColor.default = { 0 }; end
		if not labelColor.over then labelColor.over = { 255 }; end
		local r, g, b, a = labelColor.default[1] or 0, labelColor.default[2] or labelColor.default[1], labelColor.default[3] or labelColor.default[1], labelColor.default[4] or 255

		button.label = textFunction( button, label, 0, 0, font, fontSize )
		button.label:setTextColor( r, g, b, a )
		button.label:setReferencePoint( display.CenterReferencePoint )
		button.label.x = (button.contentWidth * 0.5) + xOffset
		button.label.y = (button.contentHeight * 0.5) + yOffset
		button.label.color = labelColor
		button.label.xOffset = xOffset
		button.label.yOffset = yOffset
		
		-- set properties and methods
		button._isWidget = true
		button.id = id
		button.onPress = onPress
		button.onDrag = onDrag
		button.onRelease = onRelease
		button.onEvent = onEvent
		button.touch = onButtonTouch; button:addEventListener( "touch", button )
		button.cached_removeSelf = button.removeSelf
		button.removeSelf = removeSelf
		button.setLabel = setLabel
		button.getLabel = getLabel
		
		-- position the button
		button:setReferencePoint( display.TopLeftReferencePoint )
		button.x, button.y = left, top
		button:setReferencePoint( display.CenterReferencePoint )
		
		return button
	end
	
	-- this widget supports visual customization via themes
	local themeOptions
	if widget.theme then
		local buttonTheme = widget.theme.button
		
		if buttonTheme then
			if options and options.style then	-- style parameter optionally set by user
				
				-- for themes that support various "styles" per widget
				local style = buttonTheme[options.style]
				
				if style then themeOptions = style; end
			else
				-- if no style parameter set, use default style specified by theme
				themeOptions = buttonTheme
			end
		end
	end
	
	return createButton( options, themeOptions )
end

-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------
--
-- slider widget
--
-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------

function widget.newSlider( options )
	
	-- set slider value from 0 to 100
	local function setSliderValue( self, value )	-- self == slider
		-- make sure value is not less than 0 or greater than 100
		if value < 0 then
			value = 0
		elseif value > 100 then
			value = 100
		else
			value = mFloor( value )	-- round to the nearest whole number
		end
		
		local width = self.max - self.min
		
		-- calculate percentage based on slidable width
		local percent = value / 100
		
		-- move handle to new position
		local x = (width * percent) + self.min
		self.handle.x = x
		
		-- stretch fill image from left side to handle
		local fillScaleX = (self.handle.x - self.min) / self.fillWidth
		if fillScaleX <= 0 then fillScaleX = 0.1; end
		self.fill.xScale = fillScaleX
		
		-- update reference to value
		self.value = value
	end
	
	-- dispatch slider event
	local function dispatchSliderEvent( self )	-- self == slider
		if self.listener then
			local e = {}
			e.name = "sliderEvent"
			e.type = "sliderMoved"
			e.target = self
			e.value = self.value
			
			self.listener( e )
		end
	end
	
	-- slider touch event
	local function onSliderTouch( self, event )	-- self == slider
		if event.phase == "began" then
			display.getCurrentStage():setFocus( self )
			self.isFocus = true
			self:setReferencePoint( display.CenterReferencePoint )
			
			local sliderX = (self.contentBounds.xMin + (self.contentWidth*0.5))
			local x = event.x - sliderX
			local width = self.max - self.min
			local percent = mFloor(((( (width*0.5) + x) * 100) / width))
			self:setValue( percent )
			
			dispatchSliderEvent( self )
			
		elseif self.isFocus then
			local isWithinBounds = self.min <= event.x and self.max >= event.x
			
			if event.phase == "moved" then
				
				local sliderX = (self.contentBounds.xMin + (self.contentWidth*0.5))
				local x = event.x - sliderX
				local width = self.max - self.min
				local percent = mFloor(((( (width*0.5) + x) * 100) / width))
				self:setValue( percent )
				
				dispatchSliderEvent( self )
			
			elseif event.phase == "ended" or event.phase == "cancelled" then
				
				display.getCurrentStage():setFocus( nil )
				self.isFocus = nil
			end
		end
		
		return true
	end
	
	-- removeSelf() method for slider widget
	local function removeSelf( self )
		if self.clean and type(self.clean) == "function" then self:clean(); end
		
		if self.fill then self.fill:removeSelf(); self.fill = nil; end
		if self.handle then self.handle:removeSelf(); self.handle = nil; end
		self.fillWidth = nil
		self.value = nil
		
		self:cached_removeSelf()
	end
	
	local function createSlider( options, theme )
		local options = options or {}
		local theme = theme or {}
		local id = options.id or "widget_slider"
		
		local left = options.left or 0
		local top = options.top or 0
		local width = options.width or theme.width or 200
		local height = options.height or theme.height or 10
		local background = options.background or theme.background
		local handleImage = options.handle or theme.handle
		local handleWidth = options.handleWidth or theme.handleWidth
		local handleHeight = options.handleHeight or theme.handleHeight
		local leftImage = options.leftImage or theme.leftImage
		local leftWidth = options.leftWidth or theme.leftWidth or 16
		local fillImage = options.fillImage or theme.fillImage
		local fillWidth = options.fillWidth or theme.fillWidth or 2
		local cornerRadius = options.cornerRadius or theme.cornerRadius or 5
		local value = options.value or 50
		local listener = options.listener or options.callback
		local baseDir = options.baseDir or theme.baseDir or system.ResourceDirectory
		
		local fillColor = options.fillColor or theme.fillColor or {}
				fillColor[1] = fillColor[1] or 0
				fillColor[2] = fillColor[2] or 100
				fillColor[3] = fillColor[3] or 230
				fillColor[4] = fillColor[4] or 255
		
		local handleColor = options.handleColor or theme.handleColor or {}
				handleColor[1] = handleColor[1] or 189
				handleColor[2] = handleColor[2] or 189
				handleColor[3] = handleColor[3] or 189
				handleColor[4] = handleColor[4] or 255
		
		local handleStroke = options.handleStroke or theme.handleStroke or {}
				handleStroke[1] = handleStroke[1] or 143
				handleStroke[2] = handleStroke[2] or 143
				handleStroke[3] = handleStroke[3] or 143
				handleStroke[4] = handleStroke[4] or 255
		
		local bgFill = options.bgFill or theme.bgFill or {}
				bgFill[1] = bgFill[1] or 225
				bgFill[2] = bgFill[2] or 225
				bgFill[3] = bgFill[3] or 225
				bgFill[4] = bgFill[4] or 255
		
		local bgStroke = options.bgStroke or theme.bgStroke or {}
				bgStroke[1] = bgStroke[1] or 102
				bgStroke[2] = bgStroke[2] or 102
				bgStroke[3] = bgStroke[3] or 102
				bgStroke[4] = bgStroke[4] or 255
		
		-- construct slider widget based on provided parameters (or defaults)
		local slider = display.newGroup()
		local bg, leftSide, fill, handle
		
		if not background and not fillImage then		
			bg = display.newRoundedRect( slider, 0, 0, width, height, cornerRadius )
			bg.strokeWidth = 1
			bg:setStrokeColor( bgStroke[1], bgStroke[2], bgStroke[3], bgStroke[4] )
			bg:setFillColor( bgFill[1], bgFill[2], bgFill[3], bgFill[4] )
			
			leftSide = display.newRoundedRect( slider, 0, 0, leftWidth, height, cornerRadius )
			leftSide:setReferencePoint( display.CenterReferencePoint )
			leftSide:setFillColor( fillColor[1], fillColor[2], fillColor[3], fillColor[4] )
			
			fill = display.newRect( slider, leftWidth*0.5, 0, fillWidth, height )
			fill:setReferencePoint( display.CenterLeftReferencePoint )
			fill:setFillColor( fillColor[1], fillColor[2], fillColor[3], fillColor[4] )
		
		elseif background and fillImage then
			bg = display.newImageRect( slider, background, baseDir, width, height )
			bg:setReferencePoint( display.TopLeftReferencePoint )
			bg.x, bg.y = 0, 0
			
			fill = display.newImageRect( slider, fillImage, baseDir, fillWidth, height )
			fill:setReferencePoint( display.CenterLeftReferencePoint )
			fill.x, fill.y = leftWidth, height * 0.5
		else
			if background and not fillImage then
				print( "WARNING: You must also specify a fillImage when using a custom background with the slider widget." )
				return
			elseif fillImage and not background then
				print( "WARNING: You must specify a custom background when using a custom fillImage with the slider widget." )
				return
			end
		end
		
		slider.fill = fill
		slider.fillWidth = fillWidth
		
		if not handleImage or not handleWidth or not handleHeight then
			handle = display.newCircle( slider, width*0.5, height*0.5, height )
			handle:setReferencePoint( display.CenterReferencePoint )
			handle:setFillColor( handleColor[1], handleColor[2], handleColor[3], handleColor[4] )
			handle.strokeWidth = 1
			handle:setStrokeColor( handleStroke[1], handleStroke[2], handleStroke[3], handleStroke[4] )
		else
			handle = display.newImageRect( slider, handleImage, handleWidth, handleHeight )
			handle:setReferencePoint( display.CenterReferencePoint )
			handle.x, handle.y = width*0.5, height*0.5
		end
		slider.handle = handle
		
		-- properties and methods
		slider._isWidget = true
		slider.id = id
		slider.min = leftWidth*0.5
		slider.max = width - (leftWidth * 0.5)
		slider.setValue = setSliderValue
		slider.touch = onSliderTouch
		slider:addEventListener( "touch", slider )
		slider.listener = listener
		
		slider.cached_removeSelf = slider.removeSelf
		slider.removeSelf = removeSelf
		
		local fillScaleX = (handle.x - slider.min) / fillWidth
		fill.xScale = fillScaleX
		
		-- position the widget and set reference point to center
		slider.x, slider.y = left, top
		slider:setReferencePoint( display.CenterReferencePoint )
		
		-- set initial value
		slider:setValue( value )
		
		return slider
	end
	
	-- this widget supports visual customization via themes
	local themeOptions
	if widget.theme then
		local sliderTheme = widget.theme.slider
		
		if sliderTheme then
			if options and options.style then	-- style parameter optionally set by user
				
				-- for themes that support various "styles" per widget
				local style = sliderTheme[options.style]
				
				if style then themeOptions = style; end
			else
				-- if no style parameter set, use default style specified by theme
				themeOptions = sliderTheme
			end
		end
	end
	
	return createSlider( options, themeOptions )
end

-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------
--
-- pickerWheel widget
--
-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------

--Function to handle the soft-landing of the picker wheel
local function pickerSoftLand( self )
	local target = self.parent
	
	--Variables that equal the ones used in picker.getValues
	local height = self.height
	local selectionHeight = self.selectionHeight
	local top = self.parent.parent.parent.y --Get the actual pickers groups y position to use as the top position
	local selectionTop = target.topPadding
	
	--Index to scroll to							
	local index = nil
	
	--Get row using same system at picker.getValues uses
	if target:getRowAtCoordinate( top + selectionTop + ( selectionHeight * 0.5 ) ) ~= nil then
		index = target:getRowAtCoordinate( top + selectionTop + ( selectionHeight * 0.5 ) ).index
	end
	
	--If there is an index, scroll to it to give the impression of soft landing
	if index ~= nil then
		target:scrollToIndex( index, 400 )
	end
end

function widget.newPickerWheel( options )
	-- get selection values of pickerWheel columns (returns table)
	local function getValues( self )	-- self == pickerWheel
		local columnValues = {}
		local columns = self.columns
		local top = self.y
		local selectionTop = self.selectionTop or 255
		local selectionHeight = self.selectionHeight or 46
		
		--print( selectionTop)
						
		for i=1,columns.numChildren do
			local col = columns[i]
			local realSelectionY = top + selectionTop + (selectionHeight*0.5)
			local row = col:getRowAtCoordinate( realSelectionY )
						
			if row and row.value and row.index then
				columnValues[i] = {}
				columnValues[i].value = row.value
				columnValues[i].index = row.index
			end
		end
		
		return columnValues
	end
	
	
	-- creates new pickerWheel column
	local function newPickerColumn( pickerWheel, parentGroup, columnData, params )
		local column = widget.newTableView( params )
		
		-- create individual 'rows' for the column
		for i=1,#columnData do
			local labelX = 14
			local ref = display.CenterLeftReferencePoint
			
			if columnData.alignment and columnData.alignment ~= "left" then
				if columnData.alignment == "center" then
					labelX = params.width * 0.5
					ref = display.CenterReferencePoint
				elseif columnData.alignment == "right" then
					labelX = params.width - 14
					ref = display.CenterRightReferencePoint
				end
			end
			
			local function renderRow( event )
				local row = event.row
				local view = event.view
				local fc = params.fontColor
				
				local label = display.newText( columnData[i], 0, 0, params.font, params.fontSize )
				label:setTextColor( fc[1], fc[2], fc[3], fc[4] )
				label:setReferencePoint( ref )
				label.x = labelX
				label.y = row.height * 0.5
				
				row.value = columnData[i]
				view:insert( label )
			end
			
			
			column:insertRow{
				onRender = renderRow,
				width = params.width,
				height = params.rowHeight or 32,
				rowColor = params.bgColor or { 255, 255, 255, 255 },
				lineColor = params.bgColor or { 255, 255, 255, 255 },
				skipRender = true,
			}
		end
		
		parentGroup:insert( column )
		
		return column
	end
	
	-- subclassed removeSelf method for pickerWheel
	local function removeSelf( self )	-- self == pickerWheel
		-- check to see if there is a clean method; if so, call it
		if self.clean then self:clean(); end
		
		-- remove mask if it exists
		if self.mask then
			self.columns:setMask( nil )
			self.mask = nil
		end
		
		-- remove each column one by one
		for i=self.columns.numChildren,1,-1 do
			self.columns[i]:removeSelf()
		end
		self.columns = nil
				
		-- remove pickerWheel widget
		self:cached_removeSelf()
	end
	
	local function createPickerWheel( options, themeOptions )
		local options = options or {}
		local theme = themeOptions or {}

		-- parse parameters (options) or set defaults (or theme defaults)
		local id = options.id or "widget_pickerWheel"
		local left = options.left or 0
		local top = options.top or 0
		local width = options.width or theme.width or 296
		local height = options.height or theme.height or 222
		local bgWidth = options.bgWidth or options.totalWidth or theme.bgWidth or theme.totalWidth or display.contentWidth
		local selectionTop = options.selectionTop or theme.selectionTop or 90
		local selectionHeight = options.selectionHeight or theme.selectionHeight or 46
		local font = options.font or theme.font or system.nativeFontBold
		local fontSize = options.fontSize or theme.fontSize or 22
		local fontColor = options.fontColor or theme.fontColor or {}
			fontColor[1] = fontColor[1] or 0
			fontColor[2] = fontColor[2] or fontColor[1]
			fontColor[3] = fontColor[3] or fontColor[1]
			fontColor[4] = fontColor[4] or 255
		local columnColor = options.columnColor or theme.columnColor or {}
			columnColor[1] = columnColor[1] or 255
			columnColor[2] = columnColor[2] or columnColor[1]
			columnColor[3] = columnColor[3] or columnColor[1]
			columnColor[4] = columnColor[4] or 255
		local columns = options.columns or { { "One", "Two", "Three", "Four", "Five" } }
		local maskFile = options.maskFile or theme.maskFile
		local bgImage = options.bgImage or options.background or theme.bgImage or theme.background
		local bgImageWidth = options.bgImageWidth or options.backgroundWidth or theme.bgImageWidth or theme.backgroundWidth
		local bgImageHeight = options.bgImageHeight or options.backgroundHeight or theme.bgImageHeight or theme.backgroundHeight or height
		local overlayImage = options.overlayImage or options.glassFile or theme.overlayImage or theme.glassFile
		local overlayWidth = options.overlayWidth or options.glassWidth or theme.overlayWidth or theme.glassWidth
		local overlayHeight = options.overlayHeight or options.glassHeight or theme.overlayHeight or theme.glassHeight
		local separator = options.separator or theme.separator
		local separatorWidth = options.separatorWidth or theme.separatorWidth
		local separatorHeight = options.separatorHeight or theme.separatorHeight
		local baseDir = options.baseDir or theme.baseDir or system.ResourceDirectory
		
		local pickerWheel = display.newGroup()
		local columnGroup = display.newGroup()	-- will hold all column groups (tableViews)
		
		-- create background image
		if bgImage then
			local bg = display.newImageRect( pickerWheel, bgImage, baseDir, bgImageWidth, bgImageHeight )
			bg:setReferencePoint( display.TopLeftReferencePoint )
			bg.x, bg.y = 0, 0
			bg.xScale = bgWidth / bg.contentWidth
			
			local function disableTouchLeak() return true; end
			bg.touch = disableTouchLeak
			bg:addEventListener( "touch", bg )
		end
		
		-- insert the columns group into the pickerWheel widget group
		pickerWheel:insert( columnGroup )
		columnGroup.x = (bgWidth * 0.5) - width * 0.5
		columnGroup.y = 0
		
		local currentX = 0	-- variable that used for x-location of each column
		
		-- create all columns
		for i=1,#columns do
			local col = columns[i]
			
			-- set up tableView options (each column is a tableView widget)
			local params = {}
			-- tableView specific parameters
			params.id = "pickerColumn_" .. i
			params.renderThresh = (height - selectionTop) + selectionHeight
			params.left = 0
			params.top = 0
			params.topPadding = selectionTop
			params.bottomPadding = height - (selectionTop+selectionHeight)
			params.width = col.width or width/#columns
			params.height = height
			params.bgColor = columnColor
			params.friction = pickerFriction
			params.keepRowsPastTopVisible = true
			params.hideScrollBar = true
			
			--Used for controlling the pickers softlanding
			params.selectionHeight = selectionHeight
			params.isPicker = true
			params.pickerTop = top
			
			-- if last column, ensure width fills remaining space
			if i == #columns then params.width = width - currentX; end
			
			-- picker-specific parameters
			params.rowHeight = selectionHeight
			params.font = font
			params.fontSize = fontSize
			params.fontColor = fontColor
			
			-- create line separator that goes between the rows
			local separatorLine
			if separator and i ~= #columns then
				separatorLine = display.newImageRect( pickerWheel, separator, baseDir, separatorWidth, separatorHeight )
				separatorLine:setReferencePoint( display.TopLeftReferencePoint )
				separatorLine.x = (currentX + params.width) + columnGroup.x
				separatorLine.y = 0
				separatorLine.yScale = height / separatorLine.height
			end
			
			-- create the column
			local pickerColumn = newPickerColumn( pickerWheel, columnGroup, col, params )
			pickerColumn.x = currentX
			if #col <= 2 then pickerColumn.content.shortList = true; end
			
			currentX = currentX + params.width
			
			-- scroll to startIndex if specified
			if col.startIndex and col.startIndex > 1 then
				pickerColumn:scrollToIndex( col.startIndex )
			else
				pickerColumn:scrollToIndex( 1 )
			end
		end
		
		-- apply mask to columnGroup
		if maskFile then
			pickerWheel.mask = graphics.newMask( maskFile )
			columnGroup:setMask( pickerWheel.mask )
			columnGroup.maskX = columnGroup.width * 0.5
			columnGroup.maskY = height * 0.5
			columnGroup.isHitTestMasked = false
		end
		
		-- create overlay to go above columns
		if overlayImage then
			local overlay
			if overlayWidth and overlayHeight then
				overlay = display.newImageRect( pickerWheel, overlayImage, overlayWidth, overlayHeight )
			else
				overlay = display.newImage( pickerWheel, overlayImage, true )
			end
			overlay:setReferencePoint( display.CenterReferencePoint )
			overlay.x = bgWidth * 0.5
			overlay.y = height * 0.5
		end
		
		-- properties and methods
		pickerWheel._isWidget = true
		pickerWheel._isPicker = true
		pickerWheel.id = id
		pickerWheel.columns = columnGroup
		pickerWheel.getValues = getValues
		pickerWheel.selectionTop = selectionTop
		pickerWheel.cached_removeSelf = pickerWheel.removeSelf
		pickerWheel.removeSelf = removeSelf
		
		-- position the widget
		pickerWheel.x, pickerWheel.y = left, top
		
		return pickerWheel
	end
	
	-- this widget requires visual customization via themes to work properly
	local themeOptions
	if widget.theme then
		local pickerTheme = widget.theme.pickerWheel
		
		if pickerTheme then
			if options and options.style then	-- style parameter optionally set by user
				
				-- for themes that support various "styles" per widget
				local style = pickerTheme[options.style]
				
				if style then themeOptions = style; end
			else
				-- if no style parameter set, use default style specified by theme
				themeOptions = pickerTheme
			end
			
			return createPickerWheel( options, themeOptions )
		else
			print( "WARNING: The widget theme you are using does not support the pickerWheel widget." )
			return
		end
	else
		print( "WARNING: The pickerWheel widget requires a visual theme. Use widget.setTheme()." )
		return
	end
end

-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------
--
-- scrollView widget
--
-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------

function widget.newScrollView( options )
	local function dispatchBeganScroll( self, parent_widget ) 	-- self == content
		local e = {}
		e.name = "scrollEvent"
		e.type = "beganScroll"
		e.target = parent_widget or self.parent
		self.hasScrolled = false --Used to set whether the scrollview has actually being scrolled or just pressed
		if self.listener then self.listener( e ); end
	end
	
	local function dispatchEndedScroll( self )	-- self == content
		local e = {}
		e.name = "scrollEvent"
		e.type = "endedScroll"
		e.target = self.parent
		if self.listener then self.listener( e ); end
		--If the scrollbar isn't hidden
		if self.hideScrollBar == false then
			self.parent:hide_scrollbar()
		end
		
		
	end
	
	local function dispatchPickerSoftland( self )
		local e = {}
		e.target = self.parent
		
		--Make picker wheel softland
		if e.target._isPicker then
			pickerSoftLand( self )
		end
	end
	
	local function limitScrollViewMovement( self, upperLimit, lowerLimit )	-- self == content
		local function endedScroll()
			self.tween = nil
			if self.listener then
				--Dispatch the picker soft land
				dispatchPickerSoftland( self )
				
				--If the scrollview has scrolled then dispatch the ended scroll event ( this will trigger when the content has stopped moving )
				if self.hasScrolled == true then
					dispatchEndedScroll( self )
					self.hasScrolled = false
				end
			else
				--If the scrollbar isn't hidden
				if self.hideScrollBar == false then
					self.parent:hide_scrollbar()
				end
			end
		end
		
		local tweenContent = function( limit )
			if self.tween then transition.cancel( self.tween ); end
			if not self.isFocus then  -- if content is not being touched by user
				self.tween = transition.to( self, { time=400, y=limit, transition=easing.outQuad, onComplete=endedScroll } )
			end
			
			--If the scrollbar isn't hidden			
			if self.hideScrollBar == false then
				Runtime:addEventListener( "enterFrame", self.scrollbar_listener )
			end
		end
		local moveProperty = "y"
		local e = { name="scrollEvent", target=self.parent }
		local eventMin = "movingToTopLimit"
		local eventMax = "movingToBottomLimit"
		
		if self.moveDirection == "horizontal" then
			tweenContent = function( limit )
				if self.tween then transition.cancel( self.tween ); end
				self.tween = transition.to( self, { time=400, x=limit, transition=easing.outQuad, onComplete=endedScroll } )
			end
			moveProperty = "x"
			eventMin = "movingToLeftLimit"
			eventMax = "movingToRightLimit"
		end
		
		if self[moveProperty] > upperLimit then
	
			-- Content has drifted above upper limit of scrollView
			-- Stop content movement and transition back down to upperLimit
	
			self.velocity = 0
			Runtime:removeEventListener( "enterFrame", self )
			tweenContent( upperLimit )
			
			-- dispatch scroll event
			if self.listener then
				e.type = eventMin
				self.listener( e )
			end
	
		elseif self[moveProperty] < lowerLimit and lowerLimit < 0 then
	
			-- Content has drifted below lower limit (in case lower limit is above screen bounds)
			-- Stop content movement and transition back up to lowerLimit
	
			self.velocity = 0
			Runtime:removeEventListener( "enterFrame", self )
			tweenContent( lowerLimit )
			
			-- dispatch scroll event
			if self.listener then
				e.type = eventMax
				self.listener( e )
			end
			
		elseif self[moveProperty] < lowerLimit then
			
			-- Top of content has went past lower limit (in positive-y direction)
			-- Stop content movement and transition content back to upperLimit
			
			self.velocity = 0
			Runtime:removeEventListener( "enterFrame", self )
			if not self.shortList then
				tweenContent( upperLimit )
			else
				tweenContent( lowerLimit )
			end
			
			-- dispatch scroll event
			if self.listener then
				e.type = eventMin
				self.listener( e )
			end
		end
	end
	
	local function onScrollViewUpdate( self, event )	-- self == content
		if not self.trackVelocity then
			local time = event.time
			local timePassed = time - self.lastTime
			self.lastTime = time
	
			-- stop scrolling when velocity gets close to zero
			if mAbs( self.velocity ) < .01 then
				self.velocity = 0
				
				if self.moveDirection ~= "horizontal" then
					self.y = mFloor( self.y )
				
					-- if pulled past upper/lower boundaries, tween content properly
					limitScrollViewMovement( self, self.upperLimit, self.lowerLimit )
				else
					self.x = mFloor( self.x )
					
					-- if pulled past left/right boundaries, tween content properly
					limitScrollViewMovement( self, self.leftLimit, self.rightLimit )
				end
				
				self.moveDirection = nil
				Runtime:removeEventListener( "enterFrame", self )
				
				if self.listener then
					--Dispatch the pickers soft land
					dispatchPickerSoftland( self )
					
					-- dispatch an "endedScroll" event.type to user-specified listener
					--If the scrollview has scrolled then dispatch the ended scroll event ( this will trigger when the content has stopped moving )
					if self.hasScrolled == true then
						dispatchEndedScroll( self )
						self.hasScrolled = false
					end
				end

				-- self.tween is a transition that occurs when content is above or below lower limits
				-- and calls hide_scrollbar(), so the method does not need to be called here if self.tween exists
				if not self.tween then 
					--If the scrollbar isn't hidden
					if self.hideScrollBar == false then
						self.parent:hide_scrollbar(); 
					end
				end
			else
				-- update velocity and content location on every framestep
				local moveProperty = "y"
				if self.moveDirection == "horizontal" then moveProperty = "x"; end
				self.velocity = self.velocity * self.friction
				self[moveProperty] = self[moveProperty] + (self.velocity * timePassed)
				
				if moveProperty ~= "x" then
					limitScrollViewMovement( self, self.upperLimit, self.lowerLimit )
				else
					limitScrollViewMovement( self, self.leftLimit, self.rightLimit )
				end
			end
		else
			-- for timing how long user has finger held down
			if self.moveDirection == "vertical" then		
				if self.prevY == self.y then
					if self.eventStep > 5 then
						-- if finger is held down for 5 frames, ensure velocity is reset to 0
						self.prevY = self.y
						self.velocity = 0
						self.eventStep = 0
					else
						self.eventStep = self.eventStep + 1
					end
				end
			elseif self.moveDirection == "horizontal" then
				if self.prevX == self.x then
					if self.eventStep > 5 then
						-- if finger is held down for 5 frames, ensure velocity is reset to 0
						self.prevX = self.x
						self.velocity = 0
						self.eventStep = 0
					else
						self.eventStep = self.eventStep + 1
					end
				end
			end
		end

		--If the scrollbar isn't hidden
		if self.hideScrollBar == false then
			self.parent:update_scrollbar()
		end
	end
	
	local function onContentTouch( self, event )	-- self == content
		local scrollView = self.parent
		local phase = event.phase
		local time = event.time
		local hasScrolled = nil
		
		if phase == "began" then
			
			-- set focus on scrollView content
			display.getCurrentStage():setFocus( self )
			self.isFocus = true
			
			-- remove listener for auto-movement based on velocity
			Runtime:removeEventListener( "enterFrame", self )

			-- TODO: Restructure code into "transactions" that represent the different states
			-- of scrolling to "bottleneck" things like the following 'removeEventListener()' call
			-- so they are not sprinkled all over the place.

			Runtime:removeEventListener( "enterFrame", scrollView.content.scrollbar_listener )
			scrollView:cancel_scrollbar_hide()
			
			-- set some variables necessary movement/scrolling
			self.velocity = 0
			self.prevX = self.x
			self.prevY = self.y
			self.prevPositionX = event.x
			self.prevPositionY = event.y
			self.trackVelocity = true
			self.markTime = time
			self.eventStep = 0
			self.upperLimit = scrollView.topPadding or 0
			self.lowerLimit = self.maskHeight - self.contentHeight
			self.leftLimit = 0
			self.rightLimit = self.maskWidth - self.contentWidth
			
			-- determine whether or not to disable horizontal/vertical scrolling
			if self.contentWidth <= self.maskWidth or scrollView.isVirtualized then
				self.horizontalScrollDisabled = true
			end
			
			-- reset move direction
			self.moveDirection = nil
			
			-- for tableviews:
			if scrollView.isVirtualized then
				self.moveDirection = "vertical"
			end
			
			-- begin enterFrame listener (for velocity calculations)
			Runtime:addEventListener( "enterFrame", self )
			
			-- dispatch scroll event
			
			if self.listener then
				local event = event
				event.name = "scrollEvent"
				event.type = "contentTouch"
				event.phase = "press"
				event.target = scrollView
				self.listener( event )
			end
			
			
			-- change lowerLimit if scrollView is "virtualized" (used for tableViews)
			if scrollView.isVirtualized and scrollView.virtualContentHeight then
				self.lowerLimit = self.maskHeight - scrollView.virtualContentHeight
				if scrollView.bottomPadding then
					self.lowerLimit = self.lowerLimit - scrollView.bottomPadding
				end
			end
		
		elseif self.isFocus then
			if phase == "moved" and not scrollView.isLocked then
			
				-- ensure content isn't trying to move while user is dragging content
				if self.tween then transition.cancel( self.tween ); self.tween = nil; end
				
				-- determine if user is attempting to move content left/right or up/down
				if not self.moveDirection then
					if not self.verticalScrollDisabled or not self.horizontalScrollDisabled then
						local dx = mAbs(event.x - event.xStart)
						local dy = mAbs(event.y - event.yStart)
						local moveThresh = 8
						
						if dx > moveThresh or dy > moveThresh then
							if dx > dy then
								self.moveDirection = "horizontal"
							else
								self.moveDirection = "vertical"
							end
							
							--The content has actually started to scroll so dispatch the beganScroll event
							dispatchBeganScroll( self, scrollView )
							self.hasScrolled = true
						end
					end
				else
					
					-- Finger movement and swiping; prevent content from sticking past boundaries
					
					if self.moveDirection == "vertical" and not self.verticalScrollDisabled then
						-- VERTICAL movement
						
						self.delta = event.y - self.prevPositionY
						self.prevPositionY = event.y
						
						-- do "elastic" effect when finger is dragging content past boundaries
						if self.y > self.upperLimit or self.y < self.lowerLimit then
							self.y = self.y + self.delta/2
						else
							self.y = self.y + self.delta
						end
						
						-- modify velocity based on previous move phase
						--self.eventStep = 0
						self.velocity = (self.y - self.prevY) / (time - self.markTime)
						self.markTime = time
						self.prevY = self.y
					
					elseif self.moveDirection == "horizontal" and not self.horizontalScrollDisabled then
						-- HORIZONTAL movement
						
						self.delta = event.x - self.prevPositionX
						self.prevPositionX = event.x
						
						-- do "elastic" effect when finger is dragging content past boundaries
						if self.x > self.leftLimit or self.x < self.rightLimit then
							self.x = self.x + self.delta/2
						else
							self.x = self.x + self.delta
						end
						
						-- modify velocity based on previous move phase
						--self.eventStep = 0
						self.velocity = (self.x - self.prevX) / (time - self.markTime)
						self.markTime = time
						self.prevX = self.x
					end
				end
				
				-- dispatch scroll event 
				
				-- # NOTE # - 
				
				--[[
					If we can throttle this a bit the tableviews wouldn't appear to "jerk" when coming to a halt
				--]]
				if self.listener then
					local event = event
					event.name = "scrollEvent"
					event.type = "contentTouch"
					event.target = scrollView
					self.listener( event )
				end
				
			
			elseif phase == "ended" or phase == "cancelled" then
				
				self.lastTime = time		-- necessary for calculating scroll movement
				self.trackVelocity = nil	-- stop tracking velocity
				self.markTime = nil
				
				-- dispatch scroll event
				if self.listener then
					local event = event
					event.name = "scrollEvent"
					event.type = "contentTouch"
					event.phase = "release"
					event.target = scrollView
					self.listener( event )
				end
								
				-- remove focus from tableView's content
				display.getCurrentStage():setFocus( nil )
				self.isFocus = nil
			end
		end
	
		return true
	end
	
	local function onBackgroundTouch( self, event )
	
		-- This function allows scrollView to be scrolled when only the background of the
		-- widget is being touched (rather than having to touch the content itself)
	
		if event.phase == "began" then
			local content = self.parent.content
			content:touch( event )	-- transfer touch event to content group's touch event
		end
	end
	
	local function getContentPosition( self )
		local content = self.content
		return content.x, content.y
	end
	
	local function takeFocus( self, event )
		local target = event.target.view or event.target
		
		-- if button, restore back to "default" state
		if target.default and target.over then
			target.default.isVisible = true
			target.over.isVisible = false
			local r, g, b, a = target.label.color.default[1] or 0, target.label.color.default[2] or target.label.color.default[1], target.label.color.default[3] or target.label.color.default[1], target.label.color.default[4] or 255
			target.label:setTextColor( r, g, b, a )
		end
	
		-- remove focus from target
		display.getCurrentStage():setFocus( nil )
		target.isFocus = false
		
		-- set event.target to scrollView and start back at "began" phase
		event.target = self
		event.phase = "began"
		self.content.touch( self.content, event )
	end
	
	local function scrollToX( self, x, timeInMs, onComplete )	-- PRIVATE; self == scrollView
		local content = self.content
		if not self then print( "WARNING: The correct way to call scrollToX is with a ':' not a '.'" ); return; end
		if not x then return; end
		local time = timeInMs or 500
		
		if content.tween then transition.cancel( content.tween ); end
		content.tween = transition.to( content, { x=x, time=time, transition=easing.inOutQuad, onComplete=onComplete } )
	end
	
	local function scrollToY( self, y, timeInMs, onComplete )	-- PRIVATE; self == scrollView
		local content = self.content
		if not self then print( "WARNING: The correct way to call scrollToY is with a ':' not a '.'" ); return; end
		if not y then return; end
		local time = timeInMs or 500
		
		if content.tween then transition.cancel( content.tween ); end
		content.tween = transition.to( content, { y=y, time=time, transition=easing.inOutQuad, onComplete=onComplete } )
	end
	
	local function scrollToPosition( ... )
		local self, x, y, timeInMs, onComplete	-- self == scrollView
		
		if arg[1] and type(arg[1]) == "table" then
			self = arg[1]
		end
		
		self = arg[1]
		x = arg[2]
		y = arg[3]
		
		if arg[4] and type(arg[4]) == "number" then
			timeInMs = arg[4]
		elseif arg[4] and type(arg[4]) == "function" then
			onComplete = arg[4]
		end
		
		if arg[5] and type(arg[5]) == "function" then
			onComplete = arg[5]
		end
	
		if not self then print( "WARNING: The correct way to call scrollToPosition is with a ':' not a '.'" ); return; end
		if not x and not y then return; end
		if x and not y then
			scrollToX( self, x, timeInMs, onComplete )
		end
		
		if y and not x then
			scrollToY( self, y, timeInMs, onComplete )
		end
		
		if x and y then
			local content = self.content
			timeInMs = timeInMs or 500
			if content.tween then transition.cancel( content.tween ); end
			content.tween = transition.to( content, { x=x, y=y, time=timeInMs, transition=easing.inOutQuad, onComplete=onComplete } )
		end
	end
	
	local function scrollToTop( ... )
		local self, timeInMs, onComplete
		
		self = arg[1]
		if arg[2] and type(arg[2]) == "number" then
			timeInMs = arg[2]
		elseif arg[2] and type(arg[2]) == "function" then
			onComplete = arg[2]
		end
		
		if arg[3] and type(arg[3]) == "function" then
			onComplete = arg[3]
		end
		
		local content = self.content
		timeInMs = timeInMs or 500
		
		
		if content.tween then transition.cancel( content.tween ); end
		content.tween = transition.to( content, { y=0, time=timeInMs, transition=easing.inOutQuad, onComplete=onComplete } )
	end
	
	local function scrollToBottom( ... )
		local self, timeInMs, onComplete
		
		self = arg[1]
		if arg[2] and type(arg[2]) == "number" then
			timeInMs = arg[2]
		elseif arg[2] and type(arg[2]) == "function" then
			onComplete = arg[2]
		end
		
		if arg[3] and type(arg[3]) == "function" then
			onComplete = arg[3]
		end
		
		local content = self.content
		timeInMs = timeInMs or 500
		local lowerLimit = content.maskHeight - content.contentHeight
		
		if content.tween then transition.cancel( content.tween ); end
		content.tween = transition.to( content, { y=lowerLimit, time=timeInMs, transition=easing.inOutQuad, onComplete=onComplete } )
	end
	
	local function scrollToLeft( ... )
		local self, timeInMs, onComplete
		
		self = arg[1]
		if arg[2] and type(arg[2]) == "number" then
			timeInMs = arg[2]
		elseif arg[2] and type(arg[2]) == "function" then
			onComplete = arg[2]
		end
		
		if arg[3] and type(arg[3]) == "function" then
			onComplete = arg[3]
		end
		
		local content = self.content
		timeInMs = timeInMs or 500
		
		if content.tween then transition.cancel( content.tween ); end
		content.tween = transition.to( content, { x=0, time=timeInMs, transition=easing.inOutQuad, onComplete=onComplete } )
	end
	
	local function scrollToRight( ... )
		local self, timeInMs, onComplete
		
		self = arg[1]
		if arg[2] and type(arg[2]) == "number" then
			timeInMs = arg[2]
		elseif arg[2] and type(arg[2]) == "function" then
			onComplete = arg[2]
		end
		
		if arg[3] and type(arg[3]) == "function" then
			onComplete = arg[3]
		end
		
		local content = self.content
		timeInMs = timeInMs or 500
		local rightLimit = content.maskWidth - content.contentWidth
		
		if content.tween then transition.cancel( content.tween ); end
		content.tween = transition.to( content, { x=rightLimit, time=timeInMs, transition=easing.inOutQuad, onComplete=onComplete } )
	end
	
	local function removeSelf( self )
		-- check to see if there is a clean method; if so, call it
		if self.clean then self:clean(); end
		
		-- remove scrollView content
		if self.content then
			-- cancel any active transitions
			if self.content.tween then transition.cancel( self.content.tween ); self.content.tween = nil; end
			if self.sb_tween then transition.cancel( self.sb_tween ); self.sb_tween = nil; end
			if self.sb_timer then timer.cancel( self.sb_timer ); self.sb_timer = nil; end
			
			-- remove runtime listener
			Runtime:removeEventListener( "enterFrame", self.content )
			Runtime:removeEventListener( "enterFrame", self.content.scrollbar_listener )
			
			-- remove all children from content group
			for i=self.content.numChildren,1,-1 do
				display.remove( self.content[i] )
			end
			
			display.remove( self.content )
			self.content = nil
		end
		
		-- removed fixed (non scrollable) content
		if self.fixed then
			-- remove all children from fixed group
			for i=self.fixed.numChildren,1,-1 do
				display.remove( self.fixed[i] )
			end
			
			display.remove( self.fixed )
			self.fixed = nil
		end
		
		-- remove all children from virtual group
		if self.virtual then
			for i=self.virtual.numChildren,1,-1 do
				display.remove( self.virtual[i] )
			end
			
			display.remove( self.virtual )
			self.virtual = nil
		end
		
		-- remove bitmap mask
		if self.mask then
			self:setMask( nil )
			self.mask = nil
		end
		
		-- call original removeSelf method
		self:cached_removeSelf()
	end

	local function createScrollBar( parent, manual_height, options )
		-- set initial variables
		local fixed_group = parent.fixed
		local scrollbar_width = 6
		local top = 6
		local min_height = 24
		local max_height = parent.widgetHeight-(top*2)

		-- calculate scrollbar height (based on total content height)
		local sb_height
		local content_height = manual_height or parent.content.contentHeight
		local content_bleed = content_height - parent.widgetHeight

		if content_bleed > parent.widgetHeight then
			sb_height = min_height

		elseif content_bleed > 0 then

			local bleed_percent = content_bleed/parent.widgetHeight
			sb_height = max_height-(max_height*bleed_percent)

		else
			display.remove( parent._scrollbar ); parent._scrollbar = nil
			return
		end

		-- calculate proper location of scrollbar (in case a start_percent wasn't provided)
		local amount_above_top = content_height-(content_height+parent.content.y)
		local calculated_percent = (amount_above_top/content_bleed)

		-- calculate scrollbar height and handle "squish" effect when content goes past boundaries
		local min_y = top
		local max_y = (top+max_height)-sb_height
		local scroll_range = max_y-min_y
		local scroll_percent = calculated_percent
		local x = parent.widgetWidth-3
		local y = top+(scroll_range*scroll_percent)
		if y < min_y then
			local difference = min_y - y
			sb_height = sb_height - difference
			if sb_height < min_height then sb_height = min_height; end

			-- don't allow scrollbar to go past minimum y position (even when content goes past boundary)
			y = min_y

		elseif y > max_y then
			
			local difference = y - max_y
			sb_height = sb_height - difference
			if sb_height < min_height then sb_height = min_height; end

			-- adjust y position since we adjusted scrollbar height
			y = (top+max_height)-sb_height
		end

		-- create the actual scrollbar from a rounded rectangle
		local sb = parent._scrollbar
		if not sb then
			sb = display.newRoundedRect( fixed_group, 0, 0, scrollbar_width, sb_height, 2 )			
		else
			sb.height = sb_height
		end
		sb:setReferencePoint( display.TopRightReferencePoint )
		
		if options and options.scrollBarColor and type( options.scrollBarColor ) == "table" then
			sb:setFillColor( unpack( options.scrollBarColor ) )
		else	
			sb:setFillColor( 0, 128 )
		end
		
		sb.x, sb.y = x, y
		sb.alpha = 1.0

		return sb
	end
	
	local function createScrollView( options )
		-- extract parameters or use defaults
		local	options = options or {}
		local	id = options.id or "widget_scrollView"
		local	left = options.left or 0
		local	top = options.top or 0
		local	width = options.width or (display.contentWidth-left)
		local	height = options.height or (display.contentHeight-top)
		local	scrollWidth = options.scrollWidth or width
		local	scrollHeight = options.scrollHeight or height
		local	friction = options.friction or scrollFriction
		local	listener = options.listener
		local	bgColor = options.bgColor or {}
				bgColor[1] = bgColor[1] or 255
				bgColor[2] = bgColor[2] or bgColor[1]
				bgColor[3] = bgColor[3] or bgColor[1]
				bgColor[4] = bgColor[4] or 255
		local	maskFile = options.maskFile
		local	hideBackground = options.hideBackground
		local	isVirtualized = options.isVirtualized
		local	topPadding = options.topPadding
		local	bottomPadding = options.bottomPadding
		local 	baseDir = options.baseDir or system.ResourceDirectory
		
		--Picker (used in the pickers soft landing function)
		local 	isPicker = options.isPicker or nil
		local 	pickerTop = options.pickerTop or nil
		
		-- create display groups
		local scrollView = display.newGroup()	-- display group for widget; will be masked
		local content = display.newGroup()		-- will contain scrolling content
		local virtual = display.newGroup()		-- will contain "virtual" content (such as tableView rows)
		local fixed = display.newGroup()		-- will contain 'fixed' content (that doesn't scroll)
		scrollView:insert( content )
		scrollView:insert( virtual )
		scrollView:insert( fixed )
		
		-- important references
		scrollView.content = content
		scrollView.virtual = virtual
		scrollView.fixed = fixed
		
		-- set some scrollView properties (private properties attached to content group)
		scrollView._isWidget = true
		--Exposed variables for use with picker softlanding function
		scrollView._isPicker = isPicker
		scrollView.pickerTop = pickerTop
		----------------------------------
		scrollView.id = id
		scrollView.widgetWidth = width
		scrollView.widgetHeight = height
		scrollView.isVirtualized = isVirtualized
		scrollView.topPadding = topPadding
		scrollView.bottomPadding = bottomPadding
		content.hideScrollBar = options.hideScrollBar or false
		--Exposed for use with picker softlanding function
		content.selectionHeight = options.selectionHeight or nil
		content.maskWidth = width
		content.maskHeight = height
		content.friction = friction
		content.enterFrame = onScrollViewUpdate	-- enterFrame listener function
		content.touch = onContentTouch; content:addEventListener( "touch", content )
		content.listener = listener
		
		-- scrollView methods
		scrollView.getContentPosition = getContentPosition
		scrollView.takeFocus = takeFocus
		scrollView.scrollToPosition = scrollToPosition
		scrollView.scrollToTop = scrollToTop
		scrollView.scrollToBottom = scrollToBottom
		scrollView.scrollToLeft = scrollToLeft
		scrollView.scrollToRight = scrollToRight
		
		-- create background rectangle for widget
		local bgRect = display.newRect( 0, 0, width, height )
		bgRect:setFillColor( bgColor[1], bgColor[2], bgColor[3], bgColor[4] )
		if hideBackground then bgRect.isVisible = false; end
		bgRect.isHitTestable = true
		bgRect.touch = onBackgroundTouch; bgRect:addEventListener( "touch", bgRect )
		scrollView:insert( 1, bgRect )
		
		-- create a background for actual content
		local contentBg = display.newRect( 0, 0, scrollWidth, scrollHeight )
		contentBg:setFillColor( 255, 100 )
		contentBg.isVisible = false
		content:insert( 1, contentBg )
		
		-- apply mask (if user set option)
		if maskFile then
			scrollView.mask = graphics.newMask( maskFile, baseDir )
			scrollView:setMask( scrollView.mask )
	
			scrollView.maskX = width * 0.5
			scrollView.maskY = height * 0.5
			scrollView.isHitTestMasked = false
		end
	
		-- position widget based on left/top options
		scrollView:setReferencePoint( display.TopLeftReferencePoint )
		scrollView.x, scrollView.y = left, top
	
		-- override removeSelf method for scrollView (to ensure widget is properly removed)
		scrollView.cached_removeSelf = scrollView.removeSelf
		scrollView.removeSelf = removeSelf

		function scrollView.content.scrollbar_listener( event )
			scrollView:update_scrollbar()
		end
		
		-- override insert method for scrollView to insert into content instead
		scrollView.cached_insert = scrollView.insert
		function scrollView:insert( arg1, arg2 )
			local index, obj
			
			if arg1 and type(arg1) == "number" then
				index = arg1
			elseif arg1 and type(arg1) == "table" then
				obj = arg1
			end
			
			if arg2 and type(arg2) == "table" then
				obj = arg2
			end
			
			if index then
				self.content:insert( index, obj )
			else
				self.content:insert( obj )
			end
		end

		-- cancels scrollbar fadeout effect
		function scrollView:cancel_scrollbar_hide()
			if self.sb_tween then transition.cancel( self.sb_tween ); self.sb_tween = nil; end
			if self.sb_timer then timer.cancel( self.sb_timer ); self.sb_timer = nil; end
		end

		-- function to update scrollbar height and position
		function scrollView:update_scrollbar()
			local content_height = self.virtualContentHeight
			self._scrollbar = createScrollBar( self, content_height, options )
		end

		function scrollView:hide_scrollbar()
			Runtime:removeEventListener( "enterFrame", self.content.scrollbar_listener )
			self:cancel_scrollbar_hide()

			local function fade_out()
				local function remove_scrollbar()
					display.remove( self._scrollbar )
					self._scrollbar = nil
					self.sb_tween = nil
				end
				if self.sb_tween then
					transition.cancel( self.sb_tween ); self.sb_tween = nil;
					self._scrollbar.alpha = 1.0
				end
				self.sb_tween = transition.to( self._scrollbar, { time=300, alpha=0, onComplete=remove_scrollbar } )
			end
			self.sb_timer = timer.performWithDelay( 300, fade_out, 1 )
		end
		
		return scrollView	-- returns a display group
	end
	
	return createScrollView( options )
end

-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------
--
-- tabBar widget
--
-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------

function widget.newTabBar( options )
	
	local function invokeTabButtonSelectionState( button )
		-- ensure overlay and down graphic are showing
		button.up.isVisible = false
		button.down.isVisible = true
		button.selected = true
		if button.label then button.label:setTextColor( 255 ); end
		
		-- if hideOverlay is not set to true, show overlay graphic (to represent selection)
		if not button.hideOverlay then
			button.overlay.isVisible = true
		end
	end
	
	local function onButtonSelection( self )	-- self == tab button
		local tabBar = self.parent.parent
		
		if tabBar and tabBar.deselectAll then
			tabBar:deselectAll()	-- deselect all tab buttons
		end

		invokeTabButtonSelectionState( self )

		-- call listener function
		if self.onPress and type(self.onPress) == "function" then
			local event = {
				name = "tabButtonPress",
				target = self,
			}
			self.onPress( event )
		end
	end
	
	local function onButtonTouch( self, event )		-- self == tab button
		if event.phase == "began" then
			self:onSelection()	-- see: onButtonSelection()
		end
		return true
	end
	
	local function createTabButton( params )
		local	params = params or {}
		local	id = params.id
		local	label = params.label
		local	labelFont = params.font or native.systemFontBold
		local	labelFontSize = params.size or 10
		local	labelColor = params.labelColor or { 124, 124, 124, 255 }
		local	overlayWidth = params.overlayWidth
		local	overlayHeight = params.overlayHeight
		local	disableOverlay = params.disableOverlay
		local	width = params.width or 32		-- corresponds to up/down image width
		local	height = params.height or 32	-- corresponds to up/down image height
		local	cornerRadius = params.cornerRadius or 4
		local	default = params.default or params.up or params.image	-- params.default is supported; others old/deprecated
		local	down = params.down or params.over -- params.down is supported; others old/deprecated
		local	parentObject = params.parent
		local	selected = params.selected
		local	onPress = params.onPress
		local	upGradient = params.upGradient
		local	downGradient = params.downGradient
		local	baseDir = params.baseDir or system.ResourceDirectory

		local button = display.newGroup()
		button.id = id
		button.hideOverlay = disableOverlay
		
		-- create overlay (which is the highlight when button is selected/down)
		button.overlay = display.newRoundedRect( button, 0, 0, overlayWidth, overlayHeight, cornerRadius )
		button.overlay:setFillColor( 255, 25 )
		button.overlay:setStrokeColor( 0, 75 )
		button.overlay.strokeWidth = 1
		button.overlay.isVisible = false
		button.overlay.isHitTestable = true

		button.up = display.newImageRect( button, default, baseDir, width, height )
		button.up:setReferencePoint( display.CenterReferencePoint )
		button.up.x = button.overlay.width * 0.5
		button.up.y = button.overlay.height * 0.5

		if default and not down then down = default; end
		button.down = display.newImageRect( button, down, baseDir, width, height )
		button.down:setReferencePoint( display.CenterReferencePoint )
		button.down.x = button.up.x
		button.down.y = button.up.y
		button.down.isVisible = false

		if label then	-- label is optional
			-- shift icon up
			button.up.y = button.up.y - (labelFontSize-3)
			button.down.y = button.down.y - (labelFontSize-3)

			-- create label
			button.label = display.newText( label, 0, 0, labelFont, labelFontSize )
			local color = { labelColor[1] or 124, labelColor[2] or 124, labelColor[3] or 124, labelColor[4] or 255 }
			button.label:setTextColor( color[1], color[2], color[3], color[4] )
			button.label.color = color
			button.label:setReferencePoint( display.TopCenterReferencePoint )
			button.label.x = button.up.x
			button.label.y = button.up.y + (button.up.contentHeight*0.5)	-- button.up's reference point is center
			button:insert( button.label )
		end

		-- if selected, show overlay and 'down' graphic
		if selected then
			invokeTabButtonSelectionState( button )
		end

		-- touch event
		button.touch = onButtonTouch
		button:addEventListener( "touch", button )

		-- assign onPress event (user-specified listener function)
		button.onPress = onPress
		
		-- selection method to represent button visually and call listener
		button.onSelection = onButtonSelection

		return button
	end
	
	local function deselectAllButtons( self )	-- self == tabBar
		for i=1,self.buttons.numChildren do
			local button = self.buttons[i]

			button.overlay.isVisible = false
			button.down.isVisible = false
			button.up.isVisible = true
			button.selected = false
			if button.label then button.label:setTextColor( button.label.color[1], button.label.color[2], button.label.color[3], button.label.color[4] ); end
		end
	end
	
	local function pressButton( self, buttonIndex, invokeListener )		-- self == tabBar
		self:deselectAll()
		if invokeListener == nil then invokeListener = true; end
		
		local button = self.buttons[buttonIndex]
		if button then
			invokeTabButtonSelectionState( button )
			
			-- call listener function
			if invokeListener then
				if button.onPress and type(button.onPress) == "function" then
					local event = {
						name = "tabButtonPress",
						target = button
					}
					button.onPress( event )
				end
			end
		else
			print( "WARNING: Specified tab button '" .. buttonIndex .. "' does not exist." )
		end
	end
	
	local function removeSelf( self )	-- self == tabBar
		-- check to see if there is a clean method; if so, call it
		if self.clean then self:clean(); end
		
		-- remove all buttons
		for i=self.buttons.numChildren,1,-1 do
			display.remove( self.buttons[i] )
		end
		display.remove( self.buttons )
		
		-- remove gradient (if in use)
		if self.gradientRect then
			self.gradientRect:setFillColor( 0 )	-- so it's no longer using gradient image
			if self.gradient then
				self.gradient = nil
			end
		end
		
		-- remove tab bar widget itself
		self:cached_removeSelf()
	end
	
	local function createTabBar( options, theme )
		local options = options or {}
		local theme = theme or {}
		local id = options.id or "widget_tabBar"
		local buttons = options.buttons
		local maxTabWidth = options.maxTabWidth or 120
		local width = options.width or theme.width or display.contentWidth
		local height = options.height or theme.height or 50
		local background = options.background or theme.background
		local gradient = options.gradient or options.topGradient or theme.gradient	-- gradient must be pre-created using graphics.newGradient
		local topFill = options.topFill or theme.topFill
		local bottomFill = options.bottomFill or theme.bottomFill
		local left = options.left or 0
		local top = options.top or 0
		local baseDir = options.baseDir or system.ResourceDirectory
		
		local tabBar = display.newGroup()
		local barBg = display.newGroup(); tabBar:insert( barBg )
		
		local halfW = width * 0.5
		local halfH = height * 0.5
		
		-- create tab bar background
		if topFill and bottomFill then
			-- background made from two equal halves (2 different fills)
			
			topFill[1] = topFill[1] or 0
			topFill[2] = topFill[2] or topFill[1]
			topFill[3] = topFill[3] or topFill[1]
			topFill[4] = topFill[4] or 255
			
			bottomFill[1] = bottomFill[1] or 0
			bottomFill[2] = bottomFill[2] or bottomFill[1]
			bottomFill[3] = bottomFill[3] or bottomFill[1]
			bottomFill[4] = bottomFill[4] or 255
			
			local topRect = display.newRect( barBg, 0, 0, width, halfH )
			topRect:setFillColor( topFill[1], topFill[2], topFill[3], topFill[4] )
			
			local bottomRect = display.newRect( barBg, 0, halfH, width, halfH )
			bottomRect:setFillColor( bottomFill[1], bottomFill[2], bottomFill[3], bottomFill[4] )
		
		elseif gradient and type(gradient) == "userdata" then
			-- background made from rectangle w/ gradient fill
			
			local bg = display.newRect( barBg, 0, 0, width, height )
			bg:setFillColor( gradient )
			
			if bottomFill then
				bottomFill[1] = bottomFill[1] or 0
				bottomFill[2] = bottomFill[2] or bottomFill[1]
				bottomFill[3] = bottomFill[3] or bottomFill[1]
				bottomFill[4] = bottomFill[4] or 255
				
				local bottomRect = display.newRect( barBg, 0, halfH, width, halfH )
				bottomRect:setFillColor( bottomFill[1], bottomFill[2], bottomFill[3], bottomFill[4] )
			end
			
		elseif background and type(background) == "string" then
			-- background made from user-provided image file
			
			local bg = display.newImageRect( barBg, background, baseDir, width, height )
			bg:setReferencePoint( display.TopLeftReferencePoint )
			bg.x, bg.y = 0, 0
		else
			-- no background or fills specified (default)
			
			-- create a gradient background
			tabBar.gradient = graphics.newGradient( { 39 }, { 0 }, "down" )
			tabBar.gradientRect = display.newRect( barBg, 0, 0, width, height )
			tabBar.gradientRect:setFillColor( tabBar.gradient )
			
			-- create solid black rect for bottom half of background
			local bottomRect = display.newRect( barBg, 0, halfH, width, halfH )
			bottomRect:setFillColor( 0, 0, 0, 255 )
		end
		
		-- background created; create tab buttons
		
		tabBar.buttons = display.newGroup()
		tabBar:insert( tabBar.buttons )
		
		if buttons and type(buttons) == "table" then
			local buttonWidth = mFloor((width/#buttons)-4)
			local buttonHeight = height-4
			local buttonPadding = mFloor(width/buttonWidth)*2
			
			-- ensure button width doesn't exceed maxButtonWidth
			if buttonWidth > maxTabWidth then buttonWidth = maxTabWidth; end
			
			-- construct each button and insert into tabBar.buttons group
			for i=1,#buttons do
				buttons[i].id = buttons[i].id or i
				buttons[i].overlayWidth = buttonWidth
				buttons[i].overlayHeight = buttonHeight
				buttons[i].parent = tabBar

				local tab = createTabButton( buttons[i] )
				tab:setReferencePoint( display.TopLeftReferencePoint )
				tab.x = (buttonWidth*i-buttonWidth) + buttonPadding
				tab.y = 0
				tabBar.buttons:insert( tab )
			end
			
			-- center the 'tabBar.buttons' group on the widget
			tabBar.buttons:setReferencePoint( display.CenterReferencePoint )
			tabBar.buttons.x, tabBar.buttons.y = halfW, halfH
		end
		
		-- position the widget
		tabBar:setReferencePoint( display.TopLeftReferencePoint )
		tabBar.x, tabBar.y = left, top
		tabBar:setReferencePoint( display.CenterReferencePoint )
		
		-- prevent touches from going through tabBar background
		local preventTouches = function( self, event ) return true; end
		barBg.touch = preventTouches
		barBg:addEventListener( "touch", barBg )
		
		-- override removeSelf method to ensure widget is properly freed from memory
		tabBar.cached_removeSelf = tabBar.removeSelf
		tabBar.removeSelf = removeSelf
		
		-- additional tabBar methods and properties
		tabBar._isWidget = true
		tabBar.id = id
		tabBar.deselectAll = deselectAllButtons
		tabBar.makeTabActive = pressButton
		tabBar.pressButton = pressButton	-- to remain compatible with previous version
		
		return tabBar
	end
	
	-- this widget supports visual customization via themes
	local themeOptions
	if widget.theme then
		local tabBarTheme = widget.theme.tabBar
		
		if tabBarTheme then
			if options and options.style then	-- style parameter optionally set by user
				
				-- for themes that support various "styles" per widget
				local style = tabBarTheme[options.style]
				
				if style then themeOptions = style; end
			else
				-- if no style parameter set, use default style specified by theme
				themeOptions = tabBarTheme
			end
		end
	end
	
	return createTabBar( options, themeOptions )
end

-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------
--
-- tableView widget (based on scrollView widget)
--
-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------

function widget.newTableView( options )
	-- creates group for row, as well as a background and bottom-line
	local function newRowGroup( rowData )
		local row = display.newGroup()
		
		-- create background
		local bg = display.newRect( row, 0, 0, rowData.width, rowData.height )
		bg:setFillColor( rowData.rowColor[1], rowData.rowColor[2], rowData.rowColor[3], rowData.rowColor[4] )
		
		-- create bottom-line
		local line
		
		--Only create the line if the user hasn't specified noLines == true in options table.
		if options and not options.noLines == true or options and not options.noLines or options and options.noLines == false then
			line = display.newLine( row, 0, rowData.height, rowData.width, rowData.height )
			line:setColor( rowData.lineColor[1], rowData.lineColor[2], rowData.lineColor[3], rowData.lineColor[4] )
			row.line = line
		end
		
		row.background = bg
		
		--If the user has specified noLines == true then set row.line to nil
		if type( row.line ) ~= "table" then
			row.line = nil
		end
		
		return row
	end
	
	-- render row based on index in tableView.content.rows table
	local function renderRow( self, row )	-- self == tableView
		local content = self.content
		if row.view then row.view:removeSelf(); end
		row.view = newRowGroup( row )
		self.virtual:insert( row.view )
		
		row.view.x = 0
		row.view.y = row.top
		
		if row.onRender then
			-- set up event table
			local e = {}
			e.name = "tableView_rowRender"
			e.type = "render"
			e.parent = self	-- tableView that this row belongs to
			e.target = row
			e.row = row
			e.id = row.id
			e.view = row.view
			e.background = row.view.background
			e.line = row.view.line
			e.data = row.data
			e.phase = "render"		-- phases: render, press, release, swipeLeft, swipeRight
			e.index = row.index
			
			row.onRender( e )
		end
	end
	
	local function renderCategory( self, row )	-- self == tableView; row should be a table, not an index
		local content = self.content
		
		local newCategoryRender = function()
			if content.category then display.remove( content.category ); end
			
			content.category = newRowGroup( row )
			content.category.index = row.index
			content.category.x, content.category.y = 0, 0 ---row.height
			
			self.fixed:insert( content.category )	-- insert into tableView's 'fixed' group
			
			if row.onRender then
				-- set up event table
				local e = {}
				e.name = "tableView_rowRender"
				e.type = "render"
				e.parent = self	-- tableView that this row belongs to
				e.target = row
				e.row = row
				e.id = row.id
				e.view = content.category
				e.background = content.category.background
				e.line = content.category.line
				e.data = row.data
				e.phase = "render"		-- phases: render, press, release, swipeLeft, swipeRight
				e.index = row.index
				
				row.onRender( e )
			end
		end
		
		if not content.category then
			-- new; no category currently rendered
			newCategoryRender()
			
		else
			-- there is currently a category; render only if it's different
			if content.category.index ~= row.index then
				newCategoryRender()
			end
		end
	end
	
	-- renders row if it does not have a 'view' property (display group)
	local function ensureRowIsRendered( self, row )	-- self == tableView
		if not row.view then
			renderRow( self, row )
		else
			row.view.y = row.top
		end
	end
	
	-- render rows within the render range ( -renderThresh <-- widget height --> renderThresh )
	local function renderVisibleRows( self ) -- self == tableView			
		local content = self.content
		
		-- if widget has been removed during scrolling, be sure to remove certain enterFrame listeners
		if not content or not content.y then
			if content then Runtime:removeEventListener( "enterFrame", content ); end
			Runtime:removeEventListener( "enterFrame", self.rowListener )
			return
		end
		
		local currentCategoryIndex
		local rows = content.rows
		
		-- ensure all rows that are marked .isRendered are rendered	
		for i=1,#rows do
			local row = rows[i]
			-- update top/bottom locations
			row.top = content.y + row.topOffset
			row.bottom = row.top + row.height
			
			-- category "pushing" effect
			if content.category and row.isCategory and row.index ~= content.category.index then
				if row.top < content.category.contentHeight-3 and row.top >= 0 then
					-- push the category upward
					content.category.y = row.top - (content.category.contentHeight-3)
				end
			end
			
			-- determine which category should be rendered (sticky category at top)	
			if row.isCategory and row.top <= 0 then
				currentCategoryIndex = i
			
			elseif row.isCategory and row.top >= 0 and content.category and row.index == content.category.index then
				-- category moved below top of tableView, render previous category
				
				-- render the previous category, if this is not the first current category
				if row.index ~= content.firstCategoryIndex then
					currentCategoryIndex = content.categories["cat-" .. row.index]	-- stores reference to previous category index
				else
					-- remove current category if the first category moved below top of tableView
					if content.category then
						content.category:removeSelf()
						content.category = nil
						currentCategoryIndex = nil
					end
				end
			end
			
			-- check to see if row is within viewable area
			local belowTopThresh = row.bottom > -self.renderThresh
			local aboveBottomThresh = row.top < self.widgetHeight+self.renderThresh
			if belowTopThresh and aboveBottomThresh then
				row.isRendered = true
				
				-- ensures rows that are marked for rerendering and within render area get rendered
				if row.reRender then
					if row.view then row.view:removeSelf(); row.view = nil; end
					row.reRender = nil;
					row.isRendered = true
				end
				
				ensureRowIsRendered( self, row )
				
				-- hide row's view if it happens to be outside of viewable area; show it if in viewable bounds
				if row.bottom < 0 or row.top > self.widgetHeight then
					if row.view.isVisible then row.view.isVisible = false; end
				else
					if not row.view.isVisible then row.view.isVisible = true; end
				end
			else
				row.isRendered = false
				if row.view then row.view:removeSelf(); row.view = nil; end
			end

			-- hide row if it is the current category (category item will be rendered at top of widget)
			if row.index == currentCategoryIndex then
				if row.view then row.view.isVisible = false; end
			end
		end
		
		-- render current category
		if currentCategoryIndex then
			renderCategory( self, rows[currentCategoryIndex] )
		end
	end
	
	-- find the next row insert location (y-coordinate)
	local function getNextRowTop( content )
		local rows = content.rows
		local top, nextIndex = content.y, #rows+1
		
		local final = rows[#rows]
		if final then
			-- return final row's top location + its height
			top = final.top + final.height
		end
		
		return top, nextIndex	-- returns next 'top' coordinate, & the next avail. index
	end
	
	-- iterate through all rows and update row data (such as content offset, total height, category info, etc)
	local function updateRowData( self )	-- self == tableView
		local content = self.content
		local rows = content.rows
		local top = content.y
		local currentY = top
		local firstCategory
		local previousCategory
		local totalHeight = 0
		content.categories = {}
		
		for i=1,#rows do
			rows[i].topOffset = currentY - top
			
			-- update index while we're at it
			rows[i].index = i
			
			-- popuplate content.categories table
			if rows[i].isCategory then
				if not previousCategory then
					content.categories["cat-" .. i] = "first"
					previousCategory = i
				else
					content.categories["cat-" .. i] = previousCategory
					previousCategory = i
				end
				
				if not firstCategory then
					-- store reference to very first category index
					firstCategory = i
				end
			end
			local height = rows[i].height
			currentY = currentY + height + 1
			totalHeight = totalHeight + height + 1
		end
		
		-- make reference to first category
		content.firstCategoryIndex = firstCategory
		
		-- force re-calculation of top/bottom most rendered rows
		--self.topMostRendered = nil
		--self.bottomMostRendered = nil
		
		-- update total height of all rows
		self.virtualContentHeight = totalHeight
	end
	
	-- used to insert new rows into tableView.content.rows table
	local function insertRow( self, params )	-- self == tableView
		local row = {}
		row.id = params.id		-- custom id
		row.data = params.data	-- custom data
		row.width = self.content.maskWidth
		row.height = params.height or 56	-- default row height is 56
		row.isCategory = params.isCategory
		row.onEvent = params.listener or params.onEvent
		row.onRender = params.onRender
		local rowColor = params.rowColor or {}
			rowColor[1] = rowColor[1] or 255
			rowColor[2] = rowColor[2] or rowColor[1]
			rowColor[3] = rowColor[3] or rowColor[1]
			rowColor[4] = rowColor[4] or 255
		local lineColor = params.lineColor or {}
			lineColor[1] = lineColor[1] or 128
			lineColor[2] = lineColor[2] or lineColor[1]
			lineColor[3] = lineColor[3] or lineColor[1]
			lineColor[4] = lineColor[4] or 255
		row.rowColor = rowColor
		row.lineColor = lineColor
		row.top, row.index = getNextRowTop( self.content )
		row.isRendered = false	-- will ensure row gets rendered on next update
		
		-- increase renderThresh property of tableView if row height is larger
		-- renderThresh is the limit above and below widget where rendering occurs
		if row.height >= self.renderThresh then
			self.renderThresh = row.height + 10
		end
		
		-- insert as final item in tableView.content.rows table
		table.insert( self.content.rows, row )
		updateRowData( self )
		if not params.skipRender then renderVisibleRows( self ); end	-- refresh locations/rendering
	end
	
	-- finds rendered row at on-screen y-coordinate and returns the row object
	local function getRowAtCoordinate( self, yPosition )	-- self == tableView
		local top = self.y	-- y-coordinate of tableView, from top-left reference point
		local content = self.content
		--local firstRenderedRow = content.firstRenderedRow or 1
		local rows = content.rows
		local result
		
		for i=1,#rows do
			if rows[i].view then
				local viewBounds = rows[i].view.contentBounds
				local isWithinBounds = yPosition > viewBounds.yMin and yPosition < viewBounds.yMax
				
				-- if yPosition is within the row's view group, return this row
				if isWithinBounds then result = rows[i]; break; end
			end
		end
		
		return result
	end
	
	-- calls onEvent listener for row
	local function dispatchRowTouch( row, phase, parentWidget )
		if row.onEvent then
			-- set up event table
			local e = {}
			e.name = "tableView_rowTouch"
			e.type = "touch"
			e.parent = parentWidget	-- tableView that this row belongs to
			e.target = row
			e.row = row
			e.id = row.id
			e.view = row.view
			e.background = row.view.background
			e.line = row.view.line
			e.data = row.data
			e.phase = phase		-- phases: render, press, tap, release, swipeLeft, swipeRight
			e.index = row.index
			
			row.onEvent( e )
		end
	end
	
	--Function to invoke the users tableView listener if specified
	local function invokeUserListener( self, event ) --Self == tableView
		if self.userListener and type( self.userListener ) == "function" then
			if event.type == "beganScroll" then
				if self.hasScrolled == false then
					self.userListener( event )
					self.hasScrolled = true
				end
			elseif event.type == "endedScroll" then
				if self.hasScrolled == true then
					self.userListener( event )
					
					self.hasScrolled = false
				end
			else
				self.userListener( event )
			end
		end
	end
	
	
	-- listens to scrollView events for tableView
	local function scrollListener( event )
		local tableView = event.target
		local content = tableView.content
		local eType = event.type
		
		local moveRowsWithTween = function( self )	-- self == tableView
			local updateRows = function() renderVisibleRows( self ) end
			if self.rowTimer then timer.cancel( self.rowTimer ); end;
			self.rowTimer = timer.performWithDelay( 1, updateRows, 400 )
		end
		
		if eType == "contentTouch" then
			local tapThresh = 3		-- used to determine if touch was a "drag" or a quick tap
			local moveThresh = 10	-- do not allow swipes once user drags up/down past this amount
			local swipeThresh = 12	-- if finger moves left/right this amount, trigger swipe event
			
			if event.phase == "press" then
				
				-- tableView content has been touched
				
				if tableView.rowTimer then timer.cancel( tableView.rowTimer ); tableView.rowTimer = nil; end;
				Runtime:removeEventListener( "enterFrame", tableView.rowListener )
				
				-- find out which row the touch began on and store a reference to it
				tableView.currentSelectedRow = getRowAtCoordinate( tableView, event.y )
				tableView.renderFrameCount = 0
				tableView.renderFramePace = 0
				content.yDistance = 0
				content.canSwipe = true
				
				Runtime:addEventListener( "enterFrame", tableView.rowListener )
				content.trackRowSelection = true
				
			elseif event.phase == "moved" then
			
				--Dispatch contentTouch event
				event.type = "contentTouch"
				invokeUserListener( tableView, event )
				
				-- tableView content is being dragged
				local canDrag = content.canDrag
				local canSwipe = content.canSwipe
				local yDistance
				
				-- calculate distance traveled in y direction (only when needed)
				if not canDrag or canSwipe then
					yDistance = mAbs( event.y - event.yStart )
				end
				
				-- determine if this touch event could possibly be a "row tap"
				if not canDrag then
					if yDistance > tapThresh then
						content.yDistance = yDistance
						content.canDrag, canDrag = true, true
						content.trackRowSelection = nil
					end
				end
				
				-- determine whether y distance traveled is low enough to allow left/right swipes
				if canSwipe then
					if yDistance > moveThresh then
						canSwipe = nil
						content.canSwipe = nil
					end
				else
					local selectedRow = tableView.currentSelectedRow
					
					if selectedRow and selectedRow.isTouched then
						selectedRow.isTouched = false
						selectedRow.reRender = true
					end
					
					-- ensure rows move with drag
					renderVisibleRows( tableView )
				end
				
				-- left/right swipes
				local row = tableView.currentSelectedRow
				if row and canSwipe then
					local xDistance = event.x - event.xStart
					
					-- check to see if a "swipe" event should be dispatched
					if xDistance > swipeThresh then
						dispatchRowTouch( row, "swipeRight", tableView )
						row.isTouched = false
						row = nil
						tableView.currentSelectedRow = nil
						renderVisibleRows( tableView )
						content.velocity = 0
						content.trackRowSelection = false
					
						-- remove focus from tableView's content
						display.getCurrentStage():setFocus( nil )
						content.isFocus = nil
						
					elseif xDistance < -swipeThresh then
						dispatchRowTouch( row, "swipeLeft", tableView )
						row.isTouched = false
						row = nil
						tableView.currentSelectedRow = nil
						renderVisibleRows( tableView )
						content.velocity = 0
						content.trackRowSelection = false
					
						-- remove focus from tableView's content
						display.getCurrentStage():setFocus( nil )
						content.isFocus = nil
					end
				end
			
			elseif event.phase == "release" then
				
				local row = tableView.currentSelectedRow
				if row then
					if content.yDistance < tapThresh and content.trackRowSelection then
						-- user tapped tableView content (dispatch row release event)
						dispatchRowTouch( row, "tap", tableView )
						row.isTouched = nil
						row = nil
						tableView.currentSelectedRow = nil
					else
						if row and row.isTouched then
							dispatchRowTouch( row, "release", tableView )
							row.isTouched = nil
							row = nil
							tableView.currentSelectedRow = nil
							renderVisibleRows( tableView )
						end
					end
				end
				
				-- variables used during "moved" phase
				content.yDistance = nil
				content.canDrag = nil
				content.canSwipe = nil
				content.trackRowSelection = nil
				
				-- prevents categories from getting 'stuck' in the wrong position
				if content.category and content.category.y ~= 0 then content.category.y = 0; end
			end
		
		elseif eType == "movingToTopLimit" or eType == "movingToBottomLimit" then
			--Dispatch moving to top/bottom limit event
			invokeUserListener( tableView, event )
				
			-- prevents categories from getting 'stuck' in the wrong position
			if content.category and content.category.y ~= 0 then content.category.y = 0; end
			moveRowsWithTween( tableView )
		end
	end
	
	-- times how long finger has been held down on a specific row
	local function checkSelectionStatus( self, time )	-- self == tableView
		local content = self.content
		if content.trackRowSelection then
			local timePassed = time - content.markTime
				
			if timePassed > 110 then		-- finger has been held down for more than 100 milliseconds
				content.trackRowSelection = false
				
				-- initiate "press" event if a row is being touched
				local row = self.currentSelectedRow
				if row then
					row.isTouched = true
					dispatchRowTouch( row, "press", tableView )
				end
			end
		end
	end
	
	-- enterFrame listener for tableView widget
	local function rowListener( self, event )	-- self == tableView
		-- limit velocity to maximum amount (self.maxVelocity)
		local velocity = self.content.velocity
		if velocity < -self.maxVelocity then self.content.velocity = -self.maxVelocity; end
		if velocity > self.maxVelocity then self.content.velocity = self.maxVelocity; end
		
		--Dispatch began scroll event
		event.type = "beganScroll"
		invokeUserListener( self, event )
		
		local isTrackingVelocity = self.content.trackVelocity
		if not isTrackingVelocity then
			if self.content.velocity == 0 then
				--Dispatch endedScroll event
				event.type = "endedScroll"
				invokeUserListener( self, event )
				
				Runtime:removeEventListener( "enterFrame", self.rowListener )
			end
			-- prevents categories from getting 'stuck' in the wrong position
			local content = self.content
			if content.category and content.category.y ~= 0 then content.category.y = 0; end
			
			-- renderFramePace and renderFrameCount will skip rendering frames if velocity (list travel speed) is too high
			-- [[
			local velocity = mAbs( velocity )
			if velocity >= 4 then
				self.renderFramePace = 1
				
			elseif velocity >= 6 then
				self.renderFramePace = 2
			
			elseif velocity >= 8 then
				self.renderFramePace = 3
			
			elseif velocity >= 10 then
				self.renderFramePace = 4
				
			else
				self.renderFramePace = 0
			end
			
			if self.renderFrameCount >= self.renderFramePace then
				self.renderFrameCount = 0
				renderVisibleRows( self )
			else
				self.renderFrameCount = self.renderFrameCount + 1
			end
			--]]
			
			--renderVisibleRows( self )
		else
			-- check to see if current row should be selected
			checkSelectionStatus( self, event.time )
		end
	end
	
	-- force re-render of all rows
	local function forceReRender( self )	-- self == tableView
		local content = self.content
		local rows = content.rows
		
		--self.topMostRendered, self.bottomMostRendered = nil, nil
		for i=1,#rows do
			local r = rows[i]
			if r.view then r.view:removeSelf(); r.view = nil; end
			r.isRendered = nil
		end
	end
	
	-- find proper category in proportion to specific row being at very top of list
	local function renderProperCategory( self, rows, rowIndex )		-- self == tableView
		local categoryIndex
				
		if rows[rowIndex].isCategory then
			categoryIndex = rowIndex
		else
			-- loop backwards to find the current category
			for i=rowIndex,1,-1 do
				if rows[i].isCategory then
					categoryIndex = i
					break
				end
			end
		end
		
		-- category found; render it and return the index
		if categoryIndex then
			renderCategory( self, rows[categoryIndex] )
			return categoryIndex
		end
	end
	
	-- scroll content to specified y-position
	local function scrollToY( self, yPosition, timeInMs )		-- self == tableView
		yPosition = yPosition or 0
		timeInMs = timeInMs or 1500
				
		if yPosition > 0 and not self._isPicker then
			print( "WARNING: You must specify a y-value less than zero (negative) when using tableView:scrollToY()." )
			return
		end

		local content = self.content
		
		-- called once content is in desired location
		local function contentInPosition()
			local row = getRowAtCoordinate( self, self.y )
			if row then 
				renderProperCategory( self, content.rows, row.index )
			end
		end

		if timeInMs > 0 then
			local updateTimer
			local cancelUpdateTimer = function() timer.cancel( updateTimer ); updateTimer = nil; contentInPosition(); end
			if content.tween then transition.cancel( content.tween ); end
			content.tween = transition.to( content, { y=yPosition, time=timeInMs, transition=easing.outQuad, onComplete=cancelUpdateTimer } )
			local updateRows = function() renderVisibleRows( self ); end
			updateTimer = timer.performWithDelay( 1, updateRows, timeInMs )
		else
			content.y = yPosition
			forceReRender( self )
			renderVisibleRows( self )
			contentInPosition()
		end
	end
	
	-- scroll content to place specific row at top of tableView
	local function scrollToIndex( self, rowIndex, timeInMs )	-- self == tableView
		local content = self.content
		local rows = content.rows
		local padding = self.topPadding or 0
		local yPosition = -(rows[rowIndex].topOffset) + padding
		
		if yPosition then
			if timeInMs then
				scrollToY( self, yPosition, timeInMs )
			else
				content.y = yPosition
				forceReRender( self )
				renderVisibleRows( self )
				renderProperCategory( self, rows, rowIndex ) -- render the appropriate category
			end
		end
	end
	
	-- returns y-position of content
	local function getContentPosition( self )	-- self == tableView
		return self.content.y
	end

	-- clear all rows from tableview (method)
	local function deleteAllRows( self ) -- self == tableView
		local content = self.content
		local rows = content.rows

		for i=#rows,1,-1 do
			local r = rows[i]
			display.remove( r.view ); r.view = nil
			table.remove( rows, r.index )

			if r.isCategory and content.category then
				if content.category.index == r.index then
					display.remove( content.category )
					content.category = nil
				end
			end
		end
		self.content.rows = {}
	end
	
	-- permanently remove specified row from tableView
	local function deleteRow( self, rowOrIndex )	-- self == tableView
		local content = self.content
		local rows = content.rows
		local row
		
		-- function accepts row table or index integer
		if type(rowOrIndex) == "table" then
			row = rowOrIndex
		else
			row = rows[rowOrIndex]
		end
		
		if row then
			if row.isRendered then
				if row.view then display.remove( row.view ); row.view = nil; end
			end
			table.remove( content.rows, row.index )

			if row.isCategory and content.category then
				if content.category.index == row.index then
					display.remove( content.category )
					content.category = nil
				end
			end
		end
		
		updateRowData( self )
		renderVisibleRows( self )
	end
	
	-- cleanup function (automatically called prior to calling removeSelf)
	local function cleanTableView( self )	-- self == tableView
		-- remove tableView's enterframe listener
		Runtime:removeEventListener( "enterFrame", self.rowListener )
		self.rowListener = nil
		
		-- cancel any potentially active timers/transitions
		if self.rowTimer then timer.cancel( self.rowTimer ); self.rowTimer = nil; end
		if self.content and self.content.tween then
			transition.cancel( self.content.tween ); self.content.tween = nil
		end
		
		-- remove category object if it exists
		if self.content.category then
			self.content.category:removeSelf()
			self.content.category = nil
		end
	end
	
	local function createTableView( options )
		local options = options or {}
		
		-- tableView-specific parameters
		local	id = options.id or "widget_tableView"
		local	renderThresh = options.renderThresh or 100	-- px amount above and below to begin rendering rows
		
		-- shared scrollView parameters (if not specified will use scrollView defaults)
		local	left = options.left or 0
		local	top = options.top or 0
		local	width = options.width or (display.contentWidth-left)
		local	height = options.height or (display.contentHeight-top)
		local	scrollWidth = width
		local	scrollHeight = height
		local	friction = options.friction
		local	bgColor = options.bgColor
		local	maskFile = options.maskFile
		local	hideBackground = options.hideBackground
		local	keepRowsPastTopVisible = options.keepRowsPastTopVisible
		local	topPadding = options.topPadding
		local	bottomPadding = options.bottomPadding
		local	maxVelocity = options.maxVelocity or 10
		local 	baseDir = options.baseDir or system.ResourceDirectory
		local 	hideScrollBar = options.hideScrollBar or false
		local 	scrollBarColor = options.scrollBarColor
		local 	userListener = options.listener or nil
		
		--Picker - Variables used by the picker soft landing function
		local 	selectionHeight = options.selectionHeight or nil
		local 	isPicker = options.isPicker or false
		local 	pickerTop = options.pickerTop or nil
				
		-- tableView foundation is a scrollView widget
		local tableView = widget.newScrollView{
			id = id,
			left = left,
			top = top,
			width = width,
			height = height,
			scrollWidth = scrollWidth,
			scrollHeight = scrollHeight,
			friction = friction,
			bgColor = bgColor,
			maskFile = maskFile,
			hideBackground = hideBackground,
			listener = scrollListener,
			isVirtualized = true,
			topPadding = topPadding,
			bottomPadding = bottomPadding,
			baseDir = baseDir,
			hideScrollBar = hideScrollBar,
			scrollBarColor = scrollBarColor,
			selectionHeight = selectionHeight,
		}
		tableView.userListener = userListener;
		tableView.hasScrolled = false
		
		-- properties and methods
		tableView._isWidget = true
		--Variables exposed for picker soft landing function
		tableView._isPicker = isPicker
		tableView.pickerTop = pickerTop
		-------------------------------------
		function tableView.rowListener( event ) rowListener( tableView, event ); end
		tableView.content.rows = {}	-- holds row data
		tableView.insertRow = insertRow
		tableView.deleteRow = deleteRow
		tableView.deleteAllRows = deleteAllRows
		tableView.renderThresh = renderThresh
		tableView.scrollToY = scrollToY
		tableView.scrollToIndex = scrollToIndex
		tableView.getRowAtCoordinate = getRowAtCoordinate
		tableView.getContentPosition = getContentPosition
		tableView.keepRowsPastTopVisible = keepRowsPastTopVisible
		tableView.maxVelocity = maxVelocity
		tableView.renderFramePace = 0
		tableView.renderFrameCount = 0
		
		-- clean method will be called whenever 'removeSelf' is called
		tableView.clean = cleanTableView
		
		-- position the content based on 'topPadding' variable
		tableView.content.y = topPadding or 0
		
		return tableView
	end
	
	return createTableView( options )
end

-----------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------

return widget