Login Register

Event Object

When you connect a function to a DOM event with dojo.connect, dojo passes your function a normalized event object. This means that, regardless of the client's browser, you can count on a set of standard attributes about the event and a set of methods to manipulate the event.

Syntax

Assume that your function has been called by dojo.connect and takes an argument named event

Dojo provides the following attributes with an event object:

  • event.target — the element that generated the event
  • event.currentTarget — the current target
  • event.layerX — the x coordinate, relative to the event.currentTarget
  • event.layerY — the y coordinate, relative to the event.currentTarget
  • event.pageX — the x coordinate, relative to the view port
  • event.pageY — the y coordinate, relative to the view port
  • event.relatedTarget — For onmouseover and onmouseout, the object that the mouse pointer is moving to or out of
  • event.charCode — For keypress events, the character code of the key pressed

Dojo provides the following methods with an event object:

  • event.preventDefault — prevent an event's default behavior (e.g., a link from loading a new page)
  • event.stopPropagation — prevent an event from triggering a parent node's event

Additionally, dojo.stopEvent(event) will prevent both default behavior any any propagation (bubbling) of an event.

Example Code for Reference

<head>
<title>Dojo Events are Great</title>
<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js"></script>
<script type="text/javascript">
function echo(event) {
        key = event.charCode;
        console.debug(event.charCode);
}
function foo(event) {
        dojo.stopEvent(event);
        console.debug("The link was clicked");
}
dojo.addOnLoad(function() {
        interactiveNode = dojo.byId("interactive");
        linkNode = dojo.byId("link");
        dojo.connect(interactiveNode, 'onkeypress', echo);
        dojo.connect(linkNode, 'onclick', foo);
});
</script>
<body>
        <a href="http://dojotoolkit.org" id="link">Dojo</a> is great.
        <form>
                <label for="infield"> Type some text: </label>
                <input id="interactive" type="text" name="infield">
        </form>
</body>

Using a Dojo Event Object

In the example code, we have two functions that are connected to two different events. Echo sends the key code of any key typed in the text input field to the console. It does so by using the charCode property of the normalized event object. Foo is connected to the #link and cause it to send "The link was clicked" to the console instead of changing the browser's location; by using the preventDefault method of the normalized event object, connections to change the default behavior of DOM objects.

Now, imagine that you want to detect for the down arrow key in the text box. To do this, we just need to attach a new event listener to the text box and check to see if each keycode is the keycode for the down arrow. And how do you know what the keycode for the down arrow is, you may ask? Well, Dojo provides constants for every non-alpha-numeric key (see: Key code constants). In our case, we are interested in dojo.keys.DOWN_ARROW. So, assuming that you want to just log when the down arrow is pressed, the following code should do the job:

dojo.connect(interactiveNode, 'onkeypress', function (evt) {
        key = evt.keyCode;
        if(key == dojo.keys.DOWN_ARROW) {
                console.debug("The user pressed the down arrow!");
        }
});

Capturing apple key

You can check if the "Control" key was clicked by checking for the boolean evt.ctrlKey and I do see that the evt.metaKey value is sent, but does anyone know how to capture the "Apple" key on the Mac using FF? When I check for an Apple key combo (such as Apple-S), I can't even see the event being captured at all.

Lots of issues

Firstly why can I not find this dojo.event object in the API documentation? All I get back is event from firebug - is this the same thing? I wouldn't think so.

Secondly, you list the canonical methods on event but it omits keyCode (which is then mentioned later on). When I see this kind of thing I immediately think "What other methods exist on dojo.Event but were not listed?". In order to check I would normally go the API docs ..oops not there (see first point).

I guess i could check the code itself for the truth but can I request that this information be added here too for completeness?