Difference between revisions of "Widgets (Web API)"
From PowerUI
Bablakeluke (talk | contribs) (→Parameters) |
Bablakeluke (talk | contribs) |
||
| (3 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | + | In order to make the [[Widget Manager|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 == | == Available methods == | ||
| − | See the source documents for [http://powerui.kulestar.com/powerdocs-2_0/classWindows_1_1Manager.html | + | See the source documents for [http://powerui.kulestar.com/powerdocs-2_0/classWindows_1_1Manager.html Widgets.Manager], or the source itself which is here: |
<blockquote> | <blockquote> | ||
| − | PowerUI/Source/Extras/ | + | PowerUI/Source/Extras/Widgets/Manager.cs |
</blockquote> | </blockquote> | ||
| − | == Simple opening of a | + | == Simple opening of a widget == |
| − | You'll need a reference to the document you'd like to open the | + | 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: |
<syntaxhighlight lang="csharp"> | <syntaxhighlight lang="csharp"> | ||
| − | // Open a bank | + | // Open a bank widget using the "floating" template: |
| − | + | Widgets.Widget myWidget = document.widgets.open("floating","UIs/Bank/index.html"); | |
</syntaxhighlight> | </syntaxhighlight> | ||
| − | == Opening a | + | == Opening a widget using promise == |
| − | Some | + | 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: |
<syntaxhighlight lang="csharp"> | <syntaxhighlight lang="csharp"> | ||
// Open a bank window using the "floating" template: | // Open a bank window using the "floating" template: | ||
| − | document. | + | document.widgets.load("floating","UIs/Bank/index.html").then(delegate(object o){ |
| − | // o is the successfully opened | + | // o is the successfully opened widget: |
| − | + | Widgets.Widget myWidget = o as Widgets.Widget; | |
| − | // | + | // myWidget is ready to go! |
}); | }); | ||
| Line 40: | Line 40: | ||
== Parameters == | == Parameters == | ||
| − | You can pass extra parameters to an opening | + | You can pass extra parameters to an opening widget via the globals dictionary: |
<syntaxhighlight lang="csharp"> | <syntaxhighlight lang="csharp"> | ||
| − | // Open a bank | + | // Open a bank widget using the "floating" template |
// and an 'initial' parameter of '14': | // and an 'initial' parameter of '14': | ||
| − | // (alternatively create a dictionary and pass that instead) | + | // (alternatively create a dictionary<string,object> and pass that instead) |
| − | + | Widgets.Widget myWidget = document.widgets.open("floating", "UIs/Bank/index.html", "initial", "14"); | |
| + | |||
| + | </syntaxhighlight> | ||
| + | |||
| + | Note that the names must be strings, but the values can be anything. Multiple parameters are added like this: | ||
| + | |||
| + | <syntaxhighlight lang="csharp"> | ||
| + | |||
| + | Widgets.Widget myWidget = document.widgets.open( | ||
| + | "floating", "UIs/Bank/index.html", | ||
| + | "initial", "14", | ||
| + | "tab", 1, | ||
| + | "usefulInstance", someObject | ||
| + | ); | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | |||
| − | == Get the | + | Just like with the [[Widget Protocol|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 | + | It's often useful to obtain the widget object that a particular element is in. It's as simple as this: |
<syntaxhighlight lang="csharp"> | <syntaxhighlight lang="csharp"> | ||
| Line 61: | Line 75: | ||
// HtmlElement anElement; | // HtmlElement anElement; | ||
| − | // Null if it's not in any | + | // Null if it's not in any widget |
| − | + | Widgets.Widget myWidget=anElement.widget; | |
</syntaxhighlight> | </syntaxhighlight> | ||
| − | == Opening a | + | == Opening a widget relative to another == |
| − | It's important to note that ''every'' | + | It's important to note that ''every'' widget is also a [[Widget Manager|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, [[Screen Fading (Fade to black/ Whiteouts)|fading the screen out]] and then displaying a pause menu. |
Latest revision as of 16:41, 18 March 2017
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.
Contents
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.
