Widgets (Web API)

In order to make the widget system as useful as possible, it features a Web API available as document.widgets. This is used to open, close, cycle, find etc widgets within a document.

Available methods

See the source documents for Widgets.Manager, or the source itself which is here:

PowerUI/Source/Extras/Widgets/Manager.cs

Simple opening of a widget

You'll need a reference to the document you'd like to open the widget in - that's typically either UI.document or aWorldUI.document. Then you use the widgets API like this:

// Open a bank widget using the "floating" template:
Widgets.Widget myWidget = document.widgets.open("floating","UIs/Bank/index.html");

Opening a widget using promise

Some widget templates perform some kind of animation whilst they open. When they're done, they fire the "onload" event. To catch that onload event as a convenient promise, use load instead:

// Open a bank window using the "floating" template:
document.widgets.load("floating","UIs/Bank/index.html").then(delegate(object o){
    
    // o is the successfully opened widget:
    Widgets.Widget myWidget = o as Widgets.Widget;
    
    // myWidget is ready to go!
    
});

Parameters

You can pass extra parameters to an opening widget via the globals dictionary:

// Open a bank widget using the "floating" template
// and an 'initial' parameter of '14':
// (alternatively create a dictionary<string,object> and pass that instead)
Widgets.Widget myWidget = document.widgets.open("floating", "UIs/Bank/index.html", "initial", "14");

Note that the names must be strings, but the values can be anything. Multiple parameters are added like this:

Widgets.Widget myWidget = document.widgets.open(
                                              "floating", "UIs/Bank/index.html",
                                              "initial", "14",
                                              "tab", 1,
                                              "usefulInstance", someObject
                                            );

Just like with the widget:// protocol, these parameters will be set as JavaScript globals for the content to use, and are also made available to the template.

Get the widget that an element is in

It's often useful to obtain the widget object that a particular element is in. It's as simple as this:

// HtmlElement anElement;

// Null if it's not in any widget
Widgets.Widget myWidget=anElement.widget;

Opening a widget relative to another

It's important to note that every widget is also a widget manager. This lets you open a widget "on top" of another one, regardless of their defined stacking order. An example of where this is useful is, for example, fading the screen out and then displaying a pause menu.