# Mojo.Event

## Namespace Detail

Holds functionality related to the UI Toolkit Events.

## Summary

- Mojo.Event.aboutToActivate
- Mojo.Event.activate
- Mojo.Event.back
- Mojo.Event.command
- Mojo.Event.commandEnable
- Mojo.Event.dragEnd
- Mojo.Event.dragging
- Mojo.Event.dragStart
- Mojo.Event.filter
- Mojo.Event.filterImmediate
- Mojo.Event.flick
- Mojo.Event.forward
- Mojo.Event.hold
- Mojo.Event.holdEnd
- Mojo.Event.imageViewChanged
- Mojo.Event.keydown
- Mojo.Event.keypress
- Mojo.Event.keyup
- Mojo.Event.listAdd
- Mojo.Event.listChange
- Mojo.Event.listDelete
- Mojo.Event.listReorder
- Mojo.Event.listTap
- Mojo.Event.orientationChange
- Mojo.Event.progressComplete
- Mojo.Event.progressIconTap
- Mojo.Event.propertyChange
- Mojo.Event.scrollStarting
- Mojo.Event.singleTap
- Mojo.Event.sliderDragEnd
- Mojo.Event.sliderDragStart
- Mojo.Event.stageActivate
- Mojo.Event.stageDeactivate
- Mojo.Event.tap
- Mojo.Event.webViewImageSaved

## Method Summary

- Mojo.Event.listen(target, type{string}, handlerFunction, useCapture)
- Mojo.Event.listenForFocusChanges(node, handler)
- Mojo.Event.listenForHoldEvent(node, downEvent, upEvent, handler, timeout)
- Mojo.Event.make(name{string}, details, optionalDocument, optionalBubbles, optionaCancel)
- Mojo.Event.send(element, name{string}, mojoDetails, optionalBubbles, optionaCancel)
- Mojo.Event.sendKeyDownAndUpEvents(keyDescription, optionalDocument)
- Mojo.Event.sendKeyEvent(keyDescription, optionalEventType, optionalDocument)
- Mojo.Event.stopListening(target, type{string}, handlerFunction, useCapture)

## Detail

### Mojo.Event.aboutToActivate

Generated before a scene is displayed. Allows widgets or scenes to delay the scene transition if needed.

#### Supported Widgets

- None.

### Mojo.Event.activate

An activate event is generated when a scene is loaded.

#### Supported Widgets

- None.

### Mojo.Event.back

This event is sent through the active commander chain when a back gesture is recognized (or the back key is pressed on the desktop).

It's currently generated by the stage assistant, which also responds to it in handleCommand(). If no other clients handle the event, then the stage assistant will do so by closing the current dialog or popping the current scene.

#### Custom Event Fields

- originalEvent: The original click Event object which caused this event to be dispatched. Useful for disambiguating changes if the list items contain multiple input fields.

#### Supported Widgets

- None.

### Mojo.Event.command

A command event is generated when a menu item is selected.

#### Supported Widgets

- None.

### Mojo.Event.commandEnable

Menu items that specify checkEnabled:true in the menu model cause the menu system to check their enable state before displaying them. This is useful for items in submenus and the appmenu, because they are not constantly displayed (like items in the command and view menus), meaning their enable state always appears correct when the menu is popped up. The command-enabled event is generated as part of menu updating. To check the enable state of a menu item, a command-enable event is sent through the commander chain. This event does not go through the DOM. If nothing in the commander chain calls preventDefault() on the event, the menu item will be enabled.

#### Supported Widgets

- None.

### Mojo.Event.dragEnd

An up action following a Mojo.Event.dragStart event generates a dragEnd event.

#### Supported Widgets

- None.

### Mojo.Event.dragging

Movement following the Mojo.Event.dragStart event generates dragging events.

#### Supported Widgets

- None.

### Mojo.Event.dragStart

A down action followed by movement outsided of a system-defined radius generates a Mojo.Event.dragStart event. Usually, the Mojo.Event.dragStart event is handled by the scroller. However, any element that chooses to handle this event gets all subsequent drag events.

#### Supported Widgets

