module Vedeu
module Events
# Contains all the logic of an event. Handles debouncing and
# throttling.
#
# Vedeu provides an event mechanism to facilitate the
# functionality of your application. The events are either Vedeu
# defined, ie. system events or user defined, ie. user events.
# User events allow you to orchestrate behaviour within your
# application, ie. the user presses a specific key,
# you trigger an event to make something happen. Eg. pressing 'p'
# instructs the player to play.
#
# Events described here assume that you have bound the events
# within your classes:
#
# class SomeClassInYourApplication
# Vedeu.bind(:event_name) do |arg1, arg2|
# # Things that should happen when the event is triggered;
# # these can be method calls or the triggering of another
# # event or events.
# end
#
# Vedeu.bind(:event_name) do
# # Not all events you define will have arguments; like
# # methods.
# :do_stuff
# end
#
class Event
include Vedeu::Repositories::Model
class << self
# Register an event by name with optional delay (throttling)
# which when triggered will execute the code contained within
# the passed block.
#
# @param name [Symbol] The name of the event to be triggered
# later.
# @param options [Hash<Symbol => void>] The options to
# register the event with.
# @option options :delay [Fixnum|Float] Limits the execution
# of the triggered event to only execute when first
# triggered, with subsequent triggering being ignored until
# the delay has expired.
# @option options :debounce [Fixnum|Float] Limits the
# execution of the triggered event to only execute once the
# debounce has expired. Subsequent triggers before debounce
# expiry are ignored.
# @param block [Proc] The event to be executed when triggered.
# This block could be a method call, or the triggering of
# another event, or sequence of either/both.
#
# @example
# Vedeu.bind :my_event do |some, args|
# # ... some code here ...
#
# Vedeu.trigger(:my_other_event)
# end
#
# T = Triggered, X = Executed, i = Ignored.
#
# 0.0.....0.2.....0.4.....0.6.....0.8.....1.0.....1.2.....1.4.....1.6.
# .T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T..
# .X...i...i...i...i...X...i...i...i...i...X...i...i...i...i...i...i..
#
# Vedeu.bind(:my_delayed_event, { delay: 0.5 })
# # ... some code here ...
# end
#
# T = Triggered, X = Executed, i = Ignored.
#
# 0.0.....0.2.....0.4.....0.6.....0.8.....1.0.....1.2.....1.4.....1.6.
# .T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T...T..
# .i...i...i...i...i...i...i...X...i...i...i...i...i...i...X...i...i..
#
# Vedeu.bind(:my_debounced_event, { debounce: 0.7 })
# # ... some code here ...
# end
#
# @return [TrueClass]
def bind(name, options = {}, &block)
Vedeu.log(type: :event, message: "Binding: '#{name.inspect}'".freeze)
new(name, block, options).bind
end
alias_method :event, :bind
alias_method :register, :bind
# Return a boolean indicating whether the named event is
# registered.
#
# @example
# Vedeu.bound?(:some_event)
#
# @param name [Symbol]
# @return [Boolean]
def bound?(name)
Vedeu.events.registered?(name) ||
Vedeu::Events::Aliases.registered?(name)
end
# Unbind events from a named handler.
#
# Removes all events associated with the given name.
#
# @example
# Vedeu.unbind(:some_event)
#
# @param name [Symbol]
# @return [Boolean]
def unbind(name)
return false unless Vedeu.bound?(name)
Vedeu.log(type: :event,
message: "Unbinding: '#{name.inspect}'".freeze)
Vedeu.events.remove(name)
true
end
extend Forwardable
def_delegators Vedeu::Events::Trigger,
:trigger
end # Eigenclass
# Returns a new instance of Vedeu::Events::Event.
#
# @param (see Vedeu::Events::Event.bind)
# @return [Vedeu::Events::Event]
def initialize(name, closure, options = {})
@name = name
@options = options
@closure = closure
@deadline = 0
@executed_at = 0
@now = 0
@repository = Vedeu.events
end
# @see Vedeu::Events::Event.bind
def bind
if repository.registered?(name)
new_collection = repository.find(name).add(self)
else
new_collection = Vedeu::Events::Collection.new([self], nil, name)
end
repository.store(new_collection)
true
end
# Triggers the event based on debouncing and throttling
# conditions.
#
# @param args [Array]
# @return [void]
def trigger(*args)
return execute(*args) unless debouncing? || throttling?
return execute(*args) if debouncing? && debounce_expired?
return execute(*args) if throttling? && throttle_expired?
end
protected
# @!attribute [r] closure
# @return [String]
attr_reader :closure
# @!attribute [r] name
# @return [String|Symbol]
attr_reader :name
private
# Execute the code stored in the event closure.
#
# @param args [void]
# @return [void]
def execute(*args)
@deadline = 0 # reset deadline
@executed_at = @now # set execution time to now
@now = 0 # reset now
message = "Triggering: '#{name.inspect}'"
if args.size > 1
message << " with #{args.inspect}"
elsif args.one?
message << " for #{args.first.inspect}"
end
Vedeu.log(type: :event, message: message.freeze)
closure.call(*args)
end
# Returns a boolean indicating whether throttling is required
# for this event. Setting the delay option to any value greater
# than 0 will enable throttling.
#
# @return [Boolean]
def throttling?
@now = Vedeu.clock_time
options[:delay] > 0
end
# Returns a boolean indicating whether the throttle has expired.
#
# @return [Boolean]
def throttle_expired?
return true if (@now - @executed_at) > delay
Vedeu.log(type: :event, message: "Throttling: '#{name.inspect}'".freeze)
false
end
# Returns a boolean indicating whether debouncing is required
# for this event. Setting the debounce option to any value
# greater than 0 will enable debouncing.
# Sets the deadline for when this event can be executed to a
# point in the future determined by the amount of debounce time
# left.
#
# @return [Boolean]
def debouncing?
@now = Vedeu.clock_time
@deadline = @now + debounce unless deadline?
options[:debounce] > 0
end
# Returns a boolean indicating whether the debounce has expired.
#
# @return [Boolean]
def debounce_expired?
return true if (@executed_at = @now) > @deadline
Vedeu.log(type: :event, message: "Debouncing: '#{name.inspect}'".freeze)
false
end
# Returns a boolean indicating whether this event has a
# deadline.
#
# @return [Boolean]
def deadline?
@deadline > 0
end
# Return the amount of time in seconds to debounce the event by.
#
# @return [Fixnum|Float]
def debounce
options[:debounce] || defaults[:debounce]
end
# Return the amount of time in seconds to throttle the event by.
#
# @return [Fixnum|Float]
def delay
options[:delay] || defaults[:delay]
end
# Combines the options provided at instantiation with the
# default values.
#
# @return [Hash<Symbol => void>]
def options
defaults.merge!(@options)
end
# The default values for a new instance of this class.
#
# @return [Hash<Symbol => void>]
def defaults
{
delay: 0.0,
debounce: 0.0,
}
end
end # Event
end # Events
# @!method bind
# @see Vedeu::Events::Event.bind
# @!method bound?
# @see Vedeu::Events::Event.bound?
# @!method unbind
# @see Vedeu::Events::Event.unbind
def_delegators Vedeu::Events::Event,
:bind,
:bound?,
:unbind
end # Vedeu