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.
|