Class: Vedeu::Event

Inherits:
Object
  • Object
show all
Includes:
Model
Defined in:
lib/vedeu/events/event.rb

Overview

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 either included Vedeu in your class:

class SomeClassInYourApplication

include 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

or, you are prepared to use the ‘Vedeu` prefix:

class SomeClassInYourApplication

Vedeu.bind(:event_name) do
  # Not all events you define will have arguments; like methods.
  :do_stuff
end

Instance Attribute Summary collapse

Attributes included from Model

#repository

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Model

#demodulize, #deputy, #dsl_class, included, #store

Constructor Details

#initialize(name, options = {}, closure) ⇒ Event

Returns a new instance of Event.

Parameters:

  • name (Symbol)
  • options (Hash) (defaults to: {})
  • closure (Proc) —

    The code to be executed when the event is triggered.



119
120
121
122
123
124
125
126
127
 
# File 'lib/vedeu/events/event.rb', line 119

def initialize(name, options = {}, closure)
  @name         = name
  @options      = options
  @closure      = closure
  @deadline     = 0
  @executed_at  = 0
  @now          = 0
  @repository   = Vedeu.events
end

Instance Attribute Details

#closure ⇒ Object (readonly, private)

Returns the value of attribute closure.



159
160
161
 
# File 'lib/vedeu/events/event.rb', line 159

def closure
  @closure
end

#deadline ⇒ Object (private)

Returns the value of attribute deadline.



160
161
162
 
# File 'lib/vedeu/events/event.rb', line 160

def deadline
  @deadline
end

#executed_at ⇒ Object (private)

Returns the value of attribute executed_at.



160
161
162
 
# File 'lib/vedeu/events/event.rb', line 160

def executed_at
  @executed_at
end

#name ⇒ Object (readonly, private)

Returns the value of attribute name.



159
160
161
 
# File 'lib/vedeu/events/event.rb', line 159

def name
  @name
end

#now ⇒ Object (private)

Returns the value of attribute now.



160
161
162
 
# File 'lib/vedeu/events/event.rb', line 160

def now
  @now
end

Class Method Details

.bind(name, options = {}, &block) ⇒ TrueClass

Register an event by name with optional delay (throttling) which when triggered will execute the code contained within the passed block.

Examples:

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...T
.X...i...i...i...i...X...i...i...i...i...X...i...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...T
.i...i...i...i...i...i...i...X...i...i...i...i...i...i...X...i...i...i

Vedeu.bind(:my_debounced_event, { debounce: 0.7 })
  # ... some code here ...
end

Parameters:

  • name (Symbol) —

    The name of the event which will be triggered later.

  • options (Hash) (defaults to: {}) —

    The options to register the event with.

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

Options Hash (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.

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

Returns:

  • (TrueClass) 


84
85
86
87
88
 
# File 'lib/vedeu/events/event.rb', line 84

def bind(name, options = {}, &block)
  Vedeu.log(type: :event, message: "Binding: '#{name}'")

  new(name, options, block).bind
end

.event ⇒ TrueClass

Register an event by name with optional delay (throttling) which when triggered will execute the code contained within the passed block.

Examples:

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...T
.X...i...i...i...i...X...i...i...i...i...X...i...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...T
.i...i...i...i...i...i...i...X...i...i...i...i...i...i...X...i...i...i

Vedeu.bind(:my_debounced_event, { debounce: 0.7 })
  # ... some code here ...
end

Parameters:

  • name (Symbol) —

    The name of the event which will be triggered later.

  • options (Hash) —

    The options to register the event with.

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

Returns:

  • (TrueClass) 


89
90
91
92
93
 
# File 'lib/vedeu/events/event.rb', line 89

def bind(name, options = {}, &block)
  Vedeu.log(type: :event, message: "Binding: '#{name}'")

  new(name, options, block).bind
end

.register ⇒ TrueClass

Register an event by name with optional delay (throttling) which when triggered will execute the code contained within the passed block.

Examples:

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...T
.X...i...i...i...i...X...i...i...i...i...X...i...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...T
.i...i...i...i...i...i...i...X...i...i...i...i...i...i...X...i...i...i

Vedeu.bind(:my_debounced_event, { debounce: 0.7 })
  # ... some code here ...
end

Parameters:

  • name (Symbol) —

    The name of the event which will be triggered later.

  • options (Hash) —

    The options to register the event with.

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

Returns:

  • (TrueClass) 


90
91
92
93
94
 
# File 'lib/vedeu/events/event.rb', line 90

def bind(name, options = {}, &block)
  Vedeu.log(type: :event, message: "Binding: '#{name}'")

  new(name, options, block).bind
end

.trigger(name, *args) ⇒ Object

See Also:



109
110
111
 
# File 'lib/vedeu/events/event.rb', line 109

def self.trigger(name, *args)
  Vedeu::Trigger.trigger(name, *args)
end

.unbind(name) ⇒ Boolean Also known as: unevent

Unbind events from a named handler.

Parameters:

  • name (String)

Returns:

  • (Boolean) 


96
97
98
99
100
101
102
103
 
# File 'lib/vedeu/events/event.rb', line 96

def unbind(name)
  return false unless Vedeu.events.registered?(name)

  Vedeu.log(type: :event, message: "Unbinding: '#{name}")

  Vedeu.events.remove(name)
  true
end

Instance Method Details

#bind ⇒ Object

See Also:



130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/vedeu/events/event.rb', line 130

def bind
  if repository.registered?(name)
    collection     = repository.find(name)
    new_collection = collection.add(self)

  else
    new_collection = Vedeu::Events.new([self], nil, name)

  end

  repository.store(new_collection)

  true
end

#debounce ⇒ Fixnum|Float (private)

Return the amount of time in seconds to debounce the event by.

Returns:



264
265
266
 
# File 'lib/vedeu/events/event.rb', line 264

def debounce
  options[:debounce] || defaults[:debounce]
end

#debounce_expired? ⇒ Boolean (private)

Returns a boolean indicating whether the debounce has expired.

Returns:

  • (Boolean) 


216
217
218
219
220
221
222
 
# File 'lib/vedeu/events/event.rb', line 216

def debounce_expired?
  return true if set_executed > deadline

  Vedeu.log(type: :event, message: "Debouncing: '#{name}'")

  false
end

#debouncing? ⇒ Boolean (private)

Returns a boolean indicating whether debouncing is required for this event. Setting the debounce option to any value greater than 0 will enable debouncing.

Returns:

  • (Boolean) 


205
206
207
208
209
210
211
 
# File 'lib/vedeu/events/event.rb', line 205

def debouncing?
  set_time

  set_deadline unless has_deadline?

  options[:debounce] > 0
end

#defaults ⇒ Hash (private)

The default values for a new instance of this class.

Returns:

  • (Hash) 


285
286
287
288
289
290
 
# File 'lib/vedeu/events/event.rb', line 285

def defaults
  {
    delay:      0.0,
    debounce:   0.0,
  }
end

#delay ⇒ Fixnum|Float (private)

Return the amount of time in seconds to throttle the event by.

Returns:



271
272
273
 
# File 'lib/vedeu/events/event.rb', line 271

def delay
  options[:delay] || defaults[:delay]
end

#elapsed_time ⇒ Float (private)

Returns:

  • (Float) 


225
226
227
 
# File 'lib/vedeu/events/event.rb', line 225

def elapsed_time
  now - @executed_at
end

#execute(*args) ⇒ void (private)

This method returns an undefined value.

Execute the code stored in the event closure.

Parameters:

  • args — 


166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/vedeu/events/event.rb', line 166

def execute(*args)
  reset_deadline

  set_executed

  reset_time

  Vedeu.log(type: :event, message: "Triggering: '#{name}'")

  closure.call(*args)
end

#has_deadline? ⇒ Boolean (private)

Returns:

  • (Boolean) 


245
246
247
 
# File 'lib/vedeu/events/event.rb', line 245

def has_deadline?
  @deadline > 0
end

#options ⇒ Hash (private)

Combines the options provided at instantiation with the default values.

Returns:

  • (Hash) 


278
279
280
 
# File 'lib/vedeu/events/event.rb', line 278

def options
  defaults.merge!(@options)
end

#reset_deadline ⇒ Fixnum (private)

Returns:



250
251
252
 
# File 'lib/vedeu/events/event.rb', line 250

def reset_deadline
  @deadline = 0
end

#reset_time ⇒ Fixnum (private)

Returns:



240
241
242
 
# File 'lib/vedeu/events/event.rb', line 240

def reset_time
  @now = 0
end

#set_deadline ⇒ NilClass (private)

Returns:

  • (NilClass) 


255
256
257
258
259
 
# File 'lib/vedeu/events/event.rb', line 255

def set_deadline
  @deadline = now + debounce

  nil
end

#set_executed ⇒ Float (private)

Returns:

  • (Float) 


230
231
232
 
# File 'lib/vedeu/events/event.rb', line 230

def set_executed
  @executed_at = now
end

#set_time ⇒ Float (private)

Returns:

  • (Float) 


235
236
237
 
# File 'lib/vedeu/events/event.rb', line 235

def set_time
  @now = Time.now.to_f
end

#throttle_expired? ⇒ Boolean (private)

Returns a boolean indicating whether the throttle has expired.

Returns:

  • (Boolean) 


192
193
194
195
196
197
198
 
# File 'lib/vedeu/events/event.rb', line 192

def throttle_expired?
  return true if elapsed_time > delay

  Vedeu.log(type: :event, message: "Throttling: '#{name}'")

  false
end

#throttling? ⇒ Boolean (private)

Returns a boolean indicating whether throttling is required for this event. Setting the delay option to any value greater than 0 will enable throttling.

Returns:

  • (Boolean) 


183
184
185
186
187
 
# File 'lib/vedeu/events/event.rb', line 183

def throttling?
  set_time

  options[:delay] > 0
end

#trigger(*args) ⇒ void

This method returns an undefined value.

Triggers the event based on debouncing and throttling conditions.

Parameters:

  • args (Array) 


149
150
151
152
153
154
155
 
# File 'lib/vedeu/events/event.rb', line 149

def trigger(*args)
  return execute(*args) unless debouncing? || throttling?

  return execute(*args) if debouncing? && debounce_expired?

  return execute(*args) if throttling? && throttle_expired?
end