dojo/_base/connect.js

• Provides:

  • dojo._base.connect

• Requires:

  • dojo.lib.kernel in common
  • dojo._base.lang in common

• dojo._listener

  • alias - dojo._listener
  • type

    Object

• dojo._listener.getDispatcher

  • type

    Function

• dojo._listener.add

  • parameters:
    • source: (typeof Object)
    • method: (typeof String)
    • listener: (typeof Function)
  • type

    Function

• dojo._listener.remove

  • parameters:
    • source: (typeof Object)
    • method: (typeof String)
    • handle: (typeof Handle)
  • type

    Function

• dojo.connect

  • parameters:
    • obj: (typeof Object|null)

      The source object for the event function.
      Defaults to <code>dojo.global</code> if null.
      If obj is a DOM node, the connection is delegated
      to the DOM event manager (unless dontFix is true).

    • event: (typeof String)

      name of the event function in obj.
      I.e. identifies a property <code>obj[event]</code>.

    • context: (typeof Object|null)

      The object that method will receive as "this".
      
      If context is null and method is a function, then method
      inherits the context of event.
      
      If method is a string then context must be the source
      object object for method (context[method]). If context is null,
      dojo.global is used.

    • method: (typeof String|Function)

      A function reference, or name of a function in context.
      The function identified by method fires after event does.
      method receives the same arguments as the event.
      See context argument comments for information on method's scope.

    • dontFix: (typeof Boolean)

      If obj is a DOM node, set dontFix to true to prevent delegation
      of this connection to the DOM event manager.

  • summary

    <code>dojo.connect</code> is the core event handling and delegation method in
    Dojo. It allows one function to &quot;listen in&quot; on the execution of
    any other, triggering the second whenever the first is called. Many
    listeners may be attached to a function, and source functions may
    be either regular function calls or DOM events.

  • description

    Connects listeners to actions, so that after event fires, a
    listener is called with the same arguments passed to the original
    function.
    
    Since `dojo.connect` allows the source of events to be either a
    "regular" JavaScript function or a DOM event, it provides a uniform
    interface for listening to all the types of events that an
    application is likely to deal with though a single, unified
    interface. DOM programmers may want to think of it as
    "addEventListener for everything and anything".
    
    When setting up a connection, the `event` parameter must be a
    string that is the name of the method/event to be listened for. If
    `obj` is null, `dojo.global` is assumed, meaning that connections
    to global methods are supported but also that you may inadvertently
    connect to a global by passing an incorrect object name or invalid
    reference.
    
    `dojo.connect` generally is forgiving. If you pass the name of a
    function or method that does not yet exist on `obj`, connect will
    not fail, but will instead set up a stub method. Similarly, null
    arguments may simply be omitted such that fewer than 4 arguments
    may be required to set up a connection See the examples for details.
    
    The return value is a handle that is needed to
    remove this connection with `dojo.disconnect`.

  • example

    When obj.onchange(), do ui.update():
    	dojo.connect(obj, "onchange", ui, "update");
    	dojo.connect(obj, "onchange", ui, ui.update); // same

  • example

    Using return value for disconnect:
    	var link = dojo.connect(obj, "onchange", ui, "update");
    	...
    	dojo.disconnect(link);

  • example

    When onglobalevent executes, watcher.handler is invoked:
    	dojo.connect(null, "onglobalevent", watcher, "handler");

  • example

    When ob.onCustomEvent executes, customEventHandler is invoked:
    	dojo.connect(ob, "onCustomEvent", null, "customEventHandler");
    	dojo.connect(ob, "onCustomEvent", "customEventHandler"); // same

  • example

    When ob.onCustomEvent executes, customEventHandler is invoked
    with the same scope (this):
    	dojo.connect(ob, "onCustomEvent", null, customEventHandler);
    	dojo.connect(ob, "onCustomEvent", customEventHandler); // same

  • example

    When globalEvent executes, globalHandler is invoked
    with the same scope (this):
    	dojo.connect(null, "globalEvent", null, globalHandler);
    	dojo.connect("globalEvent", globalHandler); // same

  • type

    Function

• dojo._connect

  • parameters:
    • obj
    • event
    • context
    • method
  • returns

    Handle

  • type

    Function

• dojo.disconnect

  • parameters:
    • handle: (typeof Handle)

      the return value of the dojo.connect call that created the connection.

  • summary

    Remove a link created by dojo.connect.

  • description

    Removes the connection between event and the method referenced by handle.

  • type

    Function

• dojo._disconnect

  • parameters:
    • obj
    • event
    • handle
    • listener
  • type

    Function

• dojo._topics

  • type

    Object

• dojo.subscribe

  • parameters:
    • topic: (typeof String)
    • context: (typeof Object|null)

      Scope in which method will be invoked, or null for default scope.

    • method: (typeof String|Function)

      The name of a function in context, or a function reference. This is the function that
      is invoked when topic is published.

  • summary

    Attach a listener to a named topic. The listener function is invoked whenever the
    named topic is published (see: dojo.publish).
    Returns a handle which is needed to unsubscribe this listener.

  • example

    	dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); });
    	dojo.publish("alerts", [ "read this", "hello world" ]);

  • type

    Function

• dojo.unsubscribe

  • parameters:
    • handle: (typeof Handle)

      The handle returned from a call to subscribe.

  • summary

    Remove a topic listener.

  • example

    	var alerter = dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); };
    	...
    	dojo.unsubscribe(alerter);

  • type

    Function

• dojo.publish

  • parameters:
    • topic: (typeof String)

      The name of the topic to publish.

    • args: (typeof Array)

      An array of arguments. The arguments will be applied
      to each topic subscriber (as first class parameters, via apply).

  • summary

    Invoke all listener method subscribed to topic.

  • example

    	dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); };
    	dojo.publish("alerts", [ "read this", "hello world" ]);

  • type

    Function

• dojo.connectPublisher

  • parameters:
    • topic: (typeof String)

      The name of the topic to publish.

    • obj: (typeof Object|null)

      The source object for the event function. Defaults to dojo.global
      if null.

    • event: (typeof String)

      The name of the event function in obj.
      I.e. identifies a property obj[event].

  • returns

    Handle

  • summary

    Ensure that every time obj.event() is called, a message is published
    on the topic. Returns a handle which can be passed to
    dojo.disconnect() to disable subsequent automatic publication on
    the topic.

  • example

    	dojo.connectPublisher("/ajax/start", dojo, "xhrGet");

  • type

    Function

• dojo._base.connect

  • type

    Object

• dojo._base

  • type

    Object

• dojo

  • type

    Object