- None.

### Mojo.Event.filter

Entering data in the filterbox generates a filter event after a client of default specified delay.

#### Supported Widgets

- Mojo.Widget.FilterField

#### Mojo.Event.filterImmediate

Entering data in the filterbox generates a filter event as soon as a key is typed.

#### Supported Widgets

- Mojo.Widget.FilterField

### Mojo.Event.flick

Movement greater than a system-defined rate, between down and up events, generates a flick event.

#### Supported Widgets

- None.

### Mojo.Event.forward

This event is sent through the active commander chain when a forward gesture is recognized

#### Supported Widgets

- None.

### Mojo.Event.hold

A down movement lasting greater than a system-defined time interval and with movement within a limited radius generates a hold event. The hold event is associated with the Mojo.Event.hold event.

#### Supported Widgets

- None.

### Mojo.Event.holdEnd

An up movement following a hold event generates a Mojo.Event.holdEnd event.

#### Supported Widgets

- None.

### Mojo.Event.imageViewChanged

Sent from an ImageView widget when the current center image has been changed via a gesture.

#### Supported Widgets

- Mojo.Widget.ImageView

### Mojo.Event.keydown

Forwarded keydown event. Only supported on the currently active sceneElement or container.

#### Custom Event Fields

- originalEvent: keyboard event that triggered this event.

#### Supported Widgets

- None.

### Mojo.Event.keypress

Forwarded keydown event. Only supported on the currently active sceneElement or container.

#### Custom Event Fields

- originalEvent: keyboard event that triggered this event.

#### Supported Widgets

- None.

### Mojo.Event.keyup

Forwarded keyup event. Only supported on the currently active sceneElement or container.

#### Custom Event Fields

- originalEvent: keyboard event that triggered this event.

#### Supported Widgets

- None.

### Mojo.Event.listAdd

This event is dispatched to the widget element when the special "Add" item at the end of the list is clicked. This item appears when the addItemLabel property is defined in the widget's attributes or model, and a custom event name is used to give applications an easy way to identify the expected behavior.

#### Custom Event Fields

- model: The model object used to render the List to which an item should be added.
- originalEvent: The original click Event object which caused this event to be dispatched. Useful for disambiguating changes if the list items contain multiple input fields.
- item: The item model to be added. Only defined for listAdd events resulting from a drag/drop from a different list.
- index: The index at which to add the new item. Only defined for listAdd events resulting from a drag/drop from a different list.

#### Supported Widgets

- Mojo.Widget.List

### Mojo.Event.listChange

This event is dispatched to the widget element when a list item is clicked. As with Mojo.Event.listTap, the app handler is responsible for sorting out which part of the list item changed if there are multiple options, and event.originalEvent.target should be the input element that changed.

#### Custom Event Fields

- object: The object from the listItems array in the model associated with the changed list item.
- model: The model object used to render the List.
- originalEvent: The original change Event object which caused this event to be dispatched. Useful for disambiguating changes if the list items contain multiple input fields.

#### Supported Widgets

- Mojo.Widget.List

### Mojo.Event.listDelete

This event is dispatched to the widget element when an item is deleted from the list. SceneAssistants will often listen for this event on List widgets, and should respond by deleting the given item from the model (and database, if any). If preventDefault() is called on the listDelete event, then the default deletion behavior in the list widget will not occur.

#### Custom Event Fields

- model: The widget's model object.
- item: The model object for the list item being deleted.
- index: The index of the list item being deleted.

#### Supported Widgets

- Mojo.Widget.List

### Mojo.Event.listReorder

This event is dispatched to the widget element when an item is reordered. SceneAssistants will often listen for this event on List widgets, and should respond by reordering the given item model as indicated (and persist the changes to disk if appropriate).

#### Custom Event Fields

- model: The widget's model object.
- item: The model object for the list item being moved.
- fromIndex: The current index of the list item, which it should be moved from.
- toIndex: The new index of the list item, which it should be moved to.

#### Supported Widgets

- Mojo.Widget.List

### Mojo.Event.listTap

