enyo.windows

enyo.windows provides a variety of utility methods for interacting with application windows.

To open a window or activate an existing window, call enyo.windows.activate. For example:

enyo.windows.activate(undefined, "SearchWindow");

Or, to open the window if it does not exist, add a url (the url may be absolute or relative).

enyo.windows.activate("search/index.html", "SearchWindow");

To facilitate communication between application windows, parameters can be sent. To send parameters to the window to be activated, add a params object:

enyo.windows.activate("search/index.html", "SearchWindow",
  {query: "oranges"});

Note that the activated window will fire a windowParamsChange event. The window parameters are available in the enyo.windowParams object.

windowParamsChangeHandler: function() {
  this.$.searchQueryInput.setValue(enyo.windowParams.query);
}

To send parameters to a window without activating it, use the setWindowParams method. For example:

var searchWindow = enyo.windows.fetchWindow("SearchWindow");
enyo.windows.setWindowParams(searchWindow, {safeSearch: true});

When a window is activated and deactivated by the user or system, corresponding events will fire on any created enyo.ApplicationEvents objects. To respond to activation, provide a listener for its onWindowActivated event; to respond to deactivation, provide a hander for onWindowDeactivated.

{kind: enyo.ApplicationEvents, onWindowActivated: "wakeup",
  onWindowDeactivated: "sleep"}

An application may be launched while it is already running (relaunch). By default, the application is simply brought into focus when this happens. This can occur either when a user launches the running application or a system service does so. In either case, new window params may be sent to the application. An application can customize its response to being relaunched based on this information by implementing a handler for the onApplicationRelaunch event as follows:

{kind: enyo.ApplicationEvents, onApplicationRelaunch: "relaunchHandler"},
...
relaunchHandler: function(inSender, inEvent) {
  if (enyo.windowParams.openSearchWindow = true) {
      enyo.windows.activate("search/index.html", "SearchWindow");
      return true;
  }
},
...

Notice that the event handler activates a window and then returns true. The return value indicates that the event has been handled and the default action, focusing the root application window, should not occur.

The applicationRelaunch event is always sent to the root window of an application. The root window is, by default, the first window created by the application. The window-level handler passes on the event to the various enyo.ApplicationEvents objects that have been created.

When the application is headless (i.e., it specifies noWindow: true in its appinfo.json file), the root window is always the headless, non-displayed window. When the application is not headless, the root window may change. This occurs if the user closes the root window. In this case, the root window becomes the next window opened by the application. That window will now receive the applicationRelaunch event.

Applications should be careful to consider that on the root window, the enyo.windowParams object is set by the system. On other windows, this object is private to the application. Applications may treat the applicationRelaunch as an indicator that enyo.windowParams has been changed by the system.

Methods

activate(inUrl, inName, inParams, inAttributes, inWindowInfo)

Activates an application window by name. If the window is not already open, and a url is specified, the window will be opened.

Parameters

Name Type Description
inUrl String URL for the window to open if it is not already opened. May be absolute or relative.
inName String Name of the window to activate
inParams Object Data to send to the activated window. Will be available as enyo.windowParams.
inAttributes Object (Optional) Window attributes, used to customize the window type
inWindowInfo String (Optional) Window information, used to provide extra system info

Example

enyo.windows.activate("search/index.html", "Search", {query: "oranges"});

activateWindow(inWindow, inParams)

Activates a window by window reference, optionally sending window params to the window.

Parameters

Name Type Description
inWindow Object Reference to the window to be activated
inParams Object (Optional) Window params to send to the window

Example

enyo.windows.activateWindow(myWindow, {message: "Hello World"});

addBannerMessage(inMessage, inJson, inIcon, inSoundClass, inSoundPath, inSoundDuration)

Adds a banner message that will be displayed briefly before disappearing.

Parameters

