/spacey

-- Class: Tween

-- A tween transitions a property from one state to another

-- in in-game time. A tween instance is designed to manage

-- many of these transitions at once, in fact. In order for it

-- to work properly, it must receive update events, so it must

-- be added somewhere in the current view or app. If you are using

-- the <View> class, this is already done for you.

Tween = Sprite:extend{

	tweens = {},

	visible = false,

	active = false,

	solid = false,

	-- Property: easers

	-- These are different methods of easing a tween, and

	-- can be set via the ease property of an individual tween.

	-- They should be referred to by their key name, not the property

	-- (e.g. 'linear', no Tweener.easers.linear).

	-- See http://www.gizma.com/easing/ for details.

	easers =

	{

		linear = function (elapsed, start, change, duration)

			return change * elapsed / duration + start

		end,

		quadIn = function (elapsed, start, change, duration)

			elapsed = elapsed / duration

			return change * elapsed * elapsed + start

		end,

		quadOut = function (elapsed, start, change, duration)

			elapsed = elapsed / duration

			return - change * elapsed * (elapsed - 2) + start

		end,

		quadInOut = function (elapsed, start, change, duration)

			elapsed = elapsed / (duration / 2)

			if (elapsed < 1) then

				return change / 2 * elapsed * elapsed + start

			else

				elapsed = elapsed - 1

				return - change / 2 * (elapsed * (elapsed - 2) - 1) + start

			end

		end

	},

	-- Method: reverseForever

	-- A utility function; if set via <Promise.andAfter()> for an individual

	-- tween, it reverses the tween that just happened. Use this to get a tween

	-- to repeat back and forth indefinitely (e.g. to have something glow).

	reverseForever = function (tween, tweener)

		tween.to = tween.from

		tweener:start(tween.target, tween.property, tween.to, tween.duration, tween.ease):andThen(Tween.reverseForever)

	end,

	-- Method: reverseOnce

	-- A utility function; if set via <Promise.andAfter()> for an individual

	-- tween, it reverses the tween that just happened-- then stops the tween after that.

	reverseOnce = function (tween, tweener)

		tween.to = tween.from

		tweener:start(tween.target, tween.property, tween.to, tween.duration, tween.ease)

	end,

	-- Method: start

	-- Begins a tweened transition, overriding any existing tween.

	--

	-- Arguments:

	--		target - target object

	--		property - Usually, this is a string name of a property of the target object.

	--				   You may also specify a table of getter and setter methods instead,

	--				   i.e. { myGetter, mySetter }. In either case, the property or functions

	--				   must work with either number values, or tables of numbers.

	--		to - destination value, either number or color table

	--		duration - how long the tween should last in seconds, default 1

	--		ease - function name (in Tween.easers) to use to control how the value changes, default 'linear'

	--

	-- Returns:

	--		A <Promise> that is fulfilled when the tween completes. If the object is already

	--		in the state requested, the promise resolves immediately. The tween object returns two

	--		things to the promise: a table of properties about the tween that match the arguments initially

	--		passed, and a reference to the Tween that completing the tween.

	start = function (self, target, property, to, duration, ease)

		duration = duration or 1

		ease = ease or 'linear'

		local propType = type(property)

		if STRICT then

			assert(type(target) == 'table' or type(target) == 'userdata', 'target must be a table or userdata')

			assert(propType == 'string' or propType == 'number' or propType == 'table', 'property must be a key or table of getter/setter methods')

			if propType == 'string' or propType == 'number' then

				assert(target[property], 'no such property ' .. tostring(property) .. ' on target') 

			end

			assert(type(duration) == 'number', 'duration must be a number')

			assert(self.easers[ease], 'easer ' .. ease .. ' is not defined')

		end

		-- check for an existing tween for this target and property

		for i, existing in ipairs(self.tweens) do

			if target == existing.target and property == existing.property then

				if to == existing.to then

					return existing.promise

				else

					table.remove(self.tweens, i)

				end

			end

		end

		-- add it

		tween = { target = target, property = property, propType = propType, to = to, duration = duration, ease = ease }

		tween.from = self:getTweenValue(tween)

		tween.type = type(tween.from)

		-- calculate change; if it's trivial, skip the tween

		if tween.type == 'number' then

			tween.change = tween.to - tween.from

			if math.abs(tween.change) < NEARLY_ZERO then

				return Promise:new{ state = 'fulfilled', _resolvedWith = { tween, self } }

			end

		elseif tween.type == 'table' then

			tween.change = {}

			local skip = true

			for i, value in ipairs(tween.from) do

				tween.change[i] = tween.to[i] - tween.from[i]

				if math.abs(tween.change[i]) > NEARLY_ZERO then

					skip = false

				end

			end

			if skip then

				return Promise:new{ state = 'fulfilled', _resolvedWith = { tween, self } }

			end

		else

			error('tweened property must either be a number or a table of numbers, is ' .. tween.type)

		end

		tween.elapsed = 0

		tween.promise = Promise:new()

		table.insert(self.tweens, tween)

		self.active = true

		return tween.promise

	end,

	-- Method: status

	-- Returns how much time is left for a particular tween to run.

	--

	-- Arguments:

	--		target - target object

	--		property - name of the property being tweened, or getter

	--				   (as set in the orignal <start()> call)

	--

	-- Returns:

	--		Either the time left in the tween, or nil if there is

	--		no tween matching the arguments passed.

	status = function (self, target, property)

		for _, t in pairs(self.tweens) do

			if t.target == target then

				if t.property == property or (type(t.property) == 'table' and t.property[1] == property) then

					return t.duration - t.elapsed

				end

			end

		end

		return nil

	end,

	-- Method: stop

	-- Stops a tween. The promise associated with it will be failed.

	--

	-- Arguments:

	--		target - tween target

	-- 		property - name of property being tweened, or getter (as set in the original <start()> call); 

	--				   if omitted, stops all tweens on the target

	--

	-- Returns:

	--		nothing

	stop = function (self, target, property)

		local found = false

		for i, tween in ipairs(self.tweens) do

			if tween.target == target and (tween.property == property or

			   (type(tween.property) == 'table' and tween.property[1] == property) or

			   not property) then

			   	found = true

				tween.promise:fail('Tween stopped')

				table.remove(self.tweens, i)

			end

		end

		if STRICT and not found then

			local info = debug.getinfo(2, 'Sl')

			print('Warning: asked to stop a tween, but no active tweens match it (' ..

				  info.short_src .. ', line ' .. info.currentline .. ')')

		end

	end,

	update = function (self, elapsed)	

		for i, tween in ipairs(self.tweens) do

			self.active = true

			tween.elapsed = tween.elapsed + elapsed

			if tween.elapsed >= tween.duration then

				-- tween is completed

				self:setTweenValue(tween, tween.to)

				table.remove(self.tweens, i)

				tween.promise:fulfill(tween, self)

			else

				-- move tween towards finished state

				if tween.type == 'number' then

					self:setTweenValue(tween, self.easers[tween.ease](tween.elapsed,

									   tween.from, tween.change, tween.duration))

				elseif tween.type == 'table' then

					local now = {}

					for i, value in ipairs(tween.from) do

						now[i] = self.easers[tween.ease](tween.elapsed, tween.from[i],

														 tween.change[i], tween.duration)

					end

					self:setTweenValue(tween, now)

				end

			end

		end

		self.active = (#self.tweens > 0)

	end,

	getTweenValue = function (self, tween)

		if tween.propType == 'string' or tween.propType == 'number' then

			return tween.target[tween.property]

		else

			return tween.property[1](tween.target)

		end

	end,

	setTweenValue = function (self, tween, value)

		if tween.propType == 'string' or tween.propType == 'number' then

			tween.target[tween.property] = value

		else

			tween.property[2](tween.target, value)

		end

	end,

	__tostring = function (self)

		local result = 'Tween ('

		if self.active then

			result = result .. 'active, '

			result = result .. #self.tweens .. ' tweens running'

		else

			result = result .. 'inactive'

		end

		return result .. ')'

	end

}