webOShelp.net

Asynchronously load a JavaScript file by adding a script tag to the header of the document.

This is used to animate the 'clip' style property of DOM elements. Only one side may be animated at a time. Any existing clip animation on the indicated node is cancelled when the new one is applied, and this generally behaves like animateStyle().

In addition, animateStyle() is used to provide underlying functionality, so it's details are generally supported as well.

Details object properties:

Example \usage:

This is used to animate the clipping rectangle for ProgressPill widgets.

clipStyleAnimator = Mojo.Animation.animateClip(
    this.progressDiv,    'left',    this.oldWidth,    width,    0.2,
    clip: {
      top: 0,      left: this.oldWidth,      bottom: 12,      right: 0
    },
    curve: 'ease-in-out'
);

Used to animate CSS style properties of DOM elements. Animates the specified attribute to the specified value over a specified duration. Any existing animation on the indicated node for the indicated style attribute is cancelled when the new one is applied. The animator will override any other changes made to the animated attribute while the animation is in progress. Currently, only integer valued attributes are supported, so colors and opacity cannot be animated (except using the styleSetter detail property).

One difference between this animator and CSS transitions is that both a fromValue and a toValue must be specified. This enables the animation speed to be "correct" when an attribute is being animated back and forth between two values and the back animation needs to be started while the forward animation is only partially complete.

Details object properties:

Example usage:

This code is used to animate spacers to 0 height when doing drag and drop reordering in lists. Note the use of an onComplete function to remove the 0-height spacer from the DOM.

    Mojo.Animation.animateStyle(
        this.curDragSpacer, 'height', this.dragHeight, 0, .2,
         {
          onComplete:function(el){Element.remove(el);}
        }
      );

animateValue() is used to provide underlying functionality, so its details are generally supported as well.

Animates a value between the two specified numbers over the specified duration.  Calls the specified callback function with the current value at each step of the animation. Returns an animation object that can be used to end the animation early.

Methods

Parameters

Properties for details object:

Returns a reference to the appropriate animation queue to use for specified DOM element.

Writes an error to the log if expression doesn't evaluate to true.

Mojo.require and Mojo.assert methods are very similar.  The difference is that Mojo.require methods will throw an exception when their requirements aren't met, and are intended to be used in cases where the application cannot reasonably continue if the requirements aren't met.

Returns String containing the error message written to the log.

Writes an error to the log if expectedArray fails the Prototype isArray method. Returns String containing the error message written to the log.

Writes an error to the log if targetObject wasn't constructed by the passed in constructor function. Returns String containing the error message written to the log.

Writes an error to the log if value evaluates to undefined.  Returns String containing the error message written to the log.

Example usage:

Mojo.Event.listen=function listen(target,type,handlerFunction,useCapture){
  Mojo.assertDefined(target,"Mojo.Event.listen: 'target' parameter must be defined.");
  Mojo.assertString(type,"Mojo.Event.listen: 'type' parameter must be a string.");
  Mojo.assertFunction(handlerFunction,"Mojo.Event.listen: 'handlerFunction' parameter must be a function.");
  target.addEventListener(type,handlerFunction,!!useCapture);
};

Writes an error to the log if expectedElement fails the Prototype isElement method. Returns String containing the error message written to the log.

Example usage:

Mojo.View.makeFocusable = function(targetElement) {
    Mojo.assertElement(targetElement, "Mojo.View.makeFocusable requires an element.");
    targetElement.setAttribute("tabindex", "0");
};

Writes an error to the log if expected != actual. Returns String containing the error message written to the log.

Writes an error to the log if expression evaluates to true. Returns String containing the error message written to the log.

Example usage:

    var details = this.detailsTable.get("5551212");
    Mojo.assertFalse(details, "Details must not be found");

Writes an error to the log if expectedFunction fails the Prototype isFunction method. Returns String containing the error message written to the log.

Example usage:

Mojo.Event.listen=function listen(target,type,handlerFunction,useCapture){
  Mojo.assertDefined(target,"Mojo.Event.listen: 'target' parameter must be defined.");
  Mojo.assertString(type,"Mojo.Event.listen: 'type' parameter must be a string.");
  Mojo.assertFunction(handlerFunction,
     "Mojo.Event.listen: 'handlerFunction' parameter must be a function.");
  target.addEventListener(type,handlerFunction,!!useCapture);
};

Writes an error to the log if regex doesn't match testValue.

Writes an error to the log if expectedString fails the Prototype isString method. Returns String containing the error message written to the log.

Writes an error to the log if expectedNumber fails the Prototype isNumber method. Returns String containing the error message written to the log.

Writes an error to the log if targetObject doesn't have the values for the property name or names passed and throws an exception.

Writes an error to the log if expectedString fails the Prototype isString method. Returns String containing the error message written to the log.

Returns boolean True if key is the delete key and False if not.

Returns boolean True if key is the enter key and False if not.

No info yet.

Closes all stages.

Closes the specified stage.

Creates a new stage and calls the specified function when the stage has completed loading.  Data can be bound to the callback function as needed, eliminating the need to pass parameters in the URI. The callback function can use the passed-in stage controller to push the first scene of the new stage.

