Skip to content

Commit

Permalink
event: add some documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
meh committed Feb 7, 2014
1 parent caac481 commit 8a4cd6a
Showing 1 changed file with 61 additions and 3 deletions.
64 changes: 61 additions & 3 deletions opal/browser/event/base.rb
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,24 @@ module Browser
class Event
include Native

# @see https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events
class Definition
include Native

# @private
def self.new(&block)
data = super(`{ bubbles: true, cancelable: true }`)
block.call(data) if block

data.to_n
end

# Set the event as bubbling.
def bubbles=(value)
`#@native.bubbles = #{value}`
end

# Set the event as cancelable.
def cancelable=(value)
`#@native.cancelable = #{value}`
end
Expand Down Expand Up @@ -57,17 +61,22 @@ def self.target(&block)
class Callback
attr_reader :target, :name, :selector

# @private
def initialize(target, name, selector = nil, &block)
@target = target
@name = name
@selector = selector
@block = block
end

def call(e)
to_proc.call(e)
# Call the callback with the given event.
#
# @param event [native] the native event object
def call(event)
to_proc.call(event)
end

# Get the native function linked to the callback.
def to_proc
@proc ||= -> event {
%x{
Expand All @@ -86,10 +95,13 @@ def to_proc
}
end

# @!attribute [r] event
# @return [Class] the class for the event
def event
Event.class_for(@name)
end

# Stop listening for the event linked to the callback.
def off
target.off(self)
end
Expand All @@ -102,6 +114,7 @@ def initialize(target, name, pair)
@pair = pair
end

# Stop listening for the event linked to the delegate.
def off
delegate = @target.delegated[@name]
delegate.last.delete(@pair)
Expand All @@ -115,6 +128,26 @@ def off

Delegates = Struct.new(:callback, :handlers)

# @overload on(name, &block)
#
# Start listening for an event on the target.
#
# @param name [String] the event name
#
# @yieldparam event [Event] the event
#
# @return [Callback]
#
# @overload on(name, selector, &block)
#
# Start listening for an event on the target children.
#
# @param name [String] the event name
# @param selector [String] the CSS selector to trigger the event on
#
# @yieldparam event [Event] the event
#
# @return [Delegate]
def on(name, selector = nil, &block)
raise ArgumentError, 'no block has been given' unless block

Expand Down Expand Up @@ -152,6 +185,13 @@ def on(name, selector = nil, &block)
end
end

# Start listening for an event in the capturing phase.
#
# @param name [String] the event name
#
# @yieldparam event [Event] the event
#
# @return [Callback]
def on!(name, &block)
raise ArgumentError, 'no block has been given' unless block

Expand Down Expand Up @@ -230,6 +270,13 @@ def attach!(*)
end
end

# @overload off()
# Stop listening for any event.
#
# @overload off(what)
# Stop listening for an event.
#
# @param what [Callback, String, Regexp] what to stop listening for
def off(what = nil)
case what
when Callback
Expand Down Expand Up @@ -295,6 +342,12 @@ def detach(callback)
end
end

# Trigger an event on the target.
#
# @param name [String] the event name
# @param args [Array] optional arguments to the event callback
#
# @yieldparam definition [Definition] definition to customize the event
def trigger(event, *args, &block)
if event.is_a? String
event = Event.create(event, *args, &block)
Expand All @@ -303,7 +356,12 @@ def trigger(event, *args, &block)
dispatch(event)
end

# Trigger the event without bubbling.
# Trigger an event on the target without bubbling.
#
# @param name [String] the event name
# @param args [Array] optional arguments to the event callback
#
# @yieldparam definition [Definition] definition to customize the event
def trigger!(event, *args, &block)
trigger event, *args do |e|
block.call(e) if block
Expand Down

0 comments on commit 8a4cd6a

Please sign in to comment.