Class: Vedeu::Events::Event Private

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

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

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

Instance Attribute Summary collapse

Attributes included from Repositories::Model

#repository

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Repositories::Model

included, #store

Constructor Details

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Vedeu::Events::Event.

Parameters:

  • name (NilClass|Symbol|String) —

    The name of the model or target model to act upon. May default to ‘Vedeu.focus`.

  • options (Hash<Symbol => void>) (defaults to: {}) —

    The options to register the event with.

  • block (Proc) 


128
129
130
131
132
133
134
135
136
 
# File 'lib/vedeu/events/event.rb', line 128

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

Instance Attribute Details

#closure ⇒ String (readonly, protected)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (String) 


170
171
172
 
# File 'lib/vedeu/events/event.rb', line 170

def closure
  @closure
end

#name ⇒ NilClass|Symbol|String (readonly, protected)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns The name of the model, the target model or the name of the associated model.

Returns:

  • (NilClass|Symbol|String) —

    The name of the model, the target model or the name of the associated model.



174
175
176
 
# File 'lib/vedeu/events/event.rb', line 174

def name
  @name
end

Class Method Details

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

  • name (NilClass|Symbol|String) —

    The name of the model or target model to act upon. May default to ‘Vedeu.focus`.

  • options (Hash<Symbol => void>) (defaults to: {}) —

    The options to register the event with.

  • block (Proc)

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:



87
88
89
90
91
 
# File 'lib/vedeu/events/event.rb', line 87

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

  new(name, block, options).bind
end

.bound?(name) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters:

  • name (NilClass|Symbol|String) —

    The name of the model or target model to act upon. May default to ‘Vedeu.focus`.

Returns:



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

def bound?(name)
  Vedeu.events.registered?(name) ||
    Vedeu::Events::Aliases.registered?(name)
end

.event ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

  • name (NilClass|Symbol|String) —

    The name of the model or target model to act upon. May default to ‘Vedeu.focus`.

  • options (Hash<Symbol => void>) —

    The options to register the event with.

  • block (Proc)

Returns:



92
93
94
95
96
 
# File 'lib/vedeu/events/event.rb', line 92

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

  new(name, block, options).bind
end

.register ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

  • name (NilClass|Symbol|String) —

    The name of the model or target model to act upon. May default to ‘Vedeu.focus`.

  • options (Hash<Symbol => void>) —

    The options to register the event with.

  • block (Proc)

Returns:



93
94
95
96
97
 
# File 'lib/vedeu/events/event.rb', line 93

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

  new(name, block, options).bind
end

.unbind(name) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters:

  • name (NilClass|Symbol|String) —

    The name of the model or target model to act upon. May default to ‘Vedeu.focus`.

Returns:



106
107
108
109
110
111
112
113
114
115
 
# File 'lib/vedeu/events/event.rb', line 106

def unbind(name)
  return false unless Vedeu.bound?(name)

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

  Vedeu.events.remove(name)

  true
end

Instance Method Details

#bind ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

See Also:



139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/vedeu/events/event.rb', line 139

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

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

                   end

  repository.store(new_collection)

  true
end

#deadline? ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether this event has a deadline.

Returns:



243
244
245
 
# File 'lib/vedeu/events/event.rb', line 243

def deadline?
  @deadline > 0
end

#debounce ⇒ Fixnum|Float (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Returns:

  • (Fixnum|Float) 


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

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

#debounce_expired? ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the debounce has expired.

Returns:



231
232
233
234
235
236
237
 
# File 'lib/vedeu/events/event.rb', line 231

def debounce_expired?
  return true if (@executed_at = @now) > @deadline

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

  false
end

#debouncing? ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Returns:



220
221
222
223
224
225
226
 
# File 'lib/vedeu/events/event.rb', line 220

def debouncing?
  @now = Vedeu.clock_time

  @deadline = @now + debounce unless deadline?

  options[:debounce] > 0
end

#defaults ⇒ Hash<Symbol => void> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The default options/attributes for a new instance of this class.

Returns:

  • (Hash<Symbol => void>) 


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

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

#delay ⇒ Fixnum|Float (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Returns:

  • (Fixnum|Float) 


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

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

#execute(*args) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Execute the code stored in the event closure.

Parameters:

  • args (void) 


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

def execute(*args)
  @deadline    = 0    # reset deadline
  @executed_at = @now # set execution time to now
  @now         = 0    # reset now

  closure.call(*args)
end

#options ⇒ Hash<Symbol => void> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Combines the options provided at instantiation with the default values.

Returns:

  • (Hash<Symbol => void>) 


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

def options
  defaults.merge!(@options)
end

#throttle_expired? ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a boolean indicating whether the throttle has expired.

Returns:



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

def throttle_expired?
  return true if (@now - @executed_at) > delay

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

  false
end

#throttling? ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:



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

def throttling?
  @now = Vedeu.clock_time

  options[:delay] > 0
end

#trigger(*args) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Triggers the event based on debouncing and throttling conditions.

Parameters:

  • args (Array) 


158
159
160
161
162
163
164
 
# File 'lib/vedeu/events/event.rb', line 158

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

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

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