Returns the stage controller of the currently active (in focus) stage.

Returns the orientation of the physical screen.

Returns "up", "down", "left", or "right".

Function to get the stage controller for a specified stage. Returns undefined if the stage does not exist or is not yet initialized.

Returns a controller or proxy object for a stage. Returns the stage controller if available; if not, a proxy object will be returned which implements delegateToSceneAssistant(), and will delegate the calls as expected when the stage is available.

Launches another application with parameters (optional).

Attempts to "open" a file specified in the launch parameters.  If no application can be found, the method fails.  Returns the Mojo.Service.Request object used to make the launch request.

Plays a sound.

Removes all pending banner messages. Does not affect messages that are already displayed.

Deletes a pending banner. The category parameter defaults to 'banner'. Will not remove messages that are already displayed.

Propagates notificationData and calls considerforNotification on everyone in the commander stack of the focused window (usually includes the scene assistant, stage assistant and app assistant). As the notificationData propagates through the chain, each assistant (before the app assistant) should remove any properties not needed for building a notification and return the remaining data, which can then be used by the app assistant's considerForNotification function to call showBanner or create or update a dashboard stage.

Shows a banner containing the message text from bannerParams. launchArguments will be used to launch or relaunch the application if the banner is tapped by the user. 

Wrapper around Mojo.Event.listen that also calls get() on the element parameter if it is a string, converting it to a DOM node.

Pushes a new container on the container stack of the calling scene. Mojo.Event.key* events are sent to the top container. All containers with a lower or same layer will be cancelled if they specified a cancelFunc in their options. 

Removes a commander from the commander stack.

Removes the specified container element from the stack. Returns True if successful.

Remove a request from the scene's list of requests.

Removes a specified model watcher. If model is undefined, then the specified watcher is removed from all models.

Called by the framework when re-rendering HTML that includes widgets so that the old/removed widgets are not notified of changes to models.

Constant

For standard pushContainer layers.

Called by the scene assistant during setup to specify the element that will receive focus.

Register the given attributes and model to be used with the widget of the given name.  For details on specific widgets with examples, refer to the UI Widget list.

Called by scene assistants in the setupViews() method.  If a model is specified for a widget rendered in a list item, the model will be overridden by the one defined for the list item.

Sets the data model for a widget and notifies the widget of the new model.

Widget can be specified by either DOM element or ID but not widget name, as it is intended to operate on single widget only. The setup associated with the widget is not modified.

Used to notify widgets that a div containing widgets has become visible. This is important for getting correct measurements where widgets are dependent upon them for drawing.

Wrapper around Mojo.Event.stopListening that also calls get() on element if it is a string, converting it to a DOM node.

Returns the top container in the calling scene.

Enables and disables receiving page up and page down key events in response to the "swipe" gesture when the scene is in landscape mode. This property is persistent for each scene.

Sign up for notifications when changes are made to the specified model.

When someone calls modelChanged on the specified model, the changeFunc will be called. Usually used by the framework to automatically notify widgets when their models change.

Enables and disables full screen mode for the scene. This property is persistent for each scene, so it is not necessary for client code to manage it.

Returns the scene scroller created automatically with every scene.

Notifies widgets that a div containing widgets has changed its CSS visibility property to display:none. This is important for getting correct measurements where widgets are dependent upon them for drawing.

Can be called when a data model changes and a widget displaying that data needs to be updated.

Note: Palm states this API is still changing. Eventually, they want to provide a more structure on the datamodel side and an API that allows the app to express what about the model changed.

For example, added or removed an element, modified one or more properties of an element, etc.

Popup submenus can be used to provide a text list of choices to the user. It accepts standard menu models with a few additional optional properties.

Example usage:

    sceneController.popupSubmenu(this.controller, {
            onChoose:this.popupChoose,
            placeNear:clickEvent.target,
            items: [{label: $L('Apply'), command: 'apply-cmd'},
                      {label: $L('Applique'), command: 'applique-cmd'},
                      {label: $L('Applaud'), command: 'applaud-cmd'},
                      {label: $L('Approximate'), command: 'approx-cmd'}]
            });

The above code will cause a modal list to appear with the label choices presented. When the user taps one, the onChoose function will be called in the scope of the scene assistant with the command property of the chosen item. If the user taps outside the popup menu, the menu is dismissed and the onChoose function is called with undefined.

Beyond the standard menu model properties, the submenu supports some additional model properties:

Beyond the standard menu item properties, the submenu supports some additional menu item properties:

Keyboard shortcuts can be displayed in the submenu, but are implemented by the main menu system.

Creates a Transition object that can be used to run a transition within the scene. On creation, events to the scene are frozen and a snapshot of the scene's window is taken. Any processing to change the scene's state should be done prior to calling run() on the Mojo.Transition object. After run() is called, events will once again behave as normal.

Example usage:

    var transition = this.controller.prepareTransition(Mojo.Transition.crossFade, false);
    // Code setting up the scene's new state goes here
    transition.run();

Adds the given commander to the top of the calling scene's SceneController stack. The commanders in this stack are only used when this scene is the current scene.

