Difference between revisions of "Widgets (Web API)"

Revision as of 23:15, 15 March 2017

Note: Not to be confused with the standard window object. In order to make the window system as useful as possible, it features a Web API available as document.sparkWindows. This is used to open, close, cycle, find etc windows within a document.

Available methods

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

PowerUI/Source/Extras/Window System/Manager.cs

Simple opening of a window

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

// Open a bank window using the "floating" template:
Window myWindow = document.sparkWindows.open("floating","UIs/Bank/index.html");

Opening a window using promise

Some window 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.sparkWindows.load("floating","UIs/Bank/index.html").then(delegate(object o){
    
    // o is the successfully opened window:
    Window myWindow = o as Window;
    
    // myWindow is ready to go!
    
});

Parameters

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

// Open a bank window using the "floating" template
// and an 'initial' parameter of '14':
// (alternatively create a dictionary and pass that instead)
Window myWindow = document.sparkWindows.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:

Window myWindow = document.sparkWindows.open(
                                              "floating", "UIs/Bank/index.html",
                                              "initial", "14",
                                              "tab", 1,
                                              "usefulInstance", someObject
                                            );

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

Get the window that an element is in

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

// HtmlElement anElement;

// Null if it's not in any window
Window myWindow=anElement.sparkWindow;

Opening a window relative to another

It's important to note that every window is also a window manager. This lets you open a window "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.