Name Description
inMessage Message to display
inJson JSON-formatted string to pass to enyo.relaunch if banner is tapped
inIcon (Optional) Icon to display
inSoundClass (Optional) Sound class to play
inSoundPath (Optional) Path to sound to play
inSoundDuration (Optional) Duration of sound to play

deactivate(inName)

Deactivates a window by name.

deactivateWindow(inWindow)

Deactivates a window by reference.

fetchWindow(inName)

Returns a reference to the window object specified by the given name.

The specified name must correspond to a currently opened application window, i.e., a window in the list returned by enyo.windows.getWindows().

getActiveWindow()

Returns a reference to the window object of the currently active application window.

getRootWindow()

Returns the root application window.

getWindows()

Returns an object listing the open windows by name, e.g.:

{window1: <window object>, window2: <window object> }

openDashboard(inUrl, inName, inParams, inAttributes)

Opens an application dashboard.

Parameters

Name Type Description
inUrl String URL for the window's HTML file. May be absolute or relative.
inName String Name of the window. This name can be used to retrieve the window. If one is not specified, a default name is supplied.
inParams Object Data to send to the opened window. Will be available as enyo.windowParams.
inAttributes Object Specifies optional attributes, e.g., {webosDragMode: "manual"} to enable custom handling of drag events in dashboards, or {clickableWhenLocked: true} to make dashboards usable through the lock screen.

openPopup(inUrl, inName, inParams, inAttributes, inHeight, throb)

Opens an application popup.

Parameters

Name Type Description
inUrl String URL for the window's HTML file. May be absolute or relative.
inName String Name of the window. This name can be used to retrieve the window. If one is not specified, a default name is supplied.
inParams Object Data to send to the opened window. Will be available as enyo.windowParams.
inAttributes Object Specifies optional attributes for special behavior.
inHeight Integer Height of the popup
throb Boolean If true, enables the LED throbber.

openWindow(inUrl, inName, inParams, inAttributes, inWindowInfo)

Opens an application window. This method can also be used to open a specialized window by specifying inAttributes and inWindowInfo.

Parameters

Name Type Description
inUrl String URL for the window's HTML file. May be absolute or relative.
inName String Name of the window. This name can be used to retrieve the window. If one is not specified, a default name is supplied.
inParams Object Data to send to the opened window. Will be available as enyo.windowParams.
inAttributes Object (Optional) Window attributes, used to customize the window type.
inWindowInfo String (Optional) Window information, used to provide extra system info.

Example

enyo.windows.openWindow("search/index.html", "Search",
  {query: "oranges"});

removeBannerMessage(inId)

Removes a banner message. inId is a value returned by addBannerMessage.

renameWindow(inWindow, inName)

Renames a window. Note that the final window name could be different from the one specified, if a collision occurs.

setWindowParams(inWindow, inParams)

Sends parameters to the given window. Application windows can communicate by sending window parameters to each other. Note that this method does not activate the window; if you want to activate the window, use enyo.windows.activate.

The window specified by inWindow will fire a windowParamsChange event asynchronously. This event can be handled so as to perform work related to the change in window parameters.

Parameters

Name Type Description
inWindow Object Window reference
inParams Object Parameters to send to the window. This object will be made available as enyo.windowParams. Restricted to valid JSON (i.e., no functions, cycles, etc.).

setWindowProperties(inWindow, inProps)

Sets webOS system properties of the window. Pass in a window reference to modify (use 'window' for self) and a JavaScript object with name/value pairs as inProps.

Possible properties of inProps include the following:

Name Type Description
blockScreenTimeout Boolean If true, the screen will not dim or turn off in the absence of user activity. If false, the timeout behavior will be reinstated.
setSubtleLightbar Boolean If true, makes the light bar somewhat dimmer than normal. If false, it will return to normal.
fastAccelerometer Boolean If true, the accelerometer rate will increase to 30 hz. The default value is false, with a rate of 4 hz. Note that the fast rate only applies to apps that are maximized.