Creates a Palm service request.  See the Service API section for details and examples of specific service calls.  The request is automatically cancelled when the scene is popped. The parameters are passed directly to new Mojo.Service.Request().

Sets default transition to be used for pushing or popping the calling scene. This transition can be overridden by an option specified when pushing or popping the scene.

Function to call a function after the user has been idle for a specified amount of time. Once set, the timeout will remain dormant until the user has been continuously idle for the delay specified. Returns Function.  Calling Function cancels idle timeout.

Unloads a stylesheet and any versions of it for the current locale from the stage's document.

Programatically activates the calling stage and causes card window to be maximized.

Returns the currently active scene from this stage, if any. If no scenes are active, returns undefined.

Programatically deactivates this stage and causes card windows to be minimized.

Function to call a method on the assistant of the active scene (of the current stage).

Return the current application controller.

Returns an array containing the scene controllers currently on the stack. result[0] is the first (bottom) scene.

Gets the orientation of the stage's window. Returns 'up', 'down', 'left', or 'right'.

Function to find out if the current stage has new content.  Returns Boolean.

Makes the device's center navi button pulsate if hasNew is true. Can be used for anything but mainly intended to alert the user to dashboard events.

Function to find out if the calling stage is active and has pushed scenes.  Returns Boolean.

Function to find out if the current window is a child window.  Returns Boolean.

Loads a stylesheet and any versions of it for the current locale into the stage's document.

Returns the assistant of the scene below this scene in the scene stack, or undefined if this is the root scene.

Removes a scene from the scene stack, passing returnValue to the newly revealed scene's activate method. This is an asynchronous operation.

Removes scenes from the scene stack until the specified scene is reached or all scenes have been removed from the stack, whichever comes first. The targetScene object may be either the SceneController for the target scene, the scene's DOM ID, or the scene's name. If targetScene is undefined, all scenes are popped. Popped scenes are not reactivated and there is no visual transition to signify they are being removed from the stack. This is an asynchronous operation.

Adds the provided commander to the top of the calling stage's StageController stack. The stack contains commanders that are used only with the current scene.

Pushes a new scene. After this call, the new scene is placed on the stage's scene stack, the scene assistant's setup method is called and UI widgets are instantiated. The scene is then displayed and the scene assistant's activate method is called.

Removes a commander from the commander stack.

Sends the given event through the entire command chain, starting with the CommanderStack in the current scene and progressing to the StageController's stack.  Is stopped if a scene in the command chain calls event.stopPropagation().

Enables the client application to send text to the clipboard.  Currently selected text automatically passed as first argument.

Sets the orientation of the stage's window.

Pops the current scene and simultaneously pushes a new scene without activating & deactivating any underlying scenes. This is an asynchronous operation.

Returns the topmost scene from the calling stage.

Function to add an object identified by a key to the depot. The default bucket is used.

Example usage:

db = new Mojo.Depot({name:"feedDB", version:1, estimatedSize:25000, replace: false}, 
     this.dbOpenOK.bind(this), this.dbOpenFail.bind(this)); 

db.add("feedList", feedList, 
        function() {Mojo.Log.info("........","feedList saved OK");}, 
        function(transaction,result) { 
          Mojo.Log.warn("Database save error (#", result.message, ") - can't save feed list. Will need to reload on next use."); 
          Mojo.Controller.errorDialog("Database save error (#" + result.message + ") - can't save feed list. Will need to reload on next use."); 
        });

Function to remove an object identified by key from the depot. The default bucket is used.

Function to retrieve an object identified by key from a depot. The default bucket specified by _defaultBucketName is used.

Example usage:

db = new Mojo.Depot({name:"feedDB", version:1, estimatedSize:25000, replace: false}, 
     this.dbOpenOK.bind(this), this.dbOpenFail.bind(this)); 
FeedListAssistant.prototype.dbOpenOK = function() { 
    Mojo.Log.info("........","Database opened OK"); 
    db.get("feedList", this.updateList.bind(this), 
      this.useDefaultList.bind(this)); 
}; 

Function to remove an object identified by bucket and key from the depot.

Function to delete the data from the current depot database.

Example usage:

db = new Mojo.Depot({name:"feedDB", version:1, estimatedSize:25000, replace: false}, 
     this.dbOpenOK.bind(this), this.dbOpenFail.bind(this))
db.removeAll(); 

Depot allows you to store JavaScript objects in a database. Currently implemented as a framework wrapper around HTML5 active record access.

options object properties:

Example usage:

var db= new Mojo.Depot ({name:”myDB”,version:1,replace:false}, this.openOK, this.openFail);

FeedListAssistant.prototype.dbOpenOK = function() { 
    Mojo.Log.info("........","Database opened OK"); 
    db.get("feedList", this.updateList.bind(this), 
      this.useDefaultList.bind(this)); 
}; 

FeedListAssistant.prototype.dbOpenFail = function(transaction, result) { 
    Mojo.Log.warn("Can't open feed database (#", result.message, "). All feeds will be reloaded."); 
    Mojo.Controller.errorDialog("Can't open feed database (#" + result.message + "). All feeds will be reloaded."); 
 }; 

Configures the specified element as a valid drop container for dragged items.

