Difference between revisions of "Widgets (Web API)"

From PowerUI
Jump to: navigation, search
(Available methods)
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''Note: Not to be confused with the standard window object.''' In order to make the [[Window Manager|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.
+
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 Windows.Manager], or the source itself which is here:
+
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/Window System/Manager.cs
+
PowerUI/Source/Extras/Widgets/Manager.cs
 
</blockquote>
 
</blockquote>
  
== Simple opening of a window ==
+
== Simple opening of a widget ==
  
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:
+
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 window using the "floating" template:
+
// Open a bank widget using the "floating" template:
Window myWindow = document.sparkWindows.open("floating","UIs/Bank/index.html");
+
Widgets.Widget myWidget = document.widgets.open("floating","UIs/Bank/index.html");
  
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Opening a window using promise ==
+
== Opening a widget 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:
+
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.sparkWindows.load("floating","UIs/Bank/index.html").then(delegate(object o){
+
document.widgets.load("floating","UIs/Bank/index.html").then(delegate(object o){
 
      
 
      
     // o is the successfully opened window:
+
     // o is the successfully opened widget:
     Window myWindow = o as Window;
+
     Widgets.Widget myWidget = o as Widgets.Widget;
 
      
 
      
     // myWindow is ready to go!
+
     // myWidget is ready to go!
 
      
 
      
 
});
 
});
Line 40: Line 40:
 
== Parameters ==
 
== Parameters ==
  
You can pass extra parameters to an opening window via the globals dictionary:
+
You can pass extra parameters to an opening widget via the globals dictionary:
  
 
<syntaxhighlight lang="csharp">
 
<syntaxhighlight lang="csharp">
  
// Open a bank window using the "floating" template
+
// Open a bank widget using the "floating" template
 
// and an 'initial' parameter of '14':
 
// and an 'initial' parameter of '14':
Window myWindow = document.sparkWindows.open("floating","UIs/Bank/index.html","initial","14");
+
// (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>
  
Just like with the [[Window Protocol|window:// protocol]], these parameters will be set as JavaScript globals for the content to use, and are also made available to the template.
 
  
 +
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 window that an element is in ==
+
== Get the widget 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:
+
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 window
+
// Null if it's not in any widget
Window myWindow=anElement.sparkWindow;
+
Widgets.Widget myWidget=anElement.widget;
  
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Opening a window relative to another ==
+
== Opening a widget 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, [[Screen Fading (Fade to black/ Whiteouts)|fading the screen out]] and then displaying a pause menu.
+
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.

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.