This event is dispatched to the widget element when there is a mojo-tap event on a list item. The app handler is responsible for sorting out which part of the list item was clicked if necessary, since that depends entirely on the template provided. It's useful to look at event.originalEvent.target. This is the target of the original click or change event that caused the higher level mojo event to be dispatched. It will be an input element containing the new value for a change event, or the item's sub-element that was actually clicked for a click event. For example:

>     listClickHandler: function(event) {
>       // Only respond to clicks on the label element,
>       // not the editable text field.
>       if(event.originalEvent.target.tagName == "LABEL") {
>           Mojo.Log.info(event.item.data +": "+event.item.definition);
>       }
>     }

#### Custom Event Fields

- item: The object from the listItems array in the model associated with the clicked list item.
- model: The model object used to render the List.
- originalEvent: The original click Event object which caused this event to be dispatched. Useful for disambiguating clicks if the list items contain multiple clickable elements.

#### Supported Widgets

- Mojo.Widget.List

### Mojo.Event.orientationChange

Sent by the scene controller on the scene element when the screen orientation changes. Contains an orientation property describing the orientation.

### Mojo.Event.progressComplete

Sent when progress reaches 100%.

#### Supported Widgets

- Mojo.Widget.ProgressPill
- Mojo.Widget.ProgressBar

### Mojo.Event.progressIconTap

Sent when the icon on the ProgressPill is tapped by the user.

#### Custom Event Fields

- model: model associated with this progress pill.

#### Supported Widgets

- Mojo.Widget.ProgressPill
- Mojo.Widget.ProgressBar

### Mojo.Event.propertyChange

This event is dispatched to the widget element when property-editing widgets change values.

#### Custom Event Fields

- property: Name of the property that changed.
- value: New value of the property.
- model: The model object to which the property change applies.

Sometimes available:

- oldValue: value of the widget before this change.
- originalEvent: event that triggered the propertyChange event to be sent.

#### Supported Widgets

- Mojo.Widget.ListSelector
- Mojo.Widget.PasswordField
- Mojo.Widget.RadioButton
- Mojo.Widget.Scroller
- Mojo.Widget.Slider
- Mojo.Widget.TextField
- Mojo.Widget.ToggleButton

### Mojo.Event.scrollStarting

When contained in a scroller, down action followed by movement generates a scroll-starting event.

#### Supported Widgets

- Mojo.Widget.Scroller

### Mojo.Event.singleTap

A native down-and-up movement within a limited time interval and within a limited radius generates a single tap event.

It's sent when Mojo.handleSingleTap is called and has the following properties: x, y, shiftKey, ctrlKey, altKey, metaKey, timestamp.

#### Supported Widgets

- None.

### Mojo.Event.sliderDragEnd

Sent when the draggable element on the Slider is dropped.

#### Supported Widgets

- Mojo.Widget.Slider
- Mojo.Widget.ProgressSlider

### Mojo.Event.sliderDragStart

Sent when the draggable element on the Slider is picked up to be dragged.

#### Supported Widgets

- Mojo.Widget.Slider
- Mojo.Widget.ProgressSlider

### Mojo.Event.stageActivate

A stageActivate event is generated when a stage becomes active and is potentially receiving the user's attention. For card stages, this is when the stage is maximized and fills the screen. The event is sent to the top scene, and bubbles up to the stage's document.

#### Supported Widgets

- None.

### Mojo.Event.stageDeactivate

A stageDeactivate event is generated when a stage is no longer active and potentially receiving the user's attention. For card stages, this is when the stage is minimized.

The event is sent to the top scene, and bubbles up to the stage's document.

#### Supported Widgets

- None.

### Mojo.Event.tap

A down-and-up movement within a limited time interval and within a limited radius generates a tap event.

#### Supported Widgets

- None.

### Mojo.Event.webViewImageSaved

Sent in response to saving inline images.

#### Supported Widgets

- Mojo.Widget.WebView

## Method Detail

### Mojo.Event.listen(target, type{string}, handlerFunction, useCapture)

A wrapper around addEventListener that adds some parameter checking.

#### Parameters

- target - target to observe
- {string} type - type of the event to observe
- {Function} handlerFunction - function to call when the event fires
- {Boolean} useCapture - optional parameter that, when true, causes the event to be observed during the capture phase.

### Mojo.Event.listenForFocusChanges(node, handler)

This function can be used to listen for changes in the focused element inside the node.

A 'listener object' is returned which implements a stopListening() method. This can be called to permanently cancel the listener, removing its event listeners.

#### Parameters

- node - the node on which to listen for events.
- handler - Function to be called when focus changes, passing the newly focused element or null.

### Mojo.Event.listenForHoldEvent(node, downEvent, upEvent, handler, timeout)

This function can be used to listen for some kind of 'hold' event on a given node. This works by initiating a 'hold timer' when the appropriate 'down' event is received, and cancelling it if we see the 'up' event before it has expired. If the timer expires, then we call the given handler function with the initial 'down' event as the first argument.

A 'listener object' is returned which implements a stopListening() method. This can be called to permanently cancel the listener, removing its event listeners. Alternatively, if the handler function returns true, then the listener will be automatically stopped.

The implementation is somewhat tailored for key events:

- Successive 'down' events do not reset the hold timer.
- After calling the handler once, it will not be called again until after an 'up' event is received.

#### Parameters

- node - the node on which to listen for events.
- {String} downEvent - the type of event that should initiate the hold timer.
- {String} upEvent - the type of event that should cancel the hold timer.
- handler - Function to be called when the hold timer expires.
- timeout - Length of hold timer in seconds. Optional, defaults to 1.

### {Object} Mojo.Event.make(name{string}, details, optionalDocument, optionalBubbles, optionalCancel)

Utility routine used to create custom mojo events.

In addition to creating an event with the given name, the event is also extended such that an isDefaultPrevented() method is available.

#### Parameters

- {string} name - the name of the event, visible in event.type.
- {string} details - a hash of custom event properties to be copied to the event object.
- {HTML element} optionalDocument - a supplied element to target the event on; if not supplied, defaults to current active document.
- {Boolean} optionalBubbles - flag determining if the event's propagation behavior is to bubble; default is true.
- {Boolean} optionalCancel - flag determining if the event's default action may be prevented via the preventDefault() method; default is true.

#### Returns

- {Object} This will return 'true' if any handler calls event.preventDefault().

### Mojo.Event.send(element, name{string}, mojoDetails, optionalBubbles, optionalCancel)

Like prototype's element.fire(), except that the event type is actually as specified (instead of always dataavailable), and the specified details are placed in the event object directly (instead of a memo subobject). If element is undefined, the new event will just be returned and not actually dispatched.

#### Parameters

- element - HTML element to dispatch the event on.
- {string} name - the name of the event, visible in event.type.
- {string} mojoDetails - a hash of custom event properties to be copied to the event object.
- {Boolean} optionalBubbles - flag determining if the event's propagation behavior is to bubble; default is true.
- {Boolean} optionalCancel - flag determining if the event's default action may be prevented via the preventDefault() method; default is true.

### Mojo.Event.sendKeyDownAndUpEvents(keyDescription, optionalDocument)

Function to create and send a key down and up event.

#### Parameters

- {String} keyDescription - key description for key, like "U+0009" for tab.
- {HTML element} optionalDocument - a supplied element to target the event on; if not supplied, defaults to current active document.

### Mojo.Event.sendKeyEvent(keyDescription, optionalEventType, optionalDocument)

Function to create and send a key event.

#### Parameters

- {String} keyDescription - key description for key, like "U+0009" for tab.
- {String} optionalEventType - event type; defaults to 'keydown'.
- {HTML element} optionalDocument - a supplied element to target the event on; if not supplied, defaults to current active document.

### Mojo.Event.stopListening(target, type{string}, handlerFunction, useCapture)

A wrapper around removeEventListener that adds some parameter checking.

#### Parameters

- target - target to observe.
- {string} type - type of the event that was being observed.
- {Function} handlerFunction - function that was previously passed to listen.
- {Boolean} useCapture - optional parameter that, when true, causes a capture phase listener to be removed.