dropClient object properties:

Function used to start dragging an element. Called when a hold event occurs (for elements dragged on push-and-hold) or on mousedown or dragStart.  Returns an active "dragger" object when the user's finger is down and before the dragStart event actually occurs.

The dragger sets the scene up for dragging, preventing the drag from causing the scene to be scrolled. Both dragEnd and tap events cause the drag operation to end, since dragStart and dragEnd events cannot occur if there are no mousemove events. This sort of "aborted" drag operations are treated like any other, and will still cause the appropriate enter & drop methods to be called on the container.

options object properties:

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

Supported Widgets

• None.

An activate event is generated when a scene is loaded.

Supported Widgets

• None

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.

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

Supported Widgets

• None.

Menuitems 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 & 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 menuitem, 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 menuitem will be enabled.

Supported Widgets

• None.

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

Supported Widgets

• None.

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

Supported Widgets

• None.

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.

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

Supported Widgets

• Mojo.Widget.FilterField

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

Supported Widgets

• Mojo.Widget.FilterField

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

Supported Widgets

• None.

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

Supported Widgets

• None.

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.

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

Supported Widgets

• None.

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

Supported Widgets

• Mojo.Widget.ImageView

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.

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.

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.

This event is dispatched to the widget element when there 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 SmallList 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

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 which 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 SmallList.
• 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

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

A wrapper around addEventListener that adds some parameter checking.

Example usage:

        // Setup the TruncTextField widget
        var scratchEventDiv = this.controller.get('scratch_event');
        this.controller.setupWidget('scratch_event_field', tfAttrs, this.scratchEvent);
        this.controller.instantiateChildWidgets(scratchEventDiv);
        this.scratchEventField = this.controller.get('scratch_event_field');
        this.scratchEventCommitHandler = this.handleEditScratchEventCommit.bind(this);
        this.scratchEventKeyEventHandler = this.handleScratchEventKey.bind(this);
        this.scratchEventTapHandler = this.handleScratchEventTap.bind(this)
        this.scratchEventHoldHandler = this.handleScratchEventHold.bind(this);
        
        // Listen for the key and tap events on the whole scene when a 
        // scratch event is present
        Mojo.Event.listen(scratchEventDiv, "keyup", this.scratchEventKeyEventHandler);
        Mojo.Event.listen(this.controller.sceneElement, 
             Mojo.Event.tap, this.scratchEventTapHandler);
        Mojo.Event.listen(this.controller.sceneElement, 
             Mojo.Event.hold, this.scratchEventHoldHandler);

This function can be used to listen for changes in which element has focus inside the specified node.

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

 Example usage:

        this.controller.setupWidget('emailAddress', this.emailAttributes, this.emailModel);
                
        $('emailAddress').observe(Mojo.Event.propertyChange, this.emailChanged.bind(this));
        this.emailFocusHandler = this.emailHandler.bind(this);
        Mojo.Event.listenForFocusChanges($('emailAddress'), this.emailFocusHandler);

This function can be used to listen for a 'hold' event on a given node. Initiates a hold timer when the appropriate down event is received and cancels the time if the up event occurs before the timer has expired. If the timer expires, the given handler function is called with the initial down event as the first argument.

Returns a listener object which implements a stopListening() method. Calling stopListening() permanently cancels the listener, removing its event listeners. Alternatively, if the handler function returns true, the listener will be automatically stopped.

The implementation is ideal for key events because 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.

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

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.object.data +": "+event.object.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 SmallList.
• 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

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

Sent when progress reaches 100%.

Supported Widgets

• Mojo.Widget.ProgressPill
• Mojo.Widget.ProgressBar

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

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

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

Supported Widgets

• Mojo.Widget.Scroller

Similar to the element.fire() method of the Prototype JavaScript framework, except that the event type can be specified (instead of always dataavailable), and 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.

Similar to prototype's element.fire(), method, except that the event type can be 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.

Example usage:

    if (event.keyCode === Mojo.Char.enter) {
        var selection = document.querySelector(':focus');
        if (!Mojo.Gesture.handlesReturnKey(selection)) {
            Event.stop(event);
            Mojo.Event.sendKeyDownAndUpEvents("U+0009");            
        }
    }

Function to create and send a key event.

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.

Sent when the draggable element on the Slider is dropped.

Supported Widgets

• Mojo.Widget.Slider
• Mojo.Widget.ProgressSlider

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

Supported Widgets

• Mojo.Widget.Slider
• Mojo.Widget.ProgressSlider

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.

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.

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

Supported Widgets

• None.

Function used to create custom mojo events.

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

Example usage:

      var newEv = Mojo.Event.make(Mojo.Event.back, {originalEvent: event});
      this.sendEventToCommanders(newEv);
      if(newEv.defaultPrevented)
           {Event.stop(event);}

A wrapper around removeEventListener that adds some parameter checking.

Example usage:

StartpageAssistant.prototype.deactivate = function() {

    // Stop listening for taps on the start page icons
    Mojo.Event.stopListening(this.controller.get('bookmarks'), 
  Mojo.Event.tap, this._onStartPageTapHandler, true);

    // Cleanup focus handlers.
    this.controller.document.removeEventListener(Mojo.Event.activate, 
  this._onCardActivateHandler, false);
    this.controller.document.removeEventListener(Mojo.Event.deactivate, 
  this._onCardDeactivateHandler, false);

    this._isActivated = false;
    this._addressBar.stopObserving();
    this._addressBar.closeSearchResults();
};

Formats a string based on the data to be displayed.

Example usage:

    var files = 2185;
    var model = { num: files };
    print(Mojo.Format.formatChoice(files, "0#There are no files|1#There is one file|2<#There are #{num} files.", model);

Output:

    There are 2185 files.

Formats the provided date object based on the specified options. Returns String.

options object properties:

Formats the date object based on the specified parameters. Returns String containing the formatted date.

options object properties:

Returns a zero-based index Number indicating what day is the first day of the country's or region's calendar week: Sunday: 0 Monday: 1 Tuesday: 2 etc.

options object properties:

Returns True if the current locale normally uses AM/PM as opposed to 24 hour time.

options object properties:

Returns True if the current app is using AM/PM instead of 24 hour time.  Otherwise, returns False.

Formats the provided number as a locale-based currency string.  Returns String.

options object properties:

Converts a number into a percent string using a locale-based format. Returns String.

options object properties:

Formats a number into a percent string using a locale-based format. Returns String.

options object properties:

Returns a String indicating the current timezone of the device.

Searches the specified text for URLs (web and mailto) and emoticons (if support is enabled) and returns a new String with those entities replaced by HTML links and images (respectively). 

Function to "debounce" multiple calls to a function, causing it to be called only once.  Can also be used to call a seconday function if the primary function has not been called after some specified delay.  Returns wrapped onCall function that can be called like the original function.  Upon calling the wrapped function, the onCall function is called immediately and the onTimeout function called if the wrapper is not called again within the specified delay.  Arguments passed to the onTimeout function are the same as those passed to the last call of the wrapped function.

Example usage:

// this.clearSearchString() will be called 1 second after the most recent call to this.delayedClear().

this.delayedClear = Mojo.Function.debounce(undefined, this.clearSearchString.bind(this), 1, this.controller.window);

Class used to ensure a set of functions are called simultaneously.  After creating a Mojo.Function.Synchronize object, the wrap() method can then be used to wrap callbacks to be synchronized before passing them to an asynchronous service.  The Synchronize object will "collect" the asynchronous callbacks until all have been received, then call the wrapped functions simultaneously.

Example usage:

    var synchronizer = new Mojo.Function.Synchronize({
                        syncCallback: this.continueSceneTransition()});
    var doNothing = function() {};
    var otherWrapper = synchronizer.wrap(doNothing);

    curScene.aboutToActivate(synchronizer.wrap(doNothing));
    beginOtherOperation(otherWrapper);

inOptions object properties:

Function to wrap a function within a Mojo.Function.Synchronize object so that it is called simultaneously with all other wrapped callbacks.  Returns wrapped Function that can be passed instead of the original callback function.

Example usage:

     var synchronizer = new Mojo.Function.Synchronize({
                        syncCallback: this.continueSceneTransition()});
    var doNothing = function() {};
    var otherWrapper = synchronizer.wrap(doNothing);

    curScene.aboutToActivate(synchronizer.wrap(doNothing));
    beginOtherOperation(otherWrapper);

Function to add standard logging methods to an object's prototype.

Example usage:

Adds logging methods to every scene controller:

    Mojo.Log.addLoggingMethodsToPrototype(Mojo.Controller.SceneController);

Allowing you to access logging from scene assistants:

    this.controller.info("Welcome to the dollhouse.");

Function to write an error message to the log.

Parameters passed to a logging function are concatenated together using Array.join() with a single space separating each parameter.

Example usage:

    Mojo.Log.error("I have", 3, "eggs.");

Output:

    "I have 3 eggs."

Function to write an informational message to the log.

Parameters passed to a logging function are concatenated together using Array.join() with a single space separating each parameter.

Example usage:

    Mojo.Log.info("I have", 3, "eggs.");

Output:

    "I have 3 eggs."

Function to log an exception.

Function to log all properties of an object.  Outputs one property per line.

Function to log a string containing all non-function properties of an object.

Function to write a warning message to the log.

Parameters passed to a logging function are concatenated together using Array.join() with a single space separating each parameter.

Example usage:

    Mojo.Log.warn("I have", 3, "eggs.");

Output:

    "I have 3 eggs."

Function to format model properties.  Returns decorator Object containing formatted properties.

Example usage:

var obj = Mojo.Model.format(this.controller.model, this.controller.attributes.formatters);

Function to create a decorator object from a specified "original" object.  Properties can be added to or modified in the decorator object without affecting the original object.  Useful for widgets that need to add properties to the model in preparation for rendering. Returns Object.

Function to decrypt a blowfish-encoded string.  Returns a base64 decoded String.

Example usage:

    var key = "sfhjasf7827387af9s7d8f";
    var in_string = "This is a test string.";

    var encrypted_string = Mojo.Model.encrypt( key, in_string );

    var decrypted_string = Mojo.Model.decrypt( key, encrypted_string );

Function to encrypt a string using blowfish encryption.  Returns a base64-encoded String.

Example usage:

    var key = "sfhjasf7827387af9s7d8f";
    var in_string = "This is a test string.";

    var encrypted_string = Mojo.Model.encrypt( key, in_string );

    var decrypted_string = Mojo.Model.decrypt( key, encrypted_string );

Creates a cookie object with the specified name.

Example usage:

//Get preferences cookie, or create it 
this.cookie = new Mojo.Model.Cookie("NewsPrefs"); 
var oldNewsPrefs = this.cookie.get(); 
if (oldNewsPrefs) { 
    if (oldNewsPrefs.newsVersionString == "1.0"){ 
            featureIndexFeed = oldNewsPrefs.featureIndexFeed; 
            featureFeedEnable = oldNewsPrefs.featureFeedEnable; 
            featureStoryInterval = oldNewsPrefs.featureStoryInterval; 
            feedUpdateInterval = oldNewsPrefs.feedUpdateInterval; 
            updateDialog = oldNewsPrefs.updateDialog; 
     } else { 
            this.cookie.put(){ 
               featureIndexFeed: featureIndexFeed, 
               featureFeedEnable: featureFeedEnable, 
               feedUpdateInterval: feedUpdateInterval, 
               featureStoryInterval: featureStoryInterval, 
               newsVersionString: newsVersionString 
            } 
    } 
} 

Returns the object stored in the cookie, or undefined if the cookie does not exist.

Example usage:

//Get preferences cookie, or create it 
this.cookie = new Mojo.Model.Cookie("NewsPrefs"); 
var oldNewsPrefs = this.cookie.get(); 
if (oldNewsPrefs) { 
    if (oldNewsPrefs.newsVersionString == "1.0"){ 
            featureIndexFeed = oldNewsPrefs.featureIndexFeed; 
            featureFeedEnable = oldNewsPrefs.featureFeedEnable; 
            featureStoryInterval = oldNewsPrefs.featureStoryInterval; 
            feedUpdateInterval = oldNewsPrefs.feedUpdateInterval; 
            updateDialog = oldNewsPrefs.updateDialog; 
     } else { 
            this.cookie.put(){ 
               featureIndexFeed: featureIndexFeed, 
               featureFeedEnable: featureFeedEnable, 
               feedUpdateInterval: feedUpdateInterval, 
               featureStoryInterval: featureStoryInterval, 
               newsVersionString: newsVersionString 
            } 
    } 
} 

Creates or updates the value of this cookie.

Example usage:

  this.stageAssistant.cookie.put(        {
      featureIndexFeed: this.featureFeedListModel.value,
      featureFeedEnable: this.featureFeedToggleModel.value,
      feedUpdateInterval: this.feedIntervalModel.value,
      newsVersionString: newsVersionString,
      featureStoryInterval: featureStoryInterval
  });

Deletes the cookie.

Example usage:

//Get preferences cookie, or create it 
this.cookie = new Mojo.Model.Cookie("NewsPrefs"); 
var oldNewsPrefs = this.cookie.get(); 
if (oldNewsPrefs) { 
    if (oldNewsPrefs.newsVersionString == "1.0"){ 
            featureIndexFeed = oldNewsPrefs.featureIndexFeed; 
            featureFeedEnable = oldNewsPrefs.featureFeedEnable; 
            featureStoryInterval = oldNewsPrefs.featureStoryInterval; 
            feedUpdateInterval = oldNewsPrefs.feedUpdateInterval; 
            updateDialog = oldNewsPrefs.updateDialog; 
     } else { 
            this.cookie.put(){ 
               featureIndexFeed: featureIndexFeed, 
               featureFeedEnable: featureFeedEnable, 
               feedUpdateInterval: feedUpdateInterval, 
               featureStoryInterval: featureStoryInterval, 
               newsVersionString: newsVersionString 
            } 
    } 
};
this.cookie.remove();

Writes an error to the log and throws an exception if expression doesn't evaluate to true.

Mojo.require and Mojo.assert methods are very similar.  The difference is that Mojo.require methods will throw an exception when their requirements aren't met, and are intended to be used in cases where the application cannot reasonably continue if the requirements aren't met.

Returns String containing the error message written to the log.

Example usage:

function(url) {
        Mojo.require(url, "Request requires a url");
        this.url = url;
    },

Writes an error to the log and throws an exception if expectedArray fails the Prototype isArray method. Returns String containing the error message written to the log.

Example usage:

  var names = this.testConstructorFunction[arrayName];
  if (names !== undefined) {
 	Mojo.requireArray(names, "testConstructorFunction." + arrayName +
              " must be undefined or an array.");
	this.functionsToRun = $A(names);
	return;
  }

Writes an error to the log and throws an exception if targetObject wasn't constructed by the passed in constructor function. Returns String containing the error message written to the log.

Writes an error to the log and throws an exception if value evaluates to undefined.  Returns String containing the error message written to the log.

Example usage:

Mojo.Event.listen=function listen(target,type,handlerFunction,useCapture){
  Mojo.requireDefined(target,
    "Mojo.Event.listen: 'target' parameter must be defined.");
  Mojo.requireString(type,"Mojo.Event.listen: 'type' parameter must be a string.");
  Mojo.requireFunction(handlerFunction,
    "Mojo.Event.listen: 'handlerFunction' parameter must be a function.");
  target.addEventListener(type,handlerFunction,!!useCapture);
};

Writes an error to the log and throws an exception if expectedElement fails the Prototype isElement method. Returns String containing the error message written to the log.

Example usage:

Mojo.View.makeFocusable = function(targetElement) {
    Mojo.requireElement(targetElement, "Mojo.View.makeFocusable requires an element.");
    targetElement.setAttribute("tabindex", "0");
};

Writes an error to the log and throws an exception if expected != actual. Returns String containing the error message written to the log.

Example usage:

    db.load(undefined, 0, 1, function(offset, array, totalCount){
    var readNote = array[0];
    Mojo.requireEqual(id, readNote.id);
    Mojo.requireEqual(1, totalCount);
    Mojo.requireFalse(readNote.text);
     
     // Save again all fields!
    note.text = '1';
    note.modifiedTimestamp = 2;
    note.position = 3;
    note.color = '4';
                    
    db.saveNote(note);
    db.loadNoteById(id, function(tx, readNote){
    Mojo.Log.logProperties(readNote);
    Mojo.requireEqual(id, readNote.id);
    Mojo.requireEqual('1', readNote.text);
    Mojo.requireEqual(2, readNote.modifiedTimestamp);
    Mojo.requireEqual(3, readNote.position);
    Mojo.requireEqual('4', readNote.color);
    // Done!
    recordResults(Mojo.Test.passed);
});

Writes an error to the log and throws an exception if expression evaluates to true. Returns String containing the error message written to the log.

Example usage:

    var details = this.detailsTable.get("5551212");
    Mojo.requireFalse(details, "Details must not be found");

Writes an error to the log and throws an exception if expectedFunction fails the Prototype isFunction method. Returns String containing the error message written to the log.

Example usage:

Mojo.Event.listen=function listen(target,type,handlerFunction,useCapture){
  Mojo.requireDefined(target,"Mojo.Event.listen: 'target' parameter must be defined.");
  Mojo.requireString(type,"Mojo.Event.listen: 'type' parameter must be a string.");
  Mojo.requireFunction(handlerFunction,
    "Mojo.Event.listen: 'handlerFunction' parameter must be a function.");
  target.addEventListener(type,handlerFunction,!!useCapture);
};

Writes an error to the log and throws an exception if regex doesn't match testValue.

Writes an error to the log if expectedString fails the Prototype isString method. Returns String containing the error message written to the log.

Writes an error to the log and throws an exception if expectedNumber fails the Prototype isNumber method. Returns String containing the error message written to the log.

Writes an error to the log and throws an exception if targetObject doesn't have the values for the property name or names passed and throws an exception.

Writes an error to the log and throws an exception if expectedString fails the Prototype isString method. Returns String containing the error message written to the log.

Example usage:

Mojo.Event.listen=function listen(target,type,handlerFunction,useCapture){
  Mojo.requireDefined(target,"Mojo.Event.listen: 'target' parameter must be defined.");
  Mojo.requireString(type,"Mojo.Event.listen: 'type' parameter must be a string.");
  Mojo.requireFunction(handlerFunction,
    "Mojo.Event.listen: 'handlerFunction' parameter must be a function.");
  target.addEventListener(type,handlerFunction,!!useCapture);
};

Function to report all timings for a specified category prefix through Mojo.Log.info.

Function to reports timings for scene push/pop operations, labeled with prefix 'scene#'.

Example usage:

        var timing = Mojo.Timing, that = this;
        timing.pause("scene#aboutToActivateLatency");
        timing.resume("scene#activate");
        this._active = true;
        timing.pause("scene#activate");
        var report = function(name) {
            timing.pause('scene#total');
            timing.reportSceneTiming(name, that.window);            
        };
        report.defer(this.sceneName);

Function to report all timings for a specified category prefix through Mojo.Log.info.

Example usage:

    layoutCount = sceneWindow.layoutCount;
    Mojo.Log.info(Mojo.Timing.reportTiming('scene#', "scene '" + sceneName + "': layouts: " + layoutCount));

Function to reset all timings for a specified category.

Function to reset all timers with the specified prefix.

Function to reset timings for scene push/pop operations.

Example usage:

        Mojo.Timing.resetSceneTiming(this.window);
        Mojo.Timing.resume('scene#total');

Function to begin or resume timing for a specified category.

Example usage:

        Mojo.Timing.resetSceneTiming(this.window);
        Mojo.Timing.resume('scene#total');

Function to get a performance timer for a specified category.  Creates the timer if it doesn't exist. Returns Object.

Example usage:

    var timerForCategory = Mojo.Timing.get('category1');
    timerForCategory.resume();

Function to get a list of category strings with a common prefix. Returns Array of Strings.

Example usage:

    var categories = Mojo.Timing.getCategoriesWithPrefix(prefix);
    var makeOneTiming = function(category) {
        var perfTimer = Mojo.Timing.get(category);
        return category.gsub(prefix, '') + ": " + 
           perfTimer.elapsedTime + "ms (" + perfTimer.timesRecorded + ")";
    };
    var timings = categories.collect(makeOneTiming);

Function to pause timing for the specified category.

Example usage:

Mojo.Timing.pause("scene#render");

Function to create a reset performance timer with a particular label.

Function to reset all performance timers.

Constant.

Specifies a quick and subtle cross-fade between scenes.

Example usage:

        var sController = this.controller.stageController;
        sController.popScene();
        sController.pushScene({name: "day", transition: Mojo.Transition.crossFade, 
               disableSceneScroller: true});

Constant.

Specifies the default transition to use when performing a default system defined transition.

Example usage:

this.controller.defaultTransition=Mojo.Transition.none;

Constant.

Specifies that no graphical transition should be used when switching between scene.

Example usage:

this.controller.defaultTransition=Mojo.Transition.none;

Constant.

Specifies a combination zoom and fade transition when a scene is pushed or popped.  This is the default scene transition.  Runs in reverse when scene is popped.

Example usage:

var transition = that.controller.prepareTransition(Mojo.Transition.zoomFade, true);
transition.run();

Adds a pair of locations to be used for loading localized templates.  If a template is specified by full path and the base path is a prefix of the full path, the localized path for the correct locale will be searched for the template first.

Example usage:

    Mojo.View.addTemplateLocation("/templates/", "/templates/localized/, "views");

Adds touch feedback to a new element, removing touch feedback from any currently highlighted element.

Advances the current text focus to the next focusable element in containingElement, or sets it to the first focusable element in the container if nothing in the container currently has focus.

Example usage:

        Mojo.View.advanceFocus(this.controller.scene.sceneElement, this.inputArea);

Converts the provided HTML content into nodes.  Returns the first Element node at the top level of the content.

Example usage:

content = Mojo.View.render({object: itemModel, template: itemModel.template});
node = Mojo.View.convertToNode(content, this.controller.document);

Converts the given html content into nodes and returns a nodelist. A shared rendering div is used for this conversion, so the caller needs to remove the nodes from their parent (the shared div) and should not keep a reference to the nodelist.

Example usage:

        // Set up spacer & content divs:
        spacers = Mojo.View.convertToNodeList("
               <div name='topSpacer' style='background-color:#e4e4e2;'></div>
               <div name='bottomSpacer' style='background-color:#e4e4e2;'></div>", 
               this.controller.document);
        this.topSpacer = spacers[0];
        this.bottomSpacer = spacers[1];
        Element.remove(this.topSpacer);
        Element.remove(this.bottomSpacer);

Returns the currently focused element in containingElement, or null if there is no element that currently has focus.

Example usage:

//use this to blur the currently focused item
focusedElement = Mojo.View.getFocusedElement(this.controller.scene.sceneElement);
if (focusedElement) {
    focusedElement.blur();
}

Marks an element as focusable. Currently implemented by adding a tabindex attribute of value "0".

Example usage:

            var editor = this.controller.element;
            editor.setStyle(this.RICH_TEXT_STYLES);
            Mojo.View.makeFocusable(editor);

Marks an element as not focusable. Currently implemented by removing the tab index value.

Example usage:

Mojo.View.makeNotFocusable(this.inputAreaDiv);

Given a DOM element and a target object, hide the element if the value of any of the named properties are undefined or have a false value in target.

Returns a list of focusable DOM elements in containingElement.

Searches from targetElement up the DOM looking for a Scroller widget that contains targetElement.

Example usage:

var folderContainer = this.controller.get('account_folders_'+rowElement.id);
var scroller = Mojo.View.getScrollerForElement(folderContainer);
if (elementTop > viewPortMidway && scroller) {
   //Using setTimeout to give the animation time enough to 
   //give the div enough height to scroll to
   var scrollToPos = scroller.mojo.getScrollPosition().top - (elementTop - viewPortMidway);
   setTimeout(function() {scroller.mojo.scrollTo(undefined, scrollToPos, true);}, 200);
}

Removes touch feedback from the specified element.

Create HTML markup from one or more objects.

renderParams object properties:

Example usage:

 html = Mojo.View.render(
  {
    object: {
      count: this.targetEventAttendees.attendees.size()
    }, 
    template: 'participants/participant-count'
  }
)
 this.controller.get('partv_count_div').update(html);

Example usage 2:

 var theDate = new Date(date);
            
 var y = Mojo.Format.formatDate(theDate, "yyyy");
 var m = Mojo.Format.formatDate(theDate, "MMM").toUpperCase();
 var d = Mojo.Format.formatDate(theDate, "dd");
 var button = Mojo.View.render({object: {label: $L("Date"), year: y, month: m, day: d},
                                template: "datetime/datePicker"});
 dateDiv.insert(button);
 var items = dateDiv.childElements();
 button = items[items.size() - 1];

Example usage 3:

 var content = Mojo.View.render({collection: songs,
             template: 'list/song', separator: 'list/separator''})
 listElement.innerHTML = content;

Function to check if a specified element and all of its ancestors are visible.  Returns Boolean.