PowerUI - User contributions [en]

Browsers

2018-12-06T23:21:12Z

Bablakeluke: /* Websites vs UI's */

'''PowerUI is not a web browser - it's a UI framework.''' PowerUI isn't simply a wrapper for Chrome - it's been built from scratch and it's now rapidly becoming the newest web engine in nearly 15 years. Standing at nearly 300,000 lines of code, PowerUI is a massive toolbox for all your UI needs. As it's also based on widely used standard technology, getting started with it is as simple as it gets!

== Websites vs UI's ==
Every now and then, people ask why PowerUI isn't just a wrapper for some existing web engine. Why are we going to the effort of building an entirely new one 'inside' Unity. It's because websites and user interfaces have extremely different requirements. Consider this:

=== A browser must.. ===

* Load a website as fast as possible
* Display very static websites; load time is more important than runtime performance
* Be extremely secure

=== A UI must.. ===

* Tightly integrate with your code and the engine ''(opposite of secure!)''
* Be very dynamic - UI's are not static at all and can acceptably spend more time loading ''(opposite of the loading focus of a browser!)''
* Be easy to extend in order to represent as many UI concepts as possible
* Not have awkward platform barriers

Ideally we also shouldn't need to introduce 400mb+ of bloat in a project just for UIs; PowerUI is essentially designed to be ultra compact and modular in order to simply remove features that aren't needed.

== What PowerUI can do ==

PowerUI focuses on the goals of a UI framework. As a result it can:

* Just work (and be exactly the same) on any platform
* Advanced text formatting (like knockout text)
* Shading/ Lighting
* 3D text
* Widget system
* Context menu's
* Style scrollbars and carets
* Dialogue system
* Easy to localise
* Extremely customisable - design a new html element etc
* Particle systems and camera's on your UI
* Use any part of the engine anywhere (It's all C# after all!). GIF's/ SVG's on meshes, or on other UI frameworks, for example.
* Lots more!

Many of these things are difficult or simply impossible for an embedded browser.

== So can I use it like a browser? ==

''Sort of'', but that's not what it's designed for. PowerUI has extremely broad coverage of web technologies, but these things currently limit it from being a general purpose browser:

* Stacking contexts aren't supported (for runtime performance reasons). This will make some elements on the web stack in strange orders.
* Flexbox/ grid aren't supported yet.
* JavaScript - Due to limitations on iOS and many consoles, PowerUI has a custom variant of JS called Nitro. We're now experimenting with fully compliant Javascript at the moment which you can get from the [[Source Control (GIT)|PowerUI source repository]].

Currently, these things are all being worked on - PowerUI compiles in under 10 seconds, so we can iterate on new features much, much faster than any conventional browser can (and we don't have the weight of a massive userbase limiting awesome new features either!).

Throttling

2018-11-29T22:25:26Z

Bablakeluke:

By default, PowerUI will dispatch all web requests immediately. This can result in scenarios where large amounts of UI's being created at once can hit a server hard, and potentially result in the server throttling your requests or outright rejecting them. You can limit this using the built in max request limit:

<syntaxhighlight lang="csharp">
// During setup
PowerUI.Http.Web.MaxSimultaneousRequests = 6;
</syntaxhighlight>

Using '6' essentially matches Chrome. This will restrict the maximum number of simultaneous HTTP/S requests leaving PowerUI to the number you specify. The default is -1 meaning no limit. Any additional requests made will simply wait in a queue until prior requests complete.

Throttling

2018-11-29T22:22:46Z

Bablakeluke: Created page with "By default, PowerUI will dispatch all web requests immediately. This can result in scenarios where large amounts of UI's being created at once can hit a server hard, and poten..."

By default, PowerUI will dispatch all web requests immediately. This can result in scenarios where large amounts of UI's being created at once can hit a server hard, and potentially result in the server throttling your requests or outright rejecting them. You can limit this using the built in max request limit:

<syntaxHighlighting lang="csharp">
// During setup
PowerUI.Http.Web.MaxSimultaneousRequests = 6;
</syntaxHighlighting>

Using '6' essentially matches Chrome. This will restrict the maximum number of simultaneous HTTP/S requests leaving PowerUI to the number you specify. The default is -1 meaning no limit. Any additional requests made will simply wait in a queue until prior requests complete.

World UI

2018-04-02T16:14:56Z

Bablakeluke: /* Flat World UI */

Sometimes you might want to create something 2D in your 3D world - for example, showing health above a player, a tv screen, integration with NGUI, billboards or something a little more, well, original..

[[File:WorldUI-Intro.png]]

They come in two flavours:

== Ordinary World UI ==

These are true 3D and are typically what you'd use if you want to make use of the [[Text Extrude|text-extrude CSS property]]. If you want to make one in the editor, go to:

''GameObject > UI > PowerUI > In World UI''

You'll then get a previewer which will show you where the UI will appear. Note that the "WorldUI Helper" component is intended to be more of a guideline so it's recommended to take a look at the source.

You can then access the DOM dynamically via a WorldUIHelper like this:

<syntaxhighlight lang="csharp">

// Get that created gameobject via any regular Unity method:
var myWorldUI = GameObject.Find("My WorldUI GameObject");

// Get the doc from it:
var document = myWorldUI.GetComponent<WorldUIHelper>().document;

// use the standard Web API's from here:
document.getElementById("hello-all").innerHTML = "Hello World!";

</syntaxhighlight>

Typically these WorldUI's are instanced dynamically, so to do this either parent the above to a Unity prefab and [https://docs.unity3d.com/Manual/InstantiatingPrefabs.html instantiate the prefab like normal], or directly use the [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html WorldUI scripting class]:

<syntaxhighlight lang="csharp">

// Create a WorldUI:
WorldUI myWorldUI = new WorldUI("optional-name", 200, 30);

// Auto pixel perfect scaling:
myWorldUI.PixelPerfect = true;

// Either write to innerHTML or navigate it:
myWorldUI.document.innerHTML="Hello world (literally!)";

</syntaxhighlight>

Note that with these true 3D World UI's, you must be '''very careful with the gameObject's scale on the z axis (its depth - the depth spacing between your UI elements)'''. If you set it too small, or even zero, you'll start experiencing [https://en.wikipedia.org/wiki/Z-fighting z-fighting] which means the UI will flicker. You can also use this to your advantage however - setting the z scale quite high gives a very unique looking perspective effect which is particularly powerful in VR. If you want it to be completely flat, create a "flat" WorldUI instead (below).

== Flat World UI ==

These are your more traditional in world UI's where it's rendered to an image, then the image is displayed in the gameworld however you wish. They are slower than ordinary WorldUI's because of that extra texture step, but they are a lot more flexible in terms of how they can be displayed. To create one:

''GameObject > UI > PowerUI > In World UI''

Then tick the "Make it flat" checkbox. Alternatively, like with 3D WorldUI's, you can also make them programattically too:

<syntaxhighlight lang="csharp">

// Create a FlatWorldUI (200px x 200px):
FlatWorldUI ui = new FlatWorldUI("optional-name", 200, 200);

// Set the innerHTML however you'd like (e.g. via this helper, or write, or doc.location etc).
ui.document.innerHTML="Hello flat world!";

</syntaxhighlight>

As the surface can be literally any shape, they require slightly specialized input handling. Use [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#a9ffa3ae9d8b52a0fa33f810d54048d3a ResolvePoint] if you'd like to map a ray hit to a point in pixels:

<syntaxhighlight lang="csharp">

// RaycastHit aRayHit;
// FlatWorldUI myUI;

// The point in pixels:
Vector2 pointInPixels = myUI.ResolvePoint(aRayHit);

// E.g. get an element at that point using the standard web API method:
var element = document.elementFromPoint(pointInPixels.x, pointInPixels.y);

</syntaxhighlight>

== Destroying a WorldUI ==

[[File:WorldUI-Destroy.png]]

You can destroy a WorldUI by simply destroying its GameObject, or call [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#ad5552c4e2e56cfaf567c9392317988f6 Destroy] on the WorldUI or FlatWorldUI instance.

== WorldUI Origin ==

[[File:WorldUI-Origin.png]]

By default the origin of an ordinary (not flat) WorldUI is right in the middle. You can move it with [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#a15f5d652a8c01b6ecf3e8db7216b2e01 SetOrigin]:

<syntaxhighlight lang="csharp">

// Change its origin:
myWorldUI.SetOrigin(1f, 1f);

</syntaxhighlight>

Text Extrude

2018-04-02T16:13:55Z

Bablakeluke: /* Usage */

PowerUI's text library [[InfiniText]] loads fonts directly which gives it full access to all of the glyphs. There's lots of ways in which that can be exploited, and one example is the non-standard CSS text-extrude property. It is designed for use on a [[World UI]] so you can, for example, display e.g. "CITY LIBRARY" in localized, formatted, 3D text within your game.

== Usage ==

It's as simple as declaring a CSS property:

<syntaxhighlight lang="css">

text-extrude: <length>

</syntaxhighlight>

The length is how far, in world units, to extrude the text. Other formatting, such as bold/ italic/ underlines and the colour will all be adopted by the 3D variant. It will also be located exactly where the flat version of the text would've been, so you can use any positioning that you wish with it.

Essentially, 3D text with the complete power of a layout engine.

World UI

2018-04-02T16:12:17Z

Bablakeluke: /* Ordinary World UI */

Sometimes you might want to create something 2D in your 3D world - for example, showing health above a player, a tv screen, integration with NGUI, billboards or something a little more, well, original..

[[File:WorldUI-Intro.png]]

They come in two flavours:

== Ordinary World UI ==

These are true 3D and are typically what you'd use if you want to make use of the [[Text Extrude|text-extrude CSS property]]. If you want to make one in the editor, go to:

''GameObject > UI > PowerUI > In World UI''

You'll then get a previewer which will show you where the UI will appear. Note that the "WorldUI Helper" component is intended to be more of a guideline so it's recommended to take a look at the source.

You can then access the DOM dynamically via a WorldUIHelper like this:

<syntaxhighlight lang="csharp">

// Get that created gameobject via any regular Unity method:
var myWorldUI = GameObject.Find("My WorldUI GameObject");

// Get the doc from it:
var document = myWorldUI.GetComponent<WorldUIHelper>().document;

// use the standard Web API's from here:
document.getElementById("hello-all").innerHTML = "Hello World!";

</syntaxhighlight>

Typically these WorldUI's are instanced dynamically, so to do this either parent the above to a Unity prefab and [https://docs.unity3d.com/Manual/InstantiatingPrefabs.html instantiate the prefab like normal], or directly use the [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html WorldUI scripting class]:

<syntaxhighlight lang="csharp">

// Create a WorldUI:
WorldUI myWorldUI = new WorldUI("optional-name", 200, 30);

// Auto pixel perfect scaling:
myWorldUI.PixelPerfect = true;

// Either write to innerHTML or navigate it:
myWorldUI.document.innerHTML="Hello world (literally!)";

</syntaxhighlight>

Note that with these true 3D World UI's, you must be '''very careful with the gameObject's scale on the z axis (its depth - the depth spacing between your UI elements)'''. If you set it too small, or even zero, you'll start experiencing [https://en.wikipedia.org/wiki/Z-fighting z-fighting] which means the UI will flicker. You can also use this to your advantage however - setting the z scale quite high gives a very unique looking perspective effect which is particularly powerful in VR. If you want it to be completely flat, create a "flat" WorldUI instead (below).

== Flat World UI ==

These are your more traditional in world UI's where it's rendered to an image, then the image is displayed in the gameworld however you wish. They are slower than ordinary WorldUI's because of that extra texture step, but they are a lot more flexible in terms of how they can be displayed:

<syntaxhighlight lang="csharp">

// Create a FlatWorldUI (200px x 200px):
FlatWorldUI ui = new FlatWorldUI("optional-name", 200, 200);

// Set the innerHTML however you'd like (e.g. via this helper, or write, or doc.location etc).
ui.document.innerHTML="Hello flat world!";

</syntaxhighlight>

As the surface can be literally any shape, they require slightly specialized input handling. Use [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#a9ffa3ae9d8b52a0fa33f810d54048d3a ResolvePoint] if you'd like to map a ray hit to a point in pixels:

<syntaxhighlight lang="csharp">

// RaycastHit aRayHit;
// FlatWorldUI myUI;

// The point in pixels:
Vector2 pointInPixels = myUI.ResolvePoint(aRayHit);

// E.g. get an element at that point using the standard web API method:
var element = document.elementFromPoint(pointInPixels.x, pointInPixels.y);

</syntaxhighlight>

== Destroying a WorldUI ==

[[File:WorldUI-Destroy.png]]

You can destroy a WorldUI by simply destroying its GameObject, or call [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#ad5552c4e2e56cfaf567c9392317988f6 Destroy] on the WorldUI or FlatWorldUI instance.

== WorldUI Origin ==

[[File:WorldUI-Origin.png]]

By default the origin of an ordinary (not flat) WorldUI is right in the middle. You can move it with [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#a15f5d652a8c01b6ecf3e8db7216b2e01 SetOrigin]:

<syntaxhighlight lang="csharp">

// Change its origin:
myWorldUI.SetOrigin(1f, 1f);

</syntaxhighlight>

World UI

2018-04-02T16:06:34Z

Bablakeluke: /* Ordinary World UI */

Sometimes you might want to create something 2D in your 3D world - for example, showing health above a player, a tv screen, integration with NGUI, billboards or something a little more, well, original..

[[File:WorldUI-Intro.png]]

They come in two flavours:

== Ordinary World UI ==

These are true 3D and are typically what you'd use if you want to make use of the [[Text Extrude|text-extrude CSS property]]. If you want to make one in the editor, go to:

''GameObject > UI > PowerUI > In World UI''

You'll then get a previewer which will show you where the UI will appear. Note that the "WorldUI Helper" component is intended to be more of a guideline so it's recommended to take a look at the source.

You can then access the DOM dynamically via a WorldUIHelper like this:

<syntaxhighlight lang="csharp">

// Get that created gameobject via any regular Unity method:
var myWorldUI = GameObject.Find("My WorldUI GameObject");

// Get the doc from it:
var document = myWorldUI.GetComponent<WorldUIHelper>().document;

// use the standard Web API's from here:
document.getElementById("hello-all").innerHTML = "Hello World!";

</syntaxhighlight>

Typically these WorldUI's are instanced dynamically, so to do this either parent the above to a Unity prefab and [https://docs.unity3d.com/Manual/InstantiatingPrefabs.html instantiate the prefab like normal], or directly use the [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html WorldUI scripting class]:

<syntaxhighlight lang="csharp">

// Create a WorldUI:
WorldUI myWorldUI = new WorldUI("optional-name", 200, 30);

// Auto pixel perfect scaling:
myWorldUI.PixelPerfect = true;

// Either write to innerHTML or navigate it:
myWorldUI.document.innerHTML="Hello world (literally!)";

</syntaxhighlight>

== Flat World UI ==

These are your more traditional in world UI's where it's rendered to an image, then the image is displayed in the gameworld however you wish. They are slower than ordinary WorldUI's because of that extra texture step, but they are a lot more flexible in terms of how they can be displayed:

<syntaxhighlight lang="csharp">

// Create a FlatWorldUI (200px x 200px):
FlatWorldUI ui = new FlatWorldUI("optional-name", 200, 200);

// Set the innerHTML however you'd like (e.g. via this helper, or write, or doc.location etc).
ui.document.innerHTML="Hello flat world!";

</syntaxhighlight>

As the surface can be literally any shape, they require slightly specialized input handling. Use [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#a9ffa3ae9d8b52a0fa33f810d54048d3a ResolvePoint] if you'd like to map a ray hit to a point in pixels:

<syntaxhighlight lang="csharp">

// RaycastHit aRayHit;
// FlatWorldUI myUI;

// The point in pixels:
Vector2 pointInPixels = myUI.ResolvePoint(aRayHit);

// E.g. get an element at that point using the standard web API method:
var element = document.elementFromPoint(pointInPixels.x, pointInPixels.y);

</syntaxhighlight>

== Destroying a WorldUI ==

[[File:WorldUI-Destroy.png]]

You can destroy a WorldUI by simply destroying its GameObject, or call [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#ad5552c4e2e56cfaf567c9392317988f6 Destroy] on the WorldUI or FlatWorldUI instance.

== WorldUI Origin ==

[[File:WorldUI-Origin.png]]

By default the origin of an ordinary (not flat) WorldUI is right in the middle. You can move it with [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#a15f5d652a8c01b6ecf3e8db7216b2e01 SetOrigin]:

<syntaxhighlight lang="csharp">

// Change its origin:
myWorldUI.SetOrigin(1f, 1f);

</syntaxhighlight>

World UI

2018-04-02T16:05:03Z

Bablakeluke: /* Ordinary World UI */

Sometimes you might want to create something 2D in your 3D world - for example, showing health above a player, a tv screen, integration with NGUI, billboards or something a little more, well, original..

[[File:WorldUI-Intro.png]]

They come in two flavours:

== Ordinary World UI ==

These are true 3D and are typically what you'd use if you want to make use of the [[Text Extrude|text-extrude CSS property]]. If you want to make one in the editor, go to:

''GameObject > UI > PowerUI > In World UI''

You'll then get a previewer which will show you where the UI will appear. Note that the "WorldUI Helper" component is intended to be more of a guideline so it's recommended to take a look at the source.

You can then access the DOM dynamically via a WorldUIHelper like this:

<syntaxhighlight lang="csharp">

// Get that created gameobject via any regular Unity method:
var myWorldUI = GameObject.Find("My WorldUI GameObject");

// Get the doc from it:
var document = myWorldUI.GetComponent<WorldUIHelper>().document;

// use the standard Web API's from here:
document.getElementById("hello-all").innerHTML = "Hello World!";

</syntaxhighlight>

Typically they're instanced dynamically anyway (such as for 3D chat bubbles etc) so for that you'll want to look at the [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html WorldUI scripting class]:

<syntaxhighlight lang="csharp">

// Create a WorldUI:
WorldUI myWorldUI = new WorldUI("optional-name", 200, 30);

// Auto pixel perfect scaling:
myWorldUI.PixelPerfect = true;

// Either write to innerHTML or navigate it:
myWorldUI.document.innerHTML="Hello world (literally!)";

</syntaxhighlight>

== Flat World UI ==

These are your more traditional in world UI's where it's rendered to an image, then the image is displayed in the gameworld however you wish. They are slower than ordinary WorldUI's because of that extra texture step, but they are a lot more flexible in terms of how they can be displayed:

<syntaxhighlight lang="csharp">

// Create a FlatWorldUI (200px x 200px):
FlatWorldUI ui = new FlatWorldUI("optional-name", 200, 200);

// Set the innerHTML however you'd like (e.g. via this helper, or write, or doc.location etc).
ui.document.innerHTML="Hello flat world!";

</syntaxhighlight>

As the surface can be literally any shape, they require slightly specialized input handling. Use [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#a9ffa3ae9d8b52a0fa33f810d54048d3a ResolvePoint] if you'd like to map a ray hit to a point in pixels:

<syntaxhighlight lang="csharp">

// RaycastHit aRayHit;
// FlatWorldUI myUI;

// The point in pixels:
Vector2 pointInPixels = myUI.ResolvePoint(aRayHit);

// E.g. get an element at that point using the standard web API method:
var element = document.elementFromPoint(pointInPixels.x, pointInPixels.y);

</syntaxhighlight>

== Destroying a WorldUI ==

[[File:WorldUI-Destroy.png]]

You can destroy a WorldUI by simply destroying its GameObject, or call [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#ad5552c4e2e56cfaf567c9392317988f6 Destroy] on the WorldUI or FlatWorldUI instance.

== WorldUI Origin ==

[[File:WorldUI-Origin.png]]

By default the origin of an ordinary (not flat) WorldUI is right in the middle. You can move it with [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1WorldUI.html#a15f5d652a8c01b6ecf3e8db7216b2e01 SetOrigin]:

<syntaxhighlight lang="csharp">

// Change its origin:
myWorldUI.SetOrigin(1f, 1f);

</syntaxhighlight>

Event Flow

2018-03-21T18:55:28Z

Bablakeluke: /* Template */

Events occur when something important happens. You can dispatch a custom event or listen to any event using the standard EventTarget interface. PowerUI follows the [https://www.w3.org/TR/uievents/#event-flow standard W3C event flow] which occurs in three phases - ''capture'', ''target'' then ''bubble''.

== Unhandled Events ==

Whenever an event is going to be wasted, such as clicking on nothing, PowerUI dispatches the event to a special handler so you can still respond to it. That handler is [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a573d05035b63bd0f263775209b4109c6 PowerUI.Input.Unhandled].

<syntaxhighlight lang="csharp">

// Adding a listener to the unhandled target:

PowerUI.Input.Unhandled.addEventListener("mousedown",delegate(MouseEvent e){

// They clicked on *nothing!* (straight 'through' the UI).

});

</syntaxhighlight>

Note that due to the way how the event flow and bubbling works, you can get the opposite situation at the root of the DOM:

<syntaxhighlight lang="csharp">

// Adding a listener to the document:

UI.document.addEventListener("mousedown",delegate(MouseEvent e){

// They clicked on *anything!* (and the event bubbled to the document, or the window).

});

</syntaxhighlight>

== Source locations ==

Events occur in multiple different modules of PowerUI so the source is a little spread out. Here's the important parts:

* PowerUI/Source/Dom/Events - ''In here is the very bottom of the event hierarchy; the EventTarget, EventListener and 'Event' .''

* PowerUI/Source/Engine/Events - ''More abstract events - KeyboardEvent, UIEvent, MouseEvent can all be found in here. The bulk of them are in the Events.cs file.''

== Defining custom events ==

If you'd like to define a custom event, you could just create a class which inherits from some other Event type and be done, however, if you want perfect integration then there are 2 things you need to define:

* The Event class itself (define an event and inherit from e.g. Dom.Event)
* The addEventListener method on EventTarget which accepts your delegate and creates a listener for your custom type

=== Naming conventions ===

Events should represent a ''broad category of things'' - for example, a MouseEvent rather than LeftClickEvent / RightClickEvent. A ScoreEvent and a MissionEvent rather than a PointsGainedFromMissionEvent or a MissionStartedEvent and a MissionCompletedEvent. Use type to define what the event actually is:

<syntaxhighlight lang="csharp">

// Mission complete! Fire a complete event:
MissionEvent e=new MissionEvent("complete");

// Dispatch to e.g. the main UI document:
UI.document.dispatchEvent(e);

</syntaxhighlight>

This avoids having hundreds of very specific rare events which would become difficult to maintain. You want to make it easy for yourself to fire off an event because of how useful they are (i.e. you don't want to be put off because you have to define a whole new event type!)

=== Template ===

Here's a convenient template which defines everything you need to declare a new event type which 'just works'. Just find-and-replace {NAME} with the name you'd like to use for your event name, and {LOWERNAME} with the lowercase version.

''For example, find and replace {NAME} with Mission, and {LOWERNAME} with mission''

<syntaxhighlight lang="csharp">

/// <summary>Your event object itself.
/// Add whatever properties you'd like to this.
/// Optionally swap Dom.Event for something more appropriate.</summary>
public class {NAME}Event : Dom.Event{

public class {NAME}Event(string type):base("{LOWERNAME}" + type){}

}

namespace Dom{

public partial class EventTarget{

/// <summary>Add an event listener for a {NAME}Event type of event.</summary>
public void addEventListener(string name,Action<{NAME}Event> method){
addEventListener(name,new EventListener<{NAME}Event>(method));
}

}
}

</syntaxhighlight>

If you want something to look at then the best example is WidgetEvent - it contains everything in a single file for you:

* PowerUI/Source/Extras/Widgets/WidgetEvent.cs

Event Flow

2018-03-21T18:52:41Z

Bablakeluke: /* Unhandled Events */

Events occur when something important happens. You can dispatch a custom event or listen to any event using the standard EventTarget interface. PowerUI follows the [https://www.w3.org/TR/uievents/#event-flow standard W3C event flow] which occurs in three phases - ''capture'', ''target'' then ''bubble''.

== Unhandled Events ==

Whenever an event is going to be wasted, such as clicking on nothing, PowerUI dispatches the event to a special handler so you can still respond to it. That handler is [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a573d05035b63bd0f263775209b4109c6 PowerUI.Input.Unhandled].

<syntaxhighlight lang="csharp">

// Adding a listener to the unhandled target:

PowerUI.Input.Unhandled.addEventListener("mousedown",delegate(MouseEvent e){

// They clicked on *nothing!* (straight 'through' the UI).

});

</syntaxhighlight>

Note that due to the way how the event flow and bubbling works, you can get the opposite situation at the root of the DOM:

<syntaxhighlight lang="csharp">

// Adding a listener to the document:

UI.document.addEventListener("mousedown",delegate(MouseEvent e){

// They clicked on *anything!* (and the event bubbled to the document, or the window).

});

</syntaxhighlight>

== Source locations ==

Events occur in multiple different modules of PowerUI so the source is a little spread out. Here's the important parts:

* PowerUI/Source/Dom/Events - ''In here is the very bottom of the event hierarchy; the EventTarget, EventListener and 'Event' .''

* PowerUI/Source/Engine/Events - ''More abstract events - KeyboardEvent, UIEvent, MouseEvent can all be found in here. The bulk of them are in the Events.cs file.''

== Defining custom events ==

If you'd like to define a custom event, you could just create a class which inherits from some other Event type and be done, however, if you want perfect integration then there are 2 things you need to define:

* The Event class itself (define an event and inherit from e.g. Dom.Event)
* The addEventListener method on EventTarget which accepts your delegate and creates a listener for your custom type

=== Naming conventions ===

Events should represent a ''broad category of things'' - for example, a MouseEvent rather than LeftClickEvent / RightClickEvent. A ScoreEvent and a MissionEvent rather than a PointsGainedFromMissionEvent or a MissionStartedEvent and a MissionCompletedEvent. Use type to define what the event actually is:

<syntaxhighlight lang="csharp">

// Mission complete! Fire a complete event:
MissionEvent e=new MissionEvent("complete");

// Dispatch to e.g. the main UI document:
UI.document.dispatchEvent(e);

</syntaxhighlight>

This avoids having hundreds of very specific rare events which would become difficult to maintain. You want to make it easy for yourself to fire off an event because of how useful they are (i.e. you don't want to be put off because you have to define a whole new event type!)

=== Template ===

Here's a convenient template which defines everything you need to declare a new event type which 'just works'. Just find-and-replace {NAME} with the name you'd like to use for your event name.

''For example, find and replace {NAME} with Mission''

<syntaxhighlight lang="csharp">

/// <summary>Your event object itself.
/// Add whatever properties you'd like to this.
/// Optionally swap Dom.Event for something more appropriate.</summary>
public class {NAME}Event : Dom.Event{

public class {NAME}Event(string type):base(type){}

}

namespace Dom{

public partial class EventTarget{

/// <summary>Add an event listener for a {NAME}Event type of event.</summary>
public void addEventListener(string name,Action<{NAME}Event> method){
addEventListener(name,new EventListener<{NAME}Event>(method));
}

}
}

</syntaxhighlight>

If you want something to look at then the best example is WidgetEvent - it contains everything in a single file for you:

* PowerUI/Source/Extras/Widgets/WidgetEvent.cs

Event Flow

2018-03-21T18:52:34Z

Bablakeluke: /* Unhandled Events */

Events occur when something important happens. You can dispatch a custom event or listen to any event using the standard EventTarget interface. PowerUI follows the [https://www.w3.org/TR/uievents/#event-flow standard W3C event flow] which occurs in three phases - ''capture'', ''target'' then ''bubble''.

== Unhandled Events ==

Whenever an event ia going to be wasted, such as clicking on nothing, PowerUI dispatches the event to a special handler so you can still respond to it. That handler is [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a573d05035b63bd0f263775209b4109c6 PowerUI.Input.Unhandled].

<syntaxhighlight lang="csharp">

// Adding a listener to the unhandled target:

PowerUI.Input.Unhandled.addEventListener("mousedown",delegate(MouseEvent e){

// They clicked on *nothing!* (straight 'through' the UI).

});

</syntaxhighlight>

Note that due to the way how the event flow and bubbling works, you can get the opposite situation at the root of the DOM:

<syntaxhighlight lang="csharp">

// Adding a listener to the document:

UI.document.addEventListener("mousedown",delegate(MouseEvent e){

// They clicked on *anything!* (and the event bubbled to the document, or the window).

});

</syntaxhighlight>

== Source locations ==

Events occur in multiple different modules of PowerUI so the source is a little spread out. Here's the important parts:

* PowerUI/Source/Dom/Events - ''In here is the very bottom of the event hierarchy; the EventTarget, EventListener and 'Event' .''

* PowerUI/Source/Engine/Events - ''More abstract events - KeyboardEvent, UIEvent, MouseEvent can all be found in here. The bulk of them are in the Events.cs file.''

== Defining custom events ==

If you'd like to define a custom event, you could just create a class which inherits from some other Event type and be done, however, if you want perfect integration then there are 2 things you need to define:

* The Event class itself (define an event and inherit from e.g. Dom.Event)
* The addEventListener method on EventTarget which accepts your delegate and creates a listener for your custom type

=== Naming conventions ===

Events should represent a ''broad category of things'' - for example, a MouseEvent rather than LeftClickEvent / RightClickEvent. A ScoreEvent and a MissionEvent rather than a PointsGainedFromMissionEvent or a MissionStartedEvent and a MissionCompletedEvent. Use type to define what the event actually is:

<syntaxhighlight lang="csharp">

// Mission complete! Fire a complete event:
MissionEvent e=new MissionEvent("complete");

// Dispatch to e.g. the main UI document:
UI.document.dispatchEvent(e);

</syntaxhighlight>

This avoids having hundreds of very specific rare events which would become difficult to maintain. You want to make it easy for yourself to fire off an event because of how useful they are (i.e. you don't want to be put off because you have to define a whole new event type!)

=== Template ===

Here's a convenient template which defines everything you need to declare a new event type which 'just works'. Just find-and-replace {NAME} with the name you'd like to use for your event name.

''For example, find and replace {NAME} with Mission''

<syntaxhighlight lang="csharp">

/// <summary>Your event object itself.
/// Add whatever properties you'd like to this.
/// Optionally swap Dom.Event for something more appropriate.</summary>
public class {NAME}Event : Dom.Event{

public class {NAME}Event(string type):base(type){}

}

namespace Dom{

public partial class EventTarget{

/// <summary>Add an event listener for a {NAME}Event type of event.</summary>
public void addEventListener(string name,Action<{NAME}Event> method){
addEventListener(name,new EventListener<{NAME}Event>(method));
}

}
}

</syntaxhighlight>

If you want something to look at then the best example is WidgetEvent - it contains everything in a single file for you:

* PowerUI/Source/Extras/Widgets/WidgetEvent.cs

Performance

2018-03-21T18:51:39Z

Bablakeluke: /* Go event based - avoid spamming your UI in Update */

PowerUI puts performance first. A user interface has very different requirements from a web browser - compare the UI of your favourite games with just how stationary this wiki is, for example. A web browser focuses on making a page show up quickly where as a game will spend time loading to make sure it ''runs'' quickly. PowerUI has been built from scratch to fit the requirements of a high performance UI framework.

In general, we only add support for something when we can get it working without affecting PowerUI's overall speed. It's working too - PowerUI can handle large volumes of HTML with little to no performance issues, whilst now simultaneously having very broad coverage of web technologies.

However, PowerUI is vulnerable to being exposed to some very performance draining web techniques (and there are many of them!) so this is intended to be a short guide to understanding how web engines work and what you can do to avoid some common pitfalls.

== Avoid searching for constant elements in Update ==

This one is a common mistake but can also make great performance savings if you make some small changes. Here's an example of what it looks like:

<syntaxhighlight lang="csharp">

void Update(){

// Don't do this!
var element = UI.document.getElementById("my-nav-menu");

}

</syntaxhighlight>

PowerUI will try and index your IDs, but in general, this will result in scanning your whole DOM every single frame. You should just cache the element instead:

<syntaxhighlight lang="csharp">

Element MyNavMenu;

void Start(){
// Much better!
MyNavMenu = UI.document.getElementById("my-nav-menu");
}

void Update(){
// Use MyNavMenu in here
}

</syntaxhighlight>

== Go event based - avoid spamming your UI in Update ==

Although it's ok to update your UI in the Update loop, for example for a timer, try being more event based for the greatest performance. For example, let's say you pop up some info when the user clicks on an NPC. Rather than spamming some 'SelectedNpc' field, update the UI when they're actually clicked on:

'''A common Unity anti-pattern - don't do this!''':

<syntaxhighlight lang="csharp">

void Update() {
// Bad!
var headsUp = UI.document.getElementById("npc-heads-up-info");

if (SelectedNpc != null) {
// Spamspamspamspamspam
headsUp.innerHTML = SelectedNpc.HtmlDetails;
} else {
headsUp.innerHTML = "";
}
}

</syntaxhighlight>

Instead, set that innerHTML when you set SelectedNpc:

<syntaxhighlight lang="csharp">

void SelectedAnNpc(Npc npc) {
// Much better!
SelectedNpc = npc;

// Update the UI:
var headsUp = UI.document.getElementById("npc-heads-up-info");

if (SelectedNpc != null) {
headsUp.innerHTML = SelectedNpc.HtmlDetails;
} else {
headsUp.innerHTML = "";
}
}

</syntaxhighlight>

PowerUI ships with a very powerful and extendible [[Event Flow|standards compliant event system]] - use this to your advantage. Selecting an NPC could fire off an NPC selection event, which some other class controlling your UI responds to:

<syntaxhighlight lang="csharp">

void SelectedAnNpc(Npc npc) {
// Much better!
SelectedNpc = npc;

// Fire off an event which anything can subscribe to with a standard event listener on the document:
NpcEvent e = new NpcEvent("selected");
e.npc = npc;
UI.document.dispatchEvent(e);
}

// .. somewhere else ..

UI.document.addEventListener("npcselected", delegate(NpcEvent e){
// Update the UI here, using e.npc instead.
});

</syntaxhighlight>

== Reflow ==

Reflow is the name given when a web engine resolves CSS values and figures out where everything is on the screen. PowerUI also performs reflow, so following standard good practice for reducing reflow in a web browser applies to PowerUI too, so [https://developers.google.com/speed/articles/reflow here's a guide that will help with just that]. You may have cases where your UI generates lots of reflows very fast - PowerUI internally meters this using UI.SetRate; it won't reflow any more often than the rate you give.

* '''Power tip #1: Use UI.SetRate and get it as low as you reasonably can. The default is 30fps with super smooth at 60fps.'''

Following similar lines, pulling properties such as contentHeight from an element will force a reflow to happen if the element is known to require one. Accessing the computed style (element.style.Computed.ContentHeight for example) does not force reflows, so if you know e.g. the height didn't change then using computed styles directly can be a little quicker, but this only really applies if you're doing a style change and then grabbing the contentHeight rapidly in a loop.

* '''Power tip #2: Read from ComputedStyle where possible.'''

== Skipping Reflow ==

It's possible to pull off a complex UI which only performs reflow a handful of times by focusing on post-process CSS properties. These are CSS properties which don't affect the flow or structure of an element - the main examples are color, color-overlay, transform and the special case that is scroll. Generally try to animate these ones when you can!

* '''Power tip #3: Animate transforms (scale, rotate, translate) rather than positions (top, left, right etc) if possible.'''

=== Limiting reflow scope ===

Reflow applies to the nearest ''flow root'' element. For example, let's say you update the innerHTML of a fixed/absolute/sticky '''positioned element''' then ''only that element will actually reflow''. The same applies to any of the nested kids of that positioned element - it'll bubble up the DOM to the nearest flow root, and request to reflow that element. In short, making an element become a ''flow root'' is an easy way to massively limit how many elements reflow actually affects.

== Table Chaos ==

'''PowerUI doesn't support tables with no defined widths.''' Tables cause multiple passes over potentially thousands of elements. The modern reason for using a table today is for vertical alignment - most other layouts can be easily done with other far less intense techniques. If it's vertical align that you're really after then use the custom vertical-align values on any element:

<syntaxhighlight lang="css">

/* Middle vertical alignment without the overhead of table-cell/ tables */
vertical-align:table-middle;

</syntaxhighlight>

On a similar line, tables with no defined column widths are outright evil. The number of elements scanned to guess how wide a column probably should be can go exponential very quickly and, after all of that, it often doesn't look great anyway. As we're making UIs which reflow very frequently, PowerUI requires you to give all your table columns and the table itself some kind of width value. This way PowerUI has unusually fast tables - making them suitable for heavy reflow - but they're still slow compared to almost anything else.

* '''Power tip #4: Use techniques other than table whenever appropriate, and make use of table-middle.'''

== Memory Usage ==

PowerUI is conservative about its memory usage, but if you're targeting really low memory devices, turning off [[Image_Atlasing|image atlasing]] may be wise. Turning it off exchanges GPU/rendering time for lower memory and CPU use, which can be vital for pulling off a stunning UI on a device with little memory available.

* '''Power tip #5: Turn off image atlasing for very low memory devices. See UI.RenderMode for doing that.'''

== Multithreading ==

Virtually all of PowerUI is multithreading friendly - anything that directly calls a Unity method like the geolocation web API isn't. Presently the cookie cache (loading or setting cookies) is the only known PowerUI API which avoidably causes threading issues. Use PowerUI API's directly from network threads, or spin up threads specifically for doing heavier UI work to make significant performance gains on multi-core architectures.

== Canvas ==

If you're drawing to a canvas, there's some nice savings you can be making. These savings are particularly noticeable if you're drawing repeatedly, such as in Update.

=== Only redraw your canvas when PowerUI does ===
PowerUI uploads the canvas image to the GPU no faster than your UI rate. Drawing your canvas any faster than that interval will essentially just waste cycles. We call that upload process a 'refresh' - whenever you call stroke() or fill(), a refresh request is made (and then at some point in the near future, a refresh happens).

So, if PowerUI already has an image which is ready but hasn't been uploaded yet, there will be a pending refresh. Checking for that is like this:

<syntaxhighlight lang="csharp">

private CanvasContext2D Context;

void Update(){

if(Context.ImageData.RefreshRequired){
// This means we've already rendered something to the image data
// and it's just waiting to be uploaded. Rendering again would be a waste of time.
// So, do nothing!
return;
}

// Nothing to upload - draw it now!
Context.beginPath();
Context.moveTo(10,10);
// ...

}

</syntaxhighlight>

=== Multithreading canvas ===

Like most PowerUI API's, canvas is multithreading friendly. You could build those paths on some separate timer thread if you wanted to, for example.

=== Cache your paths ===

Whenever you call context.arcTo, context.lineTo etc, PowerUI internally builds up a representation of your path. When you then next call context.beginPath or context.clear, that representation is destroyed. If you're drawing the same path over and over, it would be a great idea to save this internal representation rather than constantly rebuilding it to take some pressure off garbage collection.

'''If you do this, it's up to you to safely bound your points.''' Normally the canvas API automatically takes care of points that are excessively out of range for you - things like infinity, NaN, or generally huge numbers. If you build a VectorPath and set it to a canvas, it's important that you also guarantee your path doesn't have any of those things. Internally, the canvas API runs VectorPath.Clip on all paths constructed via lineTo, arcTo etc. Otherwise, if you have an extremely long path then the canvas API will freeze whilst it outputs billions of pixels.

To cache your paths you could either simply never call context.clear or context.beginPath and access Context.Path to move the nodes around like this:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI.

/// <summary>The canvas context.</summary>
private CanvasContext Context;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

}

void Update(){

// To clear the image but not the path, use ImageData:
Context.ImageData.Clear();

// The path is totally empty if there's no first node:
if(Context.Path.FirstPathNode == null){

// No path yet! Build it now:
Context.moveTo(10,10);
Context.lineTo(10,100);
Context.lineTo(100,100);
Context.lineTo(100,10);
Context.closePath();

// Note if any of the points in this first time call
// go far out of range of the canvas, they may be
// sliced for performance purposes.
// For example, if your entire path is off canvas,
// the whole thing may be dumped when you call stroke().

// One way to avoid that uncertainty is to build the VectorPath directly (like below)
// and then call VectorPath.Clip when it's appropriate for your use case.

}else{

// E.g. update the nodes in the cachedPath:
var point = CachedPath.FirstPathNode;

// Our path has 5 points (alternatively loop until point is null).
for(int i=0;i<5;i++){ // while(point!=null){

// Move the point by the frame time:
point.X += Time.deltaTime;

// Go to the next point:
point = point.Next;

}

}

// Stroke or fill etc down here:
Context.stroke();

}

</syntaxhighlight>

If you're drawing multiple paths and you want to cache them all, then the simpler route would be to directly build one or more VectorPath instances first:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI
using Blaze; // For VectorPath

/// <summary>The canvas context.</summary>
private CanvasContext Context;
/// <summary>A single cached path.</summary>
private VectorPath CachedPath;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

// build the vector path(s):
CachedPath = new VectorPath();

// The API is very similar - it's capitalized as it's part of the internal public API:
CachedPath.MoveTo(10,10);
CachedPath.LineTo(10,100);
CachedPath.LineTo(100,100);
CachedPath.LineTo(100,10);
CachedPath.ClosePath();

}

void Update(){

// Calling normal clear doesn't matter here (as we're not using e.g. Context.lineTo)
Context.clear();

// E.g. update current path here:
var point = CachedPath.FirstPathNode;

// note that closed paths never make infinite loops here.
// A close node simply overlaps the node it closes and has IsClose set to true.
while(point!=null){
point.X+=Time.deltaTime;
point=point.Next;
}

// Temporarily retain the path object in the canvas:
VectorPath activePath = Canvas.Path;

// Set ours:
Canvas.Path = CachedPath;

// Stroke it now:
Canvas.stroke();

// Restore the other path:
Canvas.Path = activePath;

}

</syntaxhighlight>

== Precompile PowerUI ==

Performance applies to your development process too. Unless you've got a solid state hard drive, PowerUI can take some 15 seconds to compile. Every time you change any of your C# files. [[Precompiler|Precompile PowerUI]] by going to '''Window > PowerUI > Precompile''' then just tick the box - that will entirely eliminate this delay for you.

'''If you change platform, or update Unity, you must precompile it again!''' That's because things like UNITY_ANDROID matter a lot.

Note that precompiling does not affect custom tags etc, but it does affect any ''partial class extensions''.

== Set textContent rather than innerHTML ==

If you know your text contains no HTML then setting to textContent will cause virtually everything to get recycled. Setting innerHTML is fast anyway but textContent does almost nothing.

You can also get another small boost if the new text you're setting is the same length as the old text - this takes advantage of a health counter optimisation:

<syntaxhighlight lang="csharp">

myElement.textContent = "1";
myElement.textContent = "14"; // 1 character longer

// Using 01 would make a (tiny) saving:
myElement.textContent = "01";
myElement.textContent = "14";

</syntaxhighlight>

== Disabling Unicode Bidirectionality ==

If you have no plans to use right-to-left or bidirectional text (like Arabic mixed with English), disable it by deleting '''PowerUI/Resources/BidirectionalData.bytes'''. This will give you a small memory saving (about 10kb) and slightly boost text performance.

You can also go further by specifying '''NoBIDI''' as a "scripting define symbols" as that will effectively remove all of the code which does the BIDI testing.

== Avoid late loading CSS ==

This is a massive performance drainer - avoid it! Put style as high up your document as you can (e.g. in head). That's because a newly loaded CSS selector must ''check your entire DOM'' to see if they match any of the elements already in there. If your DOM is basically empty then this operation is much faster.

Meanwhile, a newly loading element uses a range of indices to very rapidly figure out which selectors actually apply to it.

Performance

2018-03-21T18:49:56Z

Bablakeluke:

PowerUI puts performance first. A user interface has very different requirements from a web browser - compare the UI of your favourite games with just how stationary this wiki is, for example. A web browser focuses on making a page show up quickly where as a game will spend time loading to make sure it ''runs'' quickly. PowerUI has been built from scratch to fit the requirements of a high performance UI framework.

In general, we only add support for something when we can get it working without affecting PowerUI's overall speed. It's working too - PowerUI can handle large volumes of HTML with little to no performance issues, whilst now simultaneously having very broad coverage of web technologies.

However, PowerUI is vulnerable to being exposed to some very performance draining web techniques (and there are many of them!) so this is intended to be a short guide to understanding how web engines work and what you can do to avoid some common pitfalls.

== Avoid searching for constant elements in Update ==

This one is a common mistake but can also make great performance savings if you make some small changes. Here's an example of what it looks like:

<syntaxhighlight lang="csharp">

void Update(){

// Don't do this!
var element = UI.document.getElementById("my-nav-menu");

}

</syntaxhighlight>

PowerUI will try and index your IDs, but in general, this will result in scanning your whole DOM every single frame. You should just cache the element instead:

<syntaxhighlight lang="csharp">

Element MyNavMenu;

void Start(){
// Much better!
MyNavMenu = UI.document.getElementById("my-nav-menu");
}

void Update(){
// Use MyNavMenu in here
}

</syntaxhighlight>

== Go event based - avoid spamming your UI in Update ==

Although it's ok to update your UI in the Update loop, for example for a timer, try being more event based for the greatest performance. For example, let's say you pop up some info when the user clicks on an NPC. Rather than spamming some 'SelectedNpc' field, update the UI when they're actually clicked on:

'''A common Unity anti-pattern - don't do this!''':

<syntaxhighlight lang="csharp">

void Update() {
// Bad!
var headsUp = UI.document.getElementById("npc-heads-up-info");

if (SelectedNpc != null) {
// Spamspamspamspamspam
headsUp.innerHTML = SelectedNpc.HtmlDetails;
} else {
headsUp.innerHTML = "";
}
}

</syntaxhighlight>

Instead, set that innerHTML when you set SelectedNpc:

<syntaxhighlight lang="csharp">

void SelectedAnNpc(Npc npc) {
// Much better!
SelectedNpc = npc;

// Update the UI:
var headsUp = UI.document.getElementById("npc-heads-up-info");

if (SelectedNpc != null) {
headsUp.innerHTML = SelectedNpc.HtmlDetails;
} else {
headsUp.innerHTML = "";
}
}

</syntaxhighlight>

PowerUI ships with a very powerful and extendible [Event Flow|standards compliant event system] - use this to your advantage. Selecting an NPC could fire off an NPC selection event, which some other class controlling your UI responds to:

<syntaxhighlight lang="csharp">

void SelectedAnNpc(Npc npc) {
// Much better!
SelectedNpc = npc;

// Fire off an event which anything can subscribe to with a standard event listener on the document:
NpcEvent e = new NpcEvent("selected");
e.npc = npc;
UI.document.dispatchEvent(e);
}

// .. somewhere else ..

UI.document.addEventListener("npcselected", delegate(NpcEvent e){
// Update the UI here, using e.npc instead.
});

</syntaxhighlight>

== Reflow ==

Reflow is the name given when a web engine resolves CSS values and figures out where everything is on the screen. PowerUI also performs reflow, so following standard good practice for reducing reflow in a web browser applies to PowerUI too, so [https://developers.google.com/speed/articles/reflow here's a guide that will help with just that]. You may have cases where your UI generates lots of reflows very fast - PowerUI internally meters this using UI.SetRate; it won't reflow any more often than the rate you give.

* '''Power tip #1: Use UI.SetRate and get it as low as you reasonably can. The default is 30fps with super smooth at 60fps.'''

Following similar lines, pulling properties such as contentHeight from an element will force a reflow to happen if the element is known to require one. Accessing the computed style (element.style.Computed.ContentHeight for example) does not force reflows, so if you know e.g. the height didn't change then using computed styles directly can be a little quicker, but this only really applies if you're doing a style change and then grabbing the contentHeight rapidly in a loop.

* '''Power tip #2: Read from ComputedStyle where possible.'''

== Skipping Reflow ==

It's possible to pull off a complex UI which only performs reflow a handful of times by focusing on post-process CSS properties. These are CSS properties which don't affect the flow or structure of an element - the main examples are color, color-overlay, transform and the special case that is scroll. Generally try to animate these ones when you can!

* '''Power tip #3: Animate transforms (scale, rotate, translate) rather than positions (top, left, right etc) if possible.'''

=== Limiting reflow scope ===

Reflow applies to the nearest ''flow root'' element. For example, let's say you update the innerHTML of a fixed/absolute/sticky '''positioned element''' then ''only that element will actually reflow''. The same applies to any of the nested kids of that positioned element - it'll bubble up the DOM to the nearest flow root, and request to reflow that element. In short, making an element become a ''flow root'' is an easy way to massively limit how many elements reflow actually affects.

== Table Chaos ==

'''PowerUI doesn't support tables with no defined widths.''' Tables cause multiple passes over potentially thousands of elements. The modern reason for using a table today is for vertical alignment - most other layouts can be easily done with other far less intense techniques. If it's vertical align that you're really after then use the custom vertical-align values on any element:

<syntaxhighlight lang="css">

/* Middle vertical alignment without the overhead of table-cell/ tables */
vertical-align:table-middle;

</syntaxhighlight>

On a similar line, tables with no defined column widths are outright evil. The number of elements scanned to guess how wide a column probably should be can go exponential very quickly and, after all of that, it often doesn't look great anyway. As we're making UIs which reflow very frequently, PowerUI requires you to give all your table columns and the table itself some kind of width value. This way PowerUI has unusually fast tables - making them suitable for heavy reflow - but they're still slow compared to almost anything else.

* '''Power tip #4: Use techniques other than table whenever appropriate, and make use of table-middle.'''

== Memory Usage ==

PowerUI is conservative about its memory usage, but if you're targeting really low memory devices, turning off [[Image_Atlasing|image atlasing]] may be wise. Turning it off exchanges GPU/rendering time for lower memory and CPU use, which can be vital for pulling off a stunning UI on a device with little memory available.

* '''Power tip #5: Turn off image atlasing for very low memory devices. See UI.RenderMode for doing that.'''

== Multithreading ==

Virtually all of PowerUI is multithreading friendly - anything that directly calls a Unity method like the geolocation web API isn't. Presently the cookie cache (loading or setting cookies) is the only known PowerUI API which avoidably causes threading issues. Use PowerUI API's directly from network threads, or spin up threads specifically for doing heavier UI work to make significant performance gains on multi-core architectures.

== Canvas ==

If you're drawing to a canvas, there's some nice savings you can be making. These savings are particularly noticeable if you're drawing repeatedly, such as in Update.

=== Only redraw your canvas when PowerUI does ===
PowerUI uploads the canvas image to the GPU no faster than your UI rate. Drawing your canvas any faster than that interval will essentially just waste cycles. We call that upload process a 'refresh' - whenever you call stroke() or fill(), a refresh request is made (and then at some point in the near future, a refresh happens).

So, if PowerUI already has an image which is ready but hasn't been uploaded yet, there will be a pending refresh. Checking for that is like this:

<syntaxhighlight lang="csharp">

private CanvasContext2D Context;

void Update(){

if(Context.ImageData.RefreshRequired){
// This means we've already rendered something to the image data
// and it's just waiting to be uploaded. Rendering again would be a waste of time.
// So, do nothing!
return;
}

// Nothing to upload - draw it now!
Context.beginPath();
Context.moveTo(10,10);
// ...

}

</syntaxhighlight>

=== Multithreading canvas ===

Like most PowerUI API's, canvas is multithreading friendly. You could build those paths on some separate timer thread if you wanted to, for example.

=== Cache your paths ===

Whenever you call context.arcTo, context.lineTo etc, PowerUI internally builds up a representation of your path. When you then next call context.beginPath or context.clear, that representation is destroyed. If you're drawing the same path over and over, it would be a great idea to save this internal representation rather than constantly rebuilding it to take some pressure off garbage collection.

'''If you do this, it's up to you to safely bound your points.''' Normally the canvas API automatically takes care of points that are excessively out of range for you - things like infinity, NaN, or generally huge numbers. If you build a VectorPath and set it to a canvas, it's important that you also guarantee your path doesn't have any of those things. Internally, the canvas API runs VectorPath.Clip on all paths constructed via lineTo, arcTo etc. Otherwise, if you have an extremely long path then the canvas API will freeze whilst it outputs billions of pixels.

To cache your paths you could either simply never call context.clear or context.beginPath and access Context.Path to move the nodes around like this:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI.

/// <summary>The canvas context.</summary>
private CanvasContext Context;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

}

void Update(){

// To clear the image but not the path, use ImageData:
Context.ImageData.Clear();

// The path is totally empty if there's no first node:
if(Context.Path.FirstPathNode == null){

// No path yet! Build it now:
Context.moveTo(10,10);
Context.lineTo(10,100);
Context.lineTo(100,100);
Context.lineTo(100,10);
Context.closePath();

// Note if any of the points in this first time call
// go far out of range of the canvas, they may be
// sliced for performance purposes.
// For example, if your entire path is off canvas,
// the whole thing may be dumped when you call stroke().

// One way to avoid that uncertainty is to build the VectorPath directly (like below)
// and then call VectorPath.Clip when it's appropriate for your use case.

}else{

// E.g. update the nodes in the cachedPath:
var point = CachedPath.FirstPathNode;

// Our path has 5 points (alternatively loop until point is null).
for(int i=0;i<5;i++){ // while(point!=null){

// Move the point by the frame time:
point.X += Time.deltaTime;

// Go to the next point:
point = point.Next;

}

}

// Stroke or fill etc down here:
Context.stroke();

}

</syntaxhighlight>

If you're drawing multiple paths and you want to cache them all, then the simpler route would be to directly build one or more VectorPath instances first:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI
using Blaze; // For VectorPath

/// <summary>The canvas context.</summary>
private CanvasContext Context;
/// <summary>A single cached path.</summary>
private VectorPath CachedPath;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

// build the vector path(s):
CachedPath = new VectorPath();

// The API is very similar - it's capitalized as it's part of the internal public API:
CachedPath.MoveTo(10,10);
CachedPath.LineTo(10,100);
CachedPath.LineTo(100,100);
CachedPath.LineTo(100,10);
CachedPath.ClosePath();

}

void Update(){

// Calling normal clear doesn't matter here (as we're not using e.g. Context.lineTo)
Context.clear();

// E.g. update current path here:
var point = CachedPath.FirstPathNode;

// note that closed paths never make infinite loops here.
// A close node simply overlaps the node it closes and has IsClose set to true.
while(point!=null){
point.X+=Time.deltaTime;
point=point.Next;
}

// Temporarily retain the path object in the canvas:
VectorPath activePath = Canvas.Path;

// Set ours:
Canvas.Path = CachedPath;

// Stroke it now:
Canvas.stroke();

// Restore the other path:
Canvas.Path = activePath;

}

</syntaxhighlight>

== Precompile PowerUI ==

Performance applies to your development process too. Unless you've got a solid state hard drive, PowerUI can take some 15 seconds to compile. Every time you change any of your C# files. [[Precompiler|Precompile PowerUI]] by going to '''Window > PowerUI > Precompile''' then just tick the box - that will entirely eliminate this delay for you.

'''If you change platform, or update Unity, you must precompile it again!''' That's because things like UNITY_ANDROID matter a lot.

Note that precompiling does not affect custom tags etc, but it does affect any ''partial class extensions''.

== Set textContent rather than innerHTML ==

If you know your text contains no HTML then setting to textContent will cause virtually everything to get recycled. Setting innerHTML is fast anyway but textContent does almost nothing.

You can also get another small boost if the new text you're setting is the same length as the old text - this takes advantage of a health counter optimisation:

<syntaxhighlight lang="csharp">

myElement.textContent = "1";
myElement.textContent = "14"; // 1 character longer

// Using 01 would make a (tiny) saving:
myElement.textContent = "01";
myElement.textContent = "14";

</syntaxhighlight>

== Disabling Unicode Bidirectionality ==

If you have no plans to use right-to-left or bidirectional text (like Arabic mixed with English), disable it by deleting '''PowerUI/Resources/BidirectionalData.bytes'''. This will give you a small memory saving (about 10kb) and slightly boost text performance.

You can also go further by specifying '''NoBIDI''' as a "scripting define symbols" as that will effectively remove all of the code which does the BIDI testing.

== Avoid late loading CSS ==

This is a massive performance drainer - avoid it! Put style as high up your document as you can (e.g. in head). That's because a newly loaded CSS selector must ''check your entire DOM'' to see if they match any of the elements already in there. If your DOM is basically empty then this operation is much faster.

Meanwhile, a newly loading element uses a range of indices to very rapidly figure out which selectors actually apply to it.

Performance

2018-03-13T23:34:59Z

Bablakeluke: /* Table Chaos */

PowerUI puts performance first. A user interface has very different requirements from a web browser - compare the UI of your favourite games with just how stationary this wiki is, for example. A web browser focuses on making a page show up quickly where as a game will spend time loading to make sure it ''runs'' quickly. PowerUI has been built from scratch to fit the requirements of a high performance UI framework.

In general, we only add support for something when we can get it working without affecting PowerUI's overall speed. It's working too - PowerUI can handle large volumes of HTML with little to no performance issues, whilst now simultaneously having very broad coverage of web technologies.

However, PowerUI is vulnerable to being exposed to some very performance draining web techniques (and there are many of them!) so this is intended to be a short guide to understanding how web engines work and what you can do to avoid some common pitfalls.

== Avoid searching for constant elements in Update ==

This one is a common mistake but can also make great performance savings if you make some small changes. Here's an example of what it looks like:

<syntaxhighlight lang="csharp">

void Update(){

// Don't do this!
var element = UI.document.getElementById("my-nav-menu");

}

</syntaxhighlight>

PowerUI will try and index your IDs, but in general, this will result in scanning your whole DOM every single frame. You should just cache the element instead:

<syntaxhighlight lang="csharp">

Element MyNavMenu;

void Start(){
// Much better!
MyNavMenu = UI.document.getElementById("my-nav-menu");
}

void Update(){
// Use MyNavMenu in here
}

</syntaxhighlight>

== Reflow ==

Reflow is the name given when a web engine resolves CSS values and figures out where everything is on the screen. PowerUI also performs reflow, so following standard good practice for reducing reflow in a web browser applies to PowerUI too, so [https://developers.google.com/speed/articles/reflow here's a guide that will help with just that]. You may have cases where your UI generates lots of reflows very fast - PowerUI internally meters this using UI.SetRate; it won't reflow any more often than the rate you give.

* '''Power tip #1: Use UI.SetRate and get it as low as you reasonably can. The default is 30fps with super smooth at 60fps.'''

Following similar lines, pulling properties such as contentHeight from an element will force a reflow to happen if the element is known to require one. Accessing the computed style (element.style.Computed.ContentHeight for example) does not force reflows, so if you know e.g. the height didn't change then using computed styles directly can be a little quicker, but this only really applies if you're doing a style change and then grabbing the contentHeight rapidly in a loop.

* '''Power tip #2: Read from ComputedStyle where possible.'''

== Skipping Reflow ==

It's possible to pull off a complex UI which only performs reflow a handful of times by focusing on post-process CSS properties. These are CSS properties which don't affect the flow or structure of an element - the main examples are color, color-overlay, transform and the special case that is scroll. Generally try to animate these ones when you can!

* '''Power tip #3: Animate transforms (scale, rotate, translate) rather than positions (top, left, right etc) if possible.'''

=== Limiting reflow scope ===

Reflow applies to the nearest ''flow root'' element. For example, let's say you update the innerHTML of a fixed/absolute/sticky '''positioned element''' then ''only that element will actually reflow''. The same applies to any of the nested kids of that positioned element - it'll bubble up the DOM to the nearest flow root, and request to reflow that element. In short, making an element become a ''flow root'' is an easy way to massively limit how many elements reflow actually affects.

== Table Chaos ==

'''PowerUI doesn't support tables with no defined widths.''' Tables cause multiple passes over potentially thousands of elements. The modern reason for using a table today is for vertical alignment - most other layouts can be easily done with other far less intense techniques. If it's vertical align that you're really after then use the custom vertical-align values on any element:

<syntaxhighlight lang="css">

/* Middle vertical alignment without the overhead of table-cell/ tables */
vertical-align:table-middle;

</syntaxhighlight>

On a similar line, tables with no defined column widths are outright evil. The number of elements scanned to guess how wide a column probably should be can go exponential very quickly and, after all of that, it often doesn't look great anyway. As we're making UIs which reflow very frequently, PowerUI requires you to give all your table columns and the table itself some kind of width value. This way PowerUI has unusually fast tables - making them suitable for heavy reflow - but they're still slow compared to almost anything else.

* '''Power tip #4: Use techniques other than table whenever appropriate, and make use of table-middle.'''

== Memory Usage ==

PowerUI is conservative about its memory usage, but if you're targeting really low memory devices, turning off [[Image_Atlasing|image atlasing]] may be wise. Turning it off exchanges GPU/rendering time for lower memory and CPU use, which can be vital for pulling off a stunning UI on a device with little memory available.

* '''Power tip #5: Turn off image atlasing for very low memory devices. See UI.RenderMode for doing that.'''

== Multithreading ==

Virtually all of PowerUI is multithreading friendly - anything that directly calls a Unity method like the geolocation web API isn't. Presently the cookie cache (loading or setting cookies) is the only known PowerUI API which avoidably causes threading issues. Use PowerUI API's directly from network threads, or spin up threads specifically for doing heavier UI work to make significant performance gains on multi-core architectures.

== Canvas ==

If you're drawing to a canvas, there's some nice savings you can be making. These savings are particularly noticeable if you're drawing repeatedly, such as in Update.

=== Only redraw your canvas when PowerUI does ===
PowerUI uploads the canvas image to the GPU no faster than your UI rate. Drawing your canvas any faster than that interval will essentially just waste cycles. We call that upload process a 'refresh' - whenever you call stroke() or fill(), a refresh request is made (and then at some point in the near future, a refresh happens).

So, if PowerUI already has an image which is ready but hasn't been uploaded yet, there will be a pending refresh. Checking for that is like this:

<syntaxhighlight lang="csharp">

private CanvasContext2D Context;

void Update(){

if(Context.ImageData.RefreshRequired){
// This means we've already rendered something to the image data
// and it's just waiting to be uploaded. Rendering again would be a waste of time.
// So, do nothing!
return;
}

// Nothing to upload - draw it now!
Context.beginPath();
Context.moveTo(10,10);
// ...

}

</syntaxhighlight>

=== Multithreading canvas ===

Like most PowerUI API's, canvas is multithreading friendly. You could build those paths on some separate timer thread if you wanted to, for example.

=== Cache your paths ===

Whenever you call context.arcTo, context.lineTo etc, PowerUI internally builds up a representation of your path. When you then next call context.beginPath or context.clear, that representation is destroyed. If you're drawing the same path over and over, it would be a great idea to save this internal representation rather than constantly rebuilding it to take some pressure off garbage collection.

'''If you do this, it's up to you to safely bound your points.''' Normally the canvas API automatically takes care of points that are excessively out of range for you - things like infinity, NaN, or generally huge numbers. If you build a VectorPath and set it to a canvas, it's important that you also guarantee your path doesn't have any of those things. Internally, the canvas API runs VectorPath.Clip on all paths constructed via lineTo, arcTo etc. Otherwise, if you have an extremely long path then the canvas API will freeze whilst it outputs billions of pixels.

To cache your paths you could either simply never call context.clear or context.beginPath and access Context.Path to move the nodes around like this:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI.

/// <summary>The canvas context.</summary>
private CanvasContext Context;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

}

void Update(){

// To clear the image but not the path, use ImageData:
Context.ImageData.Clear();

// The path is totally empty if there's no first node:
if(Context.Path.FirstPathNode == null){

// No path yet! Build it now:
Context.moveTo(10,10);
Context.lineTo(10,100);
Context.lineTo(100,100);
Context.lineTo(100,10);
Context.closePath();

// Note if any of the points in this first time call
// go far out of range of the canvas, they may be
// sliced for performance purposes.
// For example, if your entire path is off canvas,
// the whole thing may be dumped when you call stroke().

// One way to avoid that uncertainty is to build the VectorPath directly (like below)
// and then call VectorPath.Clip when it's appropriate for your use case.

}else{

// E.g. update the nodes in the cachedPath:
var point = CachedPath.FirstPathNode;

// Our path has 5 points (alternatively loop until point is null).
for(int i=0;i<5;i++){ // while(point!=null){

// Move the point by the frame time:
point.X += Time.deltaTime;

// Go to the next point:
point = point.Next;

}

}

// Stroke or fill etc down here:
Context.stroke();

}

</syntaxhighlight>

If you're drawing multiple paths and you want to cache them all, then the simpler route would be to directly build one or more VectorPath instances first:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI
using Blaze; // For VectorPath

/// <summary>The canvas context.</summary>
private CanvasContext Context;
/// <summary>A single cached path.</summary>
private VectorPath CachedPath;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

// build the vector path(s):
CachedPath = new VectorPath();

// The API is very similar - it's capitalized as it's part of the internal public API:
CachedPath.MoveTo(10,10);
CachedPath.LineTo(10,100);
CachedPath.LineTo(100,100);
CachedPath.LineTo(100,10);
CachedPath.ClosePath();

}

void Update(){

// Calling normal clear doesn't matter here (as we're not using e.g. Context.lineTo)
Context.clear();

// E.g. update current path here:
var point = CachedPath.FirstPathNode;

// note that closed paths never make infinite loops here.
// A close node simply overlaps the node it closes and has IsClose set to true.
while(point!=null){
point.X+=Time.deltaTime;
point=point.Next;
}

// Temporarily retain the path object in the canvas:
VectorPath activePath = Canvas.Path;

// Set ours:
Canvas.Path = CachedPath;

// Stroke it now:
Canvas.stroke();

// Restore the other path:
Canvas.Path = activePath;

}

</syntaxhighlight>

== Precompile PowerUI ==

Performance applies to your development process too. Unless you've got a solid state hard drive, PowerUI can take some 15 seconds to compile. Every time you change any of your C# files. [[Precompiler|Precompile PowerUI]] by going to '''Window > PowerUI > Precompile''' then just tick the box - that will entirely eliminate this delay for you.

'''If you change platform, or update Unity, you must precompile it again!''' That's because things like UNITY_ANDROID matter a lot.

Note that precompiling does not affect custom tags etc, but it does affect any ''partial class extensions''.

== Set textContent rather than innerHTML ==

If you know your text contains no HTML then setting to textContent will cause virtually everything to get recycled. Setting innerHTML is fast anyway but textContent does almost nothing.

You can also get another small boost if the new text you're setting is the same length as the old text - this takes advantage of a health counter optimisation:

<syntaxhighlight lang="csharp">

myElement.textContent = "1";
myElement.textContent = "14"; // 1 character longer

// Using 01 would make a (tiny) saving:
myElement.textContent = "01";
myElement.textContent = "14";

</syntaxhighlight>

== Disabling Unicode Bidirectionality ==

If you have no plans to use right-to-left or bidirectional text (like Arabic mixed with English), disable it by deleting '''PowerUI/Resources/BidirectionalData.bytes'''. This will give you a small memory saving (about 10kb) and slightly boost text performance.

You can also go further by specifying '''NoBIDI''' as a "scripting define symbols" as that will effectively remove all of the code which does the BIDI testing.

== Avoid late loading CSS ==

This is a massive performance drainer - avoid it! Put style as high up your document as you can (e.g. in head). That's because a newly loaded CSS selector must ''check your entire DOM'' to see if they match any of the elements already in there. If your DOM is basically empty then this operation is much faster.

Meanwhile, a newly loading element uses a range of indices to very rapidly figure out which selectors actually apply to it.

Performance

2018-03-13T23:32:21Z

Bablakeluke: /* Table Chaos */

PowerUI puts performance first. A user interface has very different requirements from a web browser - compare the UI of your favourite games with just how stationary this wiki is, for example. A web browser focuses on making a page show up quickly where as a game will spend time loading to make sure it ''runs'' quickly. PowerUI has been built from scratch to fit the requirements of a high performance UI framework.

In general, we only add support for something when we can get it working without affecting PowerUI's overall speed. It's working too - PowerUI can handle large volumes of HTML with little to no performance issues, whilst now simultaneously having very broad coverage of web technologies.

However, PowerUI is vulnerable to being exposed to some very performance draining web techniques (and there are many of them!) so this is intended to be a short guide to understanding how web engines work and what you can do to avoid some common pitfalls.

== Avoid searching for constant elements in Update ==

This one is a common mistake but can also make great performance savings if you make some small changes. Here's an example of what it looks like:

<syntaxhighlight lang="csharp">

void Update(){

// Don't do this!
var element = UI.document.getElementById("my-nav-menu");

}

</syntaxhighlight>

PowerUI will try and index your IDs, but in general, this will result in scanning your whole DOM every single frame. You should just cache the element instead:

<syntaxhighlight lang="csharp">

Element MyNavMenu;

void Start(){
// Much better!
MyNavMenu = UI.document.getElementById("my-nav-menu");
}

void Update(){
// Use MyNavMenu in here
}

</syntaxhighlight>

== Reflow ==

Reflow is the name given when a web engine resolves CSS values and figures out where everything is on the screen. PowerUI also performs reflow, so following standard good practice for reducing reflow in a web browser applies to PowerUI too, so [https://developers.google.com/speed/articles/reflow here's a guide that will help with just that]. You may have cases where your UI generates lots of reflows very fast - PowerUI internally meters this using UI.SetRate; it won't reflow any more often than the rate you give.

* '''Power tip #1: Use UI.SetRate and get it as low as you reasonably can. The default is 30fps with super smooth at 60fps.'''

Following similar lines, pulling properties such as contentHeight from an element will force a reflow to happen if the element is known to require one. Accessing the computed style (element.style.Computed.ContentHeight for example) does not force reflows, so if you know e.g. the height didn't change then using computed styles directly can be a little quicker, but this only really applies if you're doing a style change and then grabbing the contentHeight rapidly in a loop.

* '''Power tip #2: Read from ComputedStyle where possible.'''

== Skipping Reflow ==

It's possible to pull off a complex UI which only performs reflow a handful of times by focusing on post-process CSS properties. These are CSS properties which don't affect the flow or structure of an element - the main examples are color, color-overlay, transform and the special case that is scroll. Generally try to animate these ones when you can!

* '''Power tip #3: Animate transforms (scale, rotate, translate) rather than positions (top, left, right etc) if possible.'''

=== Limiting reflow scope ===

Reflow applies to the nearest ''flow root'' element. For example, let's say you update the innerHTML of a fixed/absolute/sticky '''positioned element''' then ''only that element will actually reflow''. The same applies to any of the nested kids of that positioned element - it'll bubble up the DOM to the nearest flow root, and request to reflow that element. In short, making an element become a ''flow root'' is an easy way to massively limit how many elements reflow actually affects.

== Table Chaos ==

Tables cause multiple passes over potentially thousands of elements. The modern reason for using a table today is for vertical alignment - most other layouts can be easily done with other less intense techniques. If it's vertical align that you're really after then use the custom vertical-align values on any element:

<syntaxhighlight lang="css">

/* Middle vertical alignment without the overhead of table-cell/ tables */
vertical-align:table-middle;

</syntaxhighlight>

On a similar line, tables with no defined column widths are outright evil. The number of elements scanned to guess how wide a column probably should be can go exponential very quickly and after all of that, it often doesn't look great anyway. As a result, '''PowerUI doesn't support tables with no defined widths''' - you must give all your table columns and the table itself some kind of width value.

* '''Power tip #4: Use techniques other than table whenever appropriate, and make use of table-middle.'''

== Memory Usage ==

PowerUI is conservative about its memory usage, but if you're targeting really low memory devices, turning off [[Image_Atlasing|image atlasing]] may be wise. Turning it off exchanges GPU/rendering time for lower memory and CPU use, which can be vital for pulling off a stunning UI on a device with little memory available.

* '''Power tip #5: Turn off image atlasing for very low memory devices. See UI.RenderMode for doing that.'''

== Multithreading ==

Virtually all of PowerUI is multithreading friendly - anything that directly calls a Unity method like the geolocation web API isn't. Presently the cookie cache (loading or setting cookies) is the only known PowerUI API which avoidably causes threading issues. Use PowerUI API's directly from network threads, or spin up threads specifically for doing heavier UI work to make significant performance gains on multi-core architectures.

== Canvas ==

If you're drawing to a canvas, there's some nice savings you can be making. These savings are particularly noticeable if you're drawing repeatedly, such as in Update.

=== Only redraw your canvas when PowerUI does ===
PowerUI uploads the canvas image to the GPU no faster than your UI rate. Drawing your canvas any faster than that interval will essentially just waste cycles. We call that upload process a 'refresh' - whenever you call stroke() or fill(), a refresh request is made (and then at some point in the near future, a refresh happens).

So, if PowerUI already has an image which is ready but hasn't been uploaded yet, there will be a pending refresh. Checking for that is like this:

<syntaxhighlight lang="csharp">

private CanvasContext2D Context;

void Update(){

if(Context.ImageData.RefreshRequired){
// This means we've already rendered something to the image data
// and it's just waiting to be uploaded. Rendering again would be a waste of time.
// So, do nothing!
return;
}

// Nothing to upload - draw it now!
Context.beginPath();
Context.moveTo(10,10);
// ...

}

</syntaxhighlight>

=== Multithreading canvas ===

Like most PowerUI API's, canvas is multithreading friendly. You could build those paths on some separate timer thread if you wanted to, for example.

=== Cache your paths ===

Whenever you call context.arcTo, context.lineTo etc, PowerUI internally builds up a representation of your path. When you then next call context.beginPath or context.clear, that representation is destroyed. If you're drawing the same path over and over, it would be a great idea to save this internal representation rather than constantly rebuilding it to take some pressure off garbage collection.

'''If you do this, it's up to you to safely bound your points.''' Normally the canvas API automatically takes care of points that are excessively out of range for you - things like infinity, NaN, or generally huge numbers. If you build a VectorPath and set it to a canvas, it's important that you also guarantee your path doesn't have any of those things. Internally, the canvas API runs VectorPath.Clip on all paths constructed via lineTo, arcTo etc. Otherwise, if you have an extremely long path then the canvas API will freeze whilst it outputs billions of pixels.

To cache your paths you could either simply never call context.clear or context.beginPath and access Context.Path to move the nodes around like this:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI.

/// <summary>The canvas context.</summary>
private CanvasContext Context;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

}

void Update(){

// To clear the image but not the path, use ImageData:
Context.ImageData.Clear();

// The path is totally empty if there's no first node:
if(Context.Path.FirstPathNode == null){

// No path yet! Build it now:
Context.moveTo(10,10);
Context.lineTo(10,100);
Context.lineTo(100,100);
Context.lineTo(100,10);
Context.closePath();

// Note if any of the points in this first time call
// go far out of range of the canvas, they may be
// sliced for performance purposes.
// For example, if your entire path is off canvas,
// the whole thing may be dumped when you call stroke().

// One way to avoid that uncertainty is to build the VectorPath directly (like below)
// and then call VectorPath.Clip when it's appropriate for your use case.

}else{

// E.g. update the nodes in the cachedPath:
var point = CachedPath.FirstPathNode;

// Our path has 5 points (alternatively loop until point is null).
for(int i=0;i<5;i++){ // while(point!=null){

// Move the point by the frame time:
point.X += Time.deltaTime;

// Go to the next point:
point = point.Next;

}

}

// Stroke or fill etc down here:
Context.stroke();

}

</syntaxhighlight>

If you're drawing multiple paths and you want to cache them all, then the simpler route would be to directly build one or more VectorPath instances first:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI
using Blaze; // For VectorPath

/// <summary>The canvas context.</summary>
private CanvasContext Context;
/// <summary>A single cached path.</summary>
private VectorPath CachedPath;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

// build the vector path(s):
CachedPath = new VectorPath();

// The API is very similar - it's capitalized as it's part of the internal public API:
CachedPath.MoveTo(10,10);
CachedPath.LineTo(10,100);
CachedPath.LineTo(100,100);
CachedPath.LineTo(100,10);
CachedPath.ClosePath();

}

void Update(){

// Calling normal clear doesn't matter here (as we're not using e.g. Context.lineTo)
Context.clear();

// E.g. update current path here:
var point = CachedPath.FirstPathNode;

// note that closed paths never make infinite loops here.
// A close node simply overlaps the node it closes and has IsClose set to true.
while(point!=null){
point.X+=Time.deltaTime;
point=point.Next;
}

// Temporarily retain the path object in the canvas:
VectorPath activePath = Canvas.Path;

// Set ours:
Canvas.Path = CachedPath;

// Stroke it now:
Canvas.stroke();

// Restore the other path:
Canvas.Path = activePath;

}

</syntaxhighlight>

== Precompile PowerUI ==

Performance applies to your development process too. Unless you've got a solid state hard drive, PowerUI can take some 15 seconds to compile. Every time you change any of your C# files. [[Precompiler|Precompile PowerUI]] by going to '''Window > PowerUI > Precompile''' then just tick the box - that will entirely eliminate this delay for you.

'''If you change platform, or update Unity, you must precompile it again!''' That's because things like UNITY_ANDROID matter a lot.

Note that precompiling does not affect custom tags etc, but it does affect any ''partial class extensions''.

== Set textContent rather than innerHTML ==

If you know your text contains no HTML then setting to textContent will cause virtually everything to get recycled. Setting innerHTML is fast anyway but textContent does almost nothing.

You can also get another small boost if the new text you're setting is the same length as the old text - this takes advantage of a health counter optimisation:

<syntaxhighlight lang="csharp">

myElement.textContent = "1";
myElement.textContent = "14"; // 1 character longer

// Using 01 would make a (tiny) saving:
myElement.textContent = "01";
myElement.textContent = "14";

</syntaxhighlight>

== Disabling Unicode Bidirectionality ==

If you have no plans to use right-to-left or bidirectional text (like Arabic mixed with English), disable it by deleting '''PowerUI/Resources/BidirectionalData.bytes'''. This will give you a small memory saving (about 10kb) and slightly boost text performance.

You can also go further by specifying '''NoBIDI''' as a "scripting define symbols" as that will effectively remove all of the code which does the BIDI testing.

== Avoid late loading CSS ==

This is a massive performance drainer - avoid it! Put style as high up your document as you can (e.g. in head). That's because a newly loaded CSS selector must ''check your entire DOM'' to see if they match any of the elements already in there. If your DOM is basically empty then this operation is much faster.

Meanwhile, a newly loading element uses a range of indices to very rapidly figure out which selectors actually apply to it.

Linear lighting

2018-02-19T01:51:38Z

Bablakeluke:

If you'd like to use a linear lighting workflow in your project, you'll need to define a flag which tells PowerUI it should use the linear colour flow. If this flag isn't set, colours of your UI can appear a little off (either too bright, or too dark, depending on the colour).

'''To set the linear flag''':

* Open your current platform build settings
* Look for the text field called custom defines
* Add '''LINEAR''' in here

When you click out of the field, Unity will recompile your code and PowerUI will then be in linear lighting mode.

Linear lighting

2018-02-19T01:51:08Z

Bablakeluke:

If you'd like to use a linear lighting workflow in your project, you'll need to define a flag which tells PowerUI it should use the linear colour flow. If this flag isn't set, colours of your UI can appear a little off (either too bright, or too dark, depending on the colour).

'''To set the linear flag''', open your current platform build settings and look for the text field called custom defines. Add '''LINEAR''' in here and when you click out of the field, Unity will recompile your code and PowerUI will then be in linear lighting mode.

Linear lighting

2018-02-19T01:50:44Z

Bablakeluke: Created page with "If you'd like to use a linear lighting workflow in your project, you'll need to define a flag which tells PowerUI it should use the linear colour flow. If this flag isn't set,..."

If you'd like to use a linear lighting workflow in your project, you'll need to define a flag which tells PowerUI it should use the linear colour flow. If this flag isn't set, colours of your UI can appear a little off (either too bright, or too dark, depending on the colour).

To set the linear flag, open your current platform build settings and look for the text field called custom defines. Add `LINEAR` in here and when you click out of the field, Unity will recompile your code and PowerUI will then be in linear lighting mode.

Performance

2017-05-01T18:17:55Z

Bablakeluke: /* Set textContent rather than innerHTML */

PowerUI puts performance first. A user interface has very different requirements from a web browser - compare the UI of your favourite games with just how stationary this wiki is, for example. A web browser focuses on making a page show up quickly where as a game will spend time loading to make sure it ''runs'' quickly. PowerUI has been built from scratch to fit the requirements of a high performance UI framework.

In general, we only add support for something when we can get it working without affecting PowerUI's overall speed. It's working too - PowerUI can handle large volumes of HTML with little to no performance issues, whilst now simultaneously having very broad coverage of web technologies.

However, PowerUI is vulnerable to being exposed to some very performance draining web techniques (and there are many of them!) so this is intended to be a short guide to understanding how web engines work and what you can do to avoid some common pitfalls.

== Avoid searching for constant elements in Update ==

This one is a common mistake but can also make great performance savings if you make some small changes. Here's an example of what it looks like:

<syntaxhighlight lang="csharp">

void Update(){

// Don't do this!
var element = UI.document.getElementById("my-nav-menu");

}

</syntaxhighlight>

PowerUI will try and index your IDs, but in general, this will result in scanning your whole DOM every single frame. You should just cache the element instead:

<syntaxhighlight lang="csharp">

Element MyNavMenu;

void Start(){
// Much better!
MyNavMenu = UI.document.getElementById("my-nav-menu");
}

void Update(){
// Use MyNavMenu in here
}

</syntaxhighlight>

== Reflow ==

Reflow is the name given when a web engine resolves CSS values and figures out where everything is on the screen. PowerUI also performs reflow, so following standard good practice for reducing reflow in a web browser applies to PowerUI too, so [https://developers.google.com/speed/articles/reflow here's a guide that will help with just that]. You may have cases where your UI generates lots of reflows very fast - PowerUI internally meters this using UI.SetRate; it won't reflow any more often than the rate you give.

* '''Power tip #1: Use UI.SetRate and get it as low as you reasonably can. The default is 30fps with super smooth at 60fps.'''

Following similar lines, pulling properties such as contentHeight from an element will force a reflow to happen if the element is known to require one. Accessing the computed style (element.style.Computed.ContentHeight for example) does not force reflows, so if you know e.g. the height didn't change then using computed styles directly can be a little quicker, but this only really applies if you're doing a style change and then grabbing the contentHeight rapidly in a loop.

* '''Power tip #2: Read from ComputedStyle where possible.'''

== Skipping Reflow ==

It's possible to pull off a complex UI which only performs reflow a handful of times by focusing on post-process CSS properties. These are CSS properties which don't affect the flow or structure of an element - the main examples are color, color-overlay, transform and the special case that is scroll. Generally try to animate these ones when you can!

* '''Power tip #3: Animate transforms (scale, rotate, translate) rather than positions (top, left, right etc) if possible.'''

=== Limiting reflow scope ===

Reflow applies to the nearest ''flow root'' element. For example, let's say you update the innerHTML of a fixed/absolute/sticky '''positioned element''' then ''only that element will actually reflow''. The same applies to any of the nested kids of that positioned element - it'll bubble up the DOM to the nearest flow root, and request to reflow that element. In short, making an element become a ''flow root'' is an easy way to massively limit how many elements reflow actually affects.

== Table Chaos ==

Tables cause multiple passes over potentially thousands of elements. The modern reason for using a table today is for vertical alignment - most other layouts can be easily done with other less intense techniques. If it's vertical align that you're really after then use the custom vertical-align values on any element:

<syntaxhighlight lang="css">

/* Middle vertical alignment without the overhead of table-cell/ tables */
vertical-align:table-middle;

</syntaxhighlight>

* '''Power tip #4: Use techniques other than table whenever appropriate, and make use of table-middle.'''

== Memory Usage ==

PowerUI is conservative about its memory usage, but if you're targeting really low memory devices, turning off [[Image_Atlasing|image atlasing]] may be wise. Turning it off exchanges GPU/rendering time for lower memory and CPU use, which can be vital for pulling off a stunning UI on a device with little memory available.

* '''Power tip #5: Turn off image atlasing for very low memory devices. See UI.RenderMode for doing that.'''

== Multithreading ==

Virtually all of PowerUI is multithreading friendly - anything that directly calls a Unity method like the geolocation web API isn't. Presently the cookie cache (loading or setting cookies) is the only known PowerUI API which avoidably causes threading issues. Use PowerUI API's directly from network threads, or spin up threads specifically for doing heavier UI work to make significant performance gains on multi-core architectures.

== Canvas ==

If you're drawing to a canvas, there's some nice savings you can be making. These savings are particularly noticeable if you're drawing repeatedly, such as in Update.

=== Only redraw your canvas when PowerUI does ===
PowerUI uploads the canvas image to the GPU no faster than your UI rate. Drawing your canvas any faster than that interval will essentially just waste cycles. We call that upload process a 'refresh' - whenever you call stroke() or fill(), a refresh request is made (and then at some point in the near future, a refresh happens).

So, if PowerUI already has an image which is ready but hasn't been uploaded yet, there will be a pending refresh. Checking for that is like this:

<syntaxhighlight lang="csharp">

private CanvasContext2D Context;

void Update(){

if(Context.ImageData.RefreshRequired){
// This means we've already rendered something to the image data
// and it's just waiting to be uploaded. Rendering again would be a waste of time.
// So, do nothing!
return;
}

// Nothing to upload - draw it now!
Context.beginPath();
Context.moveTo(10,10);
// ...

}

</syntaxhighlight>

=== Multithreading canvas ===

Like most PowerUI API's, canvas is multithreading friendly. You could build those paths on some separate timer thread if you wanted to, for example.

=== Cache your paths ===

Whenever you call context.arcTo, context.lineTo etc, PowerUI internally builds up a representation of your path. When you then next call context.beginPath or context.clear, that representation is destroyed. If you're drawing the same path over and over, it would be a great idea to save this internal representation rather than constantly rebuilding it to take some pressure off garbage collection.

'''If you do this, it's up to you to safely bound your points.''' Normally the canvas API automatically takes care of points that are excessively out of range for you - things like infinity, NaN, or generally huge numbers. If you build a VectorPath and set it to a canvas, it's important that you also guarantee your path doesn't have any of those things. Internally, the canvas API runs VectorPath.Clip on all paths constructed via lineTo, arcTo etc. Otherwise, if you have an extremely long path then the canvas API will freeze whilst it outputs billions of pixels.

To cache your paths you could either simply never call context.clear or context.beginPath and access Context.Path to move the nodes around like this:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI.

/// <summary>The canvas context.</summary>
private CanvasContext Context;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

}

void Update(){

// To clear the image but not the path, use ImageData:
Context.ImageData.Clear();

// The path is totally empty if there's no first node:
if(Context.Path.FirstPathNode == null){

// No path yet! Build it now:
Context.moveTo(10,10);
Context.lineTo(10,100);
Context.lineTo(100,100);
Context.lineTo(100,10);
Context.closePath();

// Note if any of the points in this first time call
// go far out of range of the canvas, they may be
// sliced for performance purposes.
// For example, if your entire path is off canvas,
// the whole thing may be dumped when you call stroke().

// One way to avoid that uncertainty is to build the VectorPath directly (like below)
// and then call VectorPath.Clip when it's appropriate for your use case.

}else{

// E.g. update the nodes in the cachedPath:
var point = CachedPath.FirstPathNode;

// Our path has 5 points (alternatively loop until point is null).
for(int i=0;i<5;i++){ // while(point!=null){

// Move the point by the frame time:
point.X += Time.deltaTime;

// Go to the next point:
point = point.Next;

}

}

// Stroke or fill etc down here:
Context.stroke();

}

</syntaxhighlight>

If you're drawing multiple paths and you want to cache them all, then the simpler route would be to directly build one or more VectorPath instances first:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI
using Blaze; // For VectorPath

/// <summary>The canvas context.</summary>
private CanvasContext Context;
/// <summary>A single cached path.</summary>
private VectorPath CachedPath;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

// build the vector path(s):
CachedPath = new VectorPath();

// The API is very similar - it's capitalized as it's part of the internal public API:
CachedPath.MoveTo(10,10);
CachedPath.LineTo(10,100);
CachedPath.LineTo(100,100);
CachedPath.LineTo(100,10);
CachedPath.ClosePath();

}

void Update(){

// Calling normal clear doesn't matter here (as we're not using e.g. Context.lineTo)
Context.clear();

// E.g. update current path here:
var point = CachedPath.FirstPathNode;

// note that closed paths never make infinite loops here.
// A close node simply overlaps the node it closes and has IsClose set to true.
while(point!=null){
point.X+=Time.deltaTime;
point=point.Next;
}

// Temporarily retain the path object in the canvas:
VectorPath activePath = Canvas.Path;

// Set ours:
Canvas.Path = CachedPath;

// Stroke it now:
Canvas.stroke();

// Restore the other path:
Canvas.Path = activePath;

}

</syntaxhighlight>

== Precompile PowerUI ==

Performance applies to your development process too. Unless you've got a solid state hard drive, PowerUI can take some 15 seconds to compile. Every time you change any of your C# files. [[Precompiler|Precompile PowerUI]] by going to '''Window > PowerUI > Precompile''' then just tick the box - that will entirely eliminate this delay for you.

'''If you change platform, or update Unity, you must precompile it again!''' That's because things like UNITY_ANDROID matter a lot.

Note that precompiling does not affect custom tags etc, but it does affect any ''partial class extensions''.

== Set textContent rather than innerHTML ==

If you know your text contains no HTML then setting to textContent will cause virtually everything to get recycled. Setting innerHTML is fast anyway but textContent does almost nothing.

You can also get another small boost if the new text you're setting is the same length as the old text - this takes advantage of a health counter optimisation:

<syntaxhighlight lang="csharp">

myElement.textContent = "1";
myElement.textContent = "14"; // 1 character longer

// Using 01 would make a (tiny) saving:
myElement.textContent = "01";
myElement.textContent = "14";

</syntaxhighlight>

== Disabling Unicode Bidirectionality ==

If you have no plans to use right-to-left or bidirectional text (like Arabic mixed with English), disable it by deleting '''PowerUI/Resources/BidirectionalData.bytes'''. This will give you a small memory saving (about 10kb) and slightly boost text performance.

You can also go further by specifying '''NoBIDI''' as a "scripting define symbols" as that will effectively remove all of the code which does the BIDI testing.

== Avoid late loading CSS ==

This is a massive performance drainer - avoid it! Put style as high up your document as you can (e.g. in head). That's because a newly loaded CSS selector must ''check your entire DOM'' to see if they match any of the elements already in there. If your DOM is basically empty then this operation is much faster.

Meanwhile, a newly loading element uses a range of indices to very rapidly figure out which selectors actually apply to it.

Performance Tips

2017-05-01T18:13:34Z

Bablakeluke: Redirected page to Performance

#REDIRECT [[Performance]]

Performance

2017-05-01T18:11:47Z

Bablakeluke: /* Memory Usage */

PowerUI puts performance first. A user interface has very different requirements from a web browser - compare the UI of your favourite games with just how stationary this wiki is, for example. A web browser focuses on making a page show up quickly where as a game will spend time loading to make sure it ''runs'' quickly. PowerUI has been built from scratch to fit the requirements of a high performance UI framework.

In general, we only add support for something when we can get it working without affecting PowerUI's overall speed. It's working too - PowerUI can handle large volumes of HTML with little to no performance issues, whilst now simultaneously having very broad coverage of web technologies.

However, PowerUI is vulnerable to being exposed to some very performance draining web techniques (and there are many of them!) so this is intended to be a short guide to understanding how web engines work and what you can do to avoid some common pitfalls.

== Avoid searching for constant elements in Update ==

This one is a common mistake but can also make great performance savings if you make some small changes. Here's an example of what it looks like:

<syntaxhighlight lang="csharp">

void Update(){

// Don't do this!
var element = UI.document.getElementById("my-nav-menu");

}

</syntaxhighlight>

PowerUI will try and index your IDs, but in general, this will result in scanning your whole DOM every single frame. You should just cache the element instead:

<syntaxhighlight lang="csharp">

Element MyNavMenu;

void Start(){
// Much better!
MyNavMenu = UI.document.getElementById("my-nav-menu");
}

void Update(){
// Use MyNavMenu in here
}

</syntaxhighlight>

== Reflow ==

Reflow is the name given when a web engine resolves CSS values and figures out where everything is on the screen. PowerUI also performs reflow, so following standard good practice for reducing reflow in a web browser applies to PowerUI too, so [https://developers.google.com/speed/articles/reflow here's a guide that will help with just that]. You may have cases where your UI generates lots of reflows very fast - PowerUI internally meters this using UI.SetRate; it won't reflow any more often than the rate you give.

* '''Power tip #1: Use UI.SetRate and get it as low as you reasonably can. The default is 30fps with super smooth at 60fps.'''

Following similar lines, pulling properties such as contentHeight from an element will force a reflow to happen if the element is known to require one. Accessing the computed style (element.style.Computed.ContentHeight for example) does not force reflows, so if you know e.g. the height didn't change then using computed styles directly can be a little quicker, but this only really applies if you're doing a style change and then grabbing the contentHeight rapidly in a loop.

* '''Power tip #2: Read from ComputedStyle where possible.'''

== Skipping Reflow ==

It's possible to pull off a complex UI which only performs reflow a handful of times by focusing on post-process CSS properties. These are CSS properties which don't affect the flow or structure of an element - the main examples are color, color-overlay, transform and the special case that is scroll. Generally try to animate these ones when you can!

* '''Power tip #3: Animate transforms (scale, rotate, translate) rather than positions (top, left, right etc) if possible.'''

=== Limiting reflow scope ===

Reflow applies to the nearest ''flow root'' element. For example, let's say you update the innerHTML of a fixed/absolute/sticky '''positioned element''' then ''only that element will actually reflow''. The same applies to any of the nested kids of that positioned element - it'll bubble up the DOM to the nearest flow root, and request to reflow that element. In short, making an element become a ''flow root'' is an easy way to massively limit how many elements reflow actually affects.

== Table Chaos ==

Tables cause multiple passes over potentially thousands of elements. The modern reason for using a table today is for vertical alignment - most other layouts can be easily done with other less intense techniques. If it's vertical align that you're really after then use the custom vertical-align values on any element:

<syntaxhighlight lang="css">

/* Middle vertical alignment without the overhead of table-cell/ tables */
vertical-align:table-middle;

</syntaxhighlight>

* '''Power tip #4: Use techniques other than table whenever appropriate, and make use of table-middle.'''

== Memory Usage ==

PowerUI is conservative about its memory usage, but if you're targeting really low memory devices, turning off [[Image_Atlasing|image atlasing]] may be wise. Turning it off exchanges GPU/rendering time for lower memory and CPU use, which can be vital for pulling off a stunning UI on a device with little memory available.

* '''Power tip #5: Turn off image atlasing for very low memory devices. See UI.RenderMode for doing that.'''

== Multithreading ==

Virtually all of PowerUI is multithreading friendly - anything that directly calls a Unity method like the geolocation web API isn't. Presently the cookie cache (loading or setting cookies) is the only known PowerUI API which avoidably causes threading issues. Use PowerUI API's directly from network threads, or spin up threads specifically for doing heavier UI work to make significant performance gains on multi-core architectures.

== Canvas ==

If you're drawing to a canvas, there's some nice savings you can be making. These savings are particularly noticeable if you're drawing repeatedly, such as in Update.

=== Only redraw your canvas when PowerUI does ===
PowerUI uploads the canvas image to the GPU no faster than your UI rate. Drawing your canvas any faster than that interval will essentially just waste cycles. We call that upload process a 'refresh' - whenever you call stroke() or fill(), a refresh request is made (and then at some point in the near future, a refresh happens).

So, if PowerUI already has an image which is ready but hasn't been uploaded yet, there will be a pending refresh. Checking for that is like this:

<syntaxhighlight lang="csharp">

private CanvasContext2D Context;

void Update(){

if(Context.ImageData.RefreshRequired){
// This means we've already rendered something to the image data
// and it's just waiting to be uploaded. Rendering again would be a waste of time.
// So, do nothing!
return;
}

// Nothing to upload - draw it now!
Context.beginPath();
Context.moveTo(10,10);
// ...

}

</syntaxhighlight>

=== Multithreading canvas ===

Like most PowerUI API's, canvas is multithreading friendly. You could build those paths on some separate timer thread if you wanted to, for example.

=== Cache your paths ===

Whenever you call context.arcTo, context.lineTo etc, PowerUI internally builds up a representation of your path. When you then next call context.beginPath or context.clear, that representation is destroyed. If you're drawing the same path over and over, it would be a great idea to save this internal representation rather than constantly rebuilding it to take some pressure off garbage collection.

'''If you do this, it's up to you to safely bound your points.''' Normally the canvas API automatically takes care of points that are excessively out of range for you - things like infinity, NaN, or generally huge numbers. If you build a VectorPath and set it to a canvas, it's important that you also guarantee your path doesn't have any of those things. Internally, the canvas API runs VectorPath.Clip on all paths constructed via lineTo, arcTo etc. Otherwise, if you have an extremely long path then the canvas API will freeze whilst it outputs billions of pixels.

To cache your paths you could either simply never call context.clear or context.beginPath and access Context.Path to move the nodes around like this:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI.

/// <summary>The canvas context.</summary>
private CanvasContext Context;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

}

void Update(){

// To clear the image but not the path, use ImageData:
Context.ImageData.Clear();

// The path is totally empty if there's no first node:
if(Context.Path.FirstPathNode == null){

// No path yet! Build it now:
Context.moveTo(10,10);
Context.lineTo(10,100);
Context.lineTo(100,100);
Context.lineTo(100,10);
Context.closePath();

// Note if any of the points in this first time call
// go far out of range of the canvas, they may be
// sliced for performance purposes.
// For example, if your entire path is off canvas,
// the whole thing may be dumped when you call stroke().

// One way to avoid that uncertainty is to build the VectorPath directly (like below)
// and then call VectorPath.Clip when it's appropriate for your use case.

}else{

// E.g. update the nodes in the cachedPath:
var point = CachedPath.FirstPathNode;

// Our path has 5 points (alternatively loop until point is null).
for(int i=0;i<5;i++){ // while(point!=null){

// Move the point by the frame time:
point.X += Time.deltaTime;

// Go to the next point:
point = point.Next;

}

}

// Stroke or fill etc down here:
Context.stroke();

}

</syntaxhighlight>

If you're drawing multiple paths and you want to cache them all, then the simpler route would be to directly build one or more VectorPath instances first:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI
using Blaze; // For VectorPath

/// <summary>The canvas context.</summary>
private CanvasContext Context;
/// <summary>A single cached path.</summary>
private VectorPath CachedPath;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

// build the vector path(s):
CachedPath = new VectorPath();

// The API is very similar - it's capitalized as it's part of the internal public API:
CachedPath.MoveTo(10,10);
CachedPath.LineTo(10,100);
CachedPath.LineTo(100,100);
CachedPath.LineTo(100,10);
CachedPath.ClosePath();

}

void Update(){

// Calling normal clear doesn't matter here (as we're not using e.g. Context.lineTo)
Context.clear();

// E.g. update current path here:
var point = CachedPath.FirstPathNode;

// note that closed paths never make infinite loops here.
// A close node simply overlaps the node it closes and has IsClose set to true.
while(point!=null){
point.X+=Time.deltaTime;
point=point.Next;
}

// Temporarily retain the path object in the canvas:
VectorPath activePath = Canvas.Path;

// Set ours:
Canvas.Path = CachedPath;

// Stroke it now:
Canvas.stroke();

// Restore the other path:
Canvas.Path = activePath;

}

</syntaxhighlight>

== Precompile PowerUI ==

Performance applies to your development process too. Unless you've got a solid state hard drive, PowerUI can take some 15 seconds to compile. Every time you change any of your C# files. [[Precompiler|Precompile PowerUI]] by going to '''Window > PowerUI > Precompile''' then just tick the box - that will entirely eliminate this delay for you.

'''If you change platform, or update Unity, you must precompile it again!''' That's because things like UNITY_ANDROID matter a lot.

Note that precompiling does not affect custom tags etc, but it does affect any ''partial class extensions''.

== Set textContent rather than innerHTML ==

If you know your text contains no HTML then setting to textContent will cause virtually everything to get recycled. Setting innerHTML is fast anyway but textContent does almost nothing.

== Disabling Unicode Bidirectionality ==

If you have no plans to use right-to-left or bidirectional text (like Arabic mixed with English), disable it by deleting '''PowerUI/Resources/BidirectionalData.bytes'''. This will give you a small memory saving (about 10kb) and slightly boost text performance.

You can also go further by specifying '''NoBIDI''' as a "scripting define symbols" as that will effectively remove all of the code which does the BIDI testing.

== Avoid late loading CSS ==

This is a massive performance drainer - avoid it! Put style as high up your document as you can (e.g. in head). That's because a newly loaded CSS selector must ''check your entire DOM'' to see if they match any of the elements already in there. If your DOM is basically empty then this operation is much faster.

Meanwhile, a newly loading element uses a range of indices to very rapidly figure out which selectors actually apply to it.

Performance

2017-05-01T18:08:20Z

Bablakeluke:

PowerUI puts performance first. A user interface has very different requirements from a web browser - compare the UI of your favourite games with just how stationary this wiki is, for example. A web browser focuses on making a page show up quickly where as a game will spend time loading to make sure it ''runs'' quickly. PowerUI has been built from scratch to fit the requirements of a high performance UI framework.

In general, we only add support for something when we can get it working without affecting PowerUI's overall speed. It's working too - PowerUI can handle large volumes of HTML with little to no performance issues, whilst now simultaneously having very broad coverage of web technologies.

However, PowerUI is vulnerable to being exposed to some very performance draining web techniques (and there are many of them!) so this is intended to be a short guide to understanding how web engines work and what you can do to avoid some common pitfalls.

== Avoid searching for constant elements in Update ==

This one is a common mistake but can also make great performance savings if you make some small changes. Here's an example of what it looks like:

<syntaxhighlight lang="csharp">

void Update(){

// Don't do this!
var element = UI.document.getElementById("my-nav-menu");

}

</syntaxhighlight>

PowerUI will try and index your IDs, but in general, this will result in scanning your whole DOM every single frame. You should just cache the element instead:

<syntaxhighlight lang="csharp">

Element MyNavMenu;

void Start(){
// Much better!
MyNavMenu = UI.document.getElementById("my-nav-menu");
}

void Update(){
// Use MyNavMenu in here
}

</syntaxhighlight>

== Reflow ==

Reflow is the name given when a web engine resolves CSS values and figures out where everything is on the screen. PowerUI also performs reflow, so following standard good practice for reducing reflow in a web browser applies to PowerUI too, so [https://developers.google.com/speed/articles/reflow here's a guide that will help with just that]. You may have cases where your UI generates lots of reflows very fast - PowerUI internally meters this using UI.SetRate; it won't reflow any more often than the rate you give.

* '''Power tip #1: Use UI.SetRate and get it as low as you reasonably can. The default is 30fps with super smooth at 60fps.'''

Following similar lines, pulling properties such as contentHeight from an element will force a reflow to happen if the element is known to require one. Accessing the computed style (element.style.Computed.ContentHeight for example) does not force reflows, so if you know e.g. the height didn't change then using computed styles directly can be a little quicker, but this only really applies if you're doing a style change and then grabbing the contentHeight rapidly in a loop.

* '''Power tip #2: Read from ComputedStyle where possible.'''

== Skipping Reflow ==

It's possible to pull off a complex UI which only performs reflow a handful of times by focusing on post-process CSS properties. These are CSS properties which don't affect the flow or structure of an element - the main examples are color, color-overlay, transform and the special case that is scroll. Generally try to animate these ones when you can!

* '''Power tip #3: Animate transforms (scale, rotate, translate) rather than positions (top, left, right etc) if possible.'''

=== Limiting reflow scope ===

Reflow applies to the nearest ''flow root'' element. For example, let's say you update the innerHTML of a fixed/absolute/sticky '''positioned element''' then ''only that element will actually reflow''. The same applies to any of the nested kids of that positioned element - it'll bubble up the DOM to the nearest flow root, and request to reflow that element. In short, making an element become a ''flow root'' is an easy way to massively limit how many elements reflow actually affects.

== Table Chaos ==

Tables cause multiple passes over potentially thousands of elements. The modern reason for using a table today is for vertical alignment - most other layouts can be easily done with other less intense techniques. If it's vertical align that you're really after then use the custom vertical-align values on any element:

<syntaxhighlight lang="css">

/* Middle vertical alignment without the overhead of table-cell/ tables */
vertical-align:table-middle;

</syntaxhighlight>

* '''Power tip #4: Use techniques other than table whenever appropriate, and make use of table-middle.'''

== Memory Usage ==

PowerUI is conservative about its memory usage, but if your targeting really low memory devices, turning off [[Image_Atlasing|image atlasing]] may be wise. Turning it off exchanges GPU/rendering time for lower memory and CPU use, which can be vital for pulling off a stunning UI on a device with little memory available.

* '''Power tip #5: Turn off image atlasing for very low memory devices. See UI.RenderMode for doing that.'''

== Multithreading ==

Virtually all of PowerUI is multithreading friendly - anything that directly calls a Unity method like the geolocation web API isn't. Presently the cookie cache (loading or setting cookies) is the only known PowerUI API which avoidably causes threading issues. Use PowerUI API's directly from network threads, or spin up threads specifically for doing heavier UI work to make significant performance gains on multi-core architectures.

== Canvas ==

If you're drawing to a canvas, there's some nice savings you can be making. These savings are particularly noticeable if you're drawing repeatedly, such as in Update.

=== Only redraw your canvas when PowerUI does ===
PowerUI uploads the canvas image to the GPU no faster than your UI rate. Drawing your canvas any faster than that interval will essentially just waste cycles. We call that upload process a 'refresh' - whenever you call stroke() or fill(), a refresh request is made (and then at some point in the near future, a refresh happens).

So, if PowerUI already has an image which is ready but hasn't been uploaded yet, there will be a pending refresh. Checking for that is like this:

<syntaxhighlight lang="csharp">

private CanvasContext2D Context;

void Update(){

if(Context.ImageData.RefreshRequired){
// This means we've already rendered something to the image data
// and it's just waiting to be uploaded. Rendering again would be a waste of time.
// So, do nothing!
return;
}

// Nothing to upload - draw it now!
Context.beginPath();
Context.moveTo(10,10);
// ...

}

</syntaxhighlight>

=== Multithreading canvas ===

Like most PowerUI API's, canvas is multithreading friendly. You could build those paths on some separate timer thread if you wanted to, for example.

=== Cache your paths ===

Whenever you call context.arcTo, context.lineTo etc, PowerUI internally builds up a representation of your path. When you then next call context.beginPath or context.clear, that representation is destroyed. If you're drawing the same path over and over, it would be a great idea to save this internal representation rather than constantly rebuilding it to take some pressure off garbage collection.

'''If you do this, it's up to you to safely bound your points.''' Normally the canvas API automatically takes care of points that are excessively out of range for you - things like infinity, NaN, or generally huge numbers. If you build a VectorPath and set it to a canvas, it's important that you also guarantee your path doesn't have any of those things. Internally, the canvas API runs VectorPath.Clip on all paths constructed via lineTo, arcTo etc. Otherwise, if you have an extremely long path then the canvas API will freeze whilst it outputs billions of pixels.

To cache your paths you could either simply never call context.clear or context.beginPath and access Context.Path to move the nodes around like this:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI.

/// <summary>The canvas context.</summary>
private CanvasContext Context;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

}

void Update(){

// To clear the image but not the path, use ImageData:
Context.ImageData.Clear();

// The path is totally empty if there's no first node:
if(Context.Path.FirstPathNode == null){

// No path yet! Build it now:
Context.moveTo(10,10);
Context.lineTo(10,100);
Context.lineTo(100,100);
Context.lineTo(100,10);
Context.closePath();

// Note if any of the points in this first time call
// go far out of range of the canvas, they may be
// sliced for performance purposes.
// For example, if your entire path is off canvas,
// the whole thing may be dumped when you call stroke().

// One way to avoid that uncertainty is to build the VectorPath directly (like below)
// and then call VectorPath.Clip when it's appropriate for your use case.

}else{

// E.g. update the nodes in the cachedPath:
var point = CachedPath.FirstPathNode;

// Our path has 5 points (alternatively loop until point is null).
for(int i=0;i<5;i++){ // while(point!=null){

// Move the point by the frame time:
point.X += Time.deltaTime;

// Go to the next point:
point = point.Next;

}

}

// Stroke or fill etc down here:
Context.stroke();

}

</syntaxhighlight>

If you're drawing multiple paths and you want to cache them all, then the simpler route would be to directly build one or more VectorPath instances first:

<syntaxhighlight lang="csharp">

using PowerUI; // For CanvasContext and UI
using Blaze; // For VectorPath

/// <summary>The canvas context.</summary>
private CanvasContext Context;
/// <summary>A single cached path.</summary>
private VectorPath CachedPath;

void Start(){

var document = UI.document;

var canvas = document.getElementById("my-canvas") as HtmlElement;

Context = canvas.getContext("2d");

// build the vector path(s):
CachedPath = new VectorPath();

// The API is very similar - it's capitalized as it's part of the internal public API:
CachedPath.MoveTo(10,10);
CachedPath.LineTo(10,100);
CachedPath.LineTo(100,100);
CachedPath.LineTo(100,10);
CachedPath.ClosePath();

}

void Update(){

// Calling normal clear doesn't matter here (as we're not using e.g. Context.lineTo)
Context.clear();

// E.g. update current path here:
var point = CachedPath.FirstPathNode;

// note that closed paths never make infinite loops here.
// A close node simply overlaps the node it closes and has IsClose set to true.
while(point!=null){
point.X+=Time.deltaTime;
point=point.Next;
}

// Temporarily retain the path object in the canvas:
VectorPath activePath = Canvas.Path;

// Set ours:
Canvas.Path = CachedPath;

// Stroke it now:
Canvas.stroke();

// Restore the other path:
Canvas.Path = activePath;

}

</syntaxhighlight>

== Precompile PowerUI ==

Performance applies to your development process too. Unless you've got a solid state hard drive, PowerUI can take some 15 seconds to compile. Every time you change any of your C# files. [[Precompiler|Precompile PowerUI]] by going to '''Window > PowerUI > Precompile''' then just tick the box - that will entirely eliminate this delay for you.

'''If you change platform, or update Unity, you must precompile it again!''' That's because things like UNITY_ANDROID matter a lot.

Note that precompiling does not affect custom tags etc, but it does affect any ''partial class extensions''.

== Set textContent rather than innerHTML ==

If you know your text contains no HTML then setting to textContent will cause virtually everything to get recycled. Setting innerHTML is fast anyway but textContent does almost nothing.

== Disabling Unicode Bidirectionality ==

If you have no plans to use right-to-left or bidirectional text (like Arabic mixed with English), disable it by deleting '''PowerUI/Resources/BidirectionalData.bytes'''. This will give you a small memory saving (about 10kb) and slightly boost text performance.

You can also go further by specifying '''NoBIDI''' as a "scripting define symbols" as that will effectively remove all of the code which does the BIDI testing.

== Avoid late loading CSS ==

This is a massive performance drainer - avoid it! Put style as high up your document as you can (e.g. in head). That's because a newly loaded CSS selector must ''check your entire DOM'' to see if they match any of the elements already in there. If your DOM is basically empty then this operation is much faster.

Meanwhile, a newly loading element uses a range of indices to very rapidly figure out which selectors actually apply to it.

Input Pointers

2017-05-01T04:10:52Z

Bablakeluke: /* Virtual Reality */

An input pointer is [https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events#term_pointer any kind of pointing device] which presses, hovers, or both. A mouse, a finger and a stylus are the three main ones. They are related to the (draft) [https://w3c.github.io/pointerevents/ W3C Pointer Events specification]. Here's some specific notes about the input pointers available in PowerUI.

== Mouse Input ==

PowerUI assumes that only a desktop platform will have a mouse. A [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1MousePointer.html MousePointer] is created when it's running on a desktop and [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a7527e2574ccda7fb7cdd2d8a28fff6db PowerUI.Input.CreateSystemMouse] is true ''(the default)''. If your project doesn't use a mouse pointer on a desktop platform (it's [[Virtual Reality Cameras|virtual reality]] for example), you'd remove it by setting [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a7527e2574ccda7fb7cdd2d8a28fff6db CreateSystemMouse] to false in an Awake method.

== Touch and Stylus Input ==

PowerUI handles multi-touch input by default on any platform which supports it. It will automatically stack with a mouse input on desktops which also have touchscreens. Each time a new touch is detected, a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1FingerPointer.html FingerPointer] or a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1StylusPointer.html StylusPointer] is created. They fire the various [https://developer.mozilla.org/en-US/docs/Web/API/Touch_events touch events] as well as [https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent mouse events].

All pointers are [https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/isPrimary primary] (which means they all fire those mouse events too).

== Virtual Reality ==

PowerUI has a custom input pointer, a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1CameraPointer.html CameraPointer], for virtual reality. See [[Virtual Reality Cameras|the article]] relating to virtual reality camera's. Alternatively here's a (rough!) laser pointer input example. Just add it to your project and see the notes below on how to e.g. add it and make it click:

<syntaxhighlight lang='csharp'>
using System;
using UnityEngine;

/// <summary>A laser pointer which fires an input ray from e.g. a 3D hand.</summary>
public class LaserPointer : PowerUI.InputPointer{

public Transform Transform;
/// <summary>True if UI's move around.</summary>
public bool MovingUIs;

/// <summary>Setup a laser pointer from the given transform (e.g. a hand object).</summary>
public LaserPointer(Transform transform):this(transform,true){}

/// <summary>Setup a laser pointer from the given transform (e.g. a hand object).</summary>
/// <param name='movingUIs'>Set this to true if your WorldUI's move around.
/// Setting it to false is a small performance saving. If you're not sure, just use true.</param>
public LaserPointer(Transform transform, bool movingUIs){
Transform = transform;
MovingUIs = movingUIs;

// It won't interact with the main UI so just put it offscreen to skip checking entirely:
ScreenX = ScreenY = -1000f;

}

public override bool Raycast(out RaycastHit hit, Camera cam, Vector2 screenPoint){

// Fire off your ray in whatever your pointers direction is; we'll use transform.forward here.
// ('forward' is +ve z):
Ray ray = new Ray(Transform.position, Transform.forward);

return Physics.Raycast(theRay, out hit);
}

public override bool Relocate(out Vector2 delta){

// We can just ignore delta (it's for the main UI):
delta = Vector2.zero;

if(MovingUIs){
// Always recompute.
return true;
}

// Transform moved?
if(Transform!=null && Transform.hasChanged){
Transform.hasChanged = false;
return true;
}

// Don't bother recalculating - it's not moved.
// (Always return true if your UI's are moving instead).
return false;
}

}

</syntaxhighlight>

Usage:

<syntaxhighlight lang='csharp'>

// Fires a ray from the given hand object. If your UI's don't move around, use LaserPointer(aHandObject,false) to make a performance gain.
LaserPointer myPointer = new LaserPointer(aHandObject);

// Add it:
myPointer.Add();

// myPointer.LeftDown(); etc to click (see more below)

</syntaxhighlight>

== Define your own ==

If you're doing something more specialised then you can also define your own input pointer. Multiple Wii controllers, for example. This is very straight forward to do - at a minimum you must inherit from InputPointer:

<syntaxhighlight lang="csharp">

public class MyCustomPointer : InputPointer{
}

</syntaxhighlight>

Then to use it, all you need to do is create and add it:

<syntaxhighlight lang="csharp">
MyCustomPointer pointer = new MyCustomPointer();
pointer.Add();
</syntaxhighlight>

It can be clicked etc or have a pressure value like any other pointer. To move it around, set the Position property (Top left corner is 0,0):

<syntaxhighlight lang="csharp">
pointer.Position = new Vector2(100,100);
</syntaxhighlight>

Alternatively you can put your position update logic inside the pointer itself by overriding the Relocate method:

<syntaxhighlight lang="csharp">

public class MyCustomPointer : InputPointer{

public override bool Relocate(out Vector2 positionChange){

// - Get your latest coordinates here -
Vector2 newPosition = Vector2.zero;

// Try moving it (just returns false if your position wasn't different to the current one):
return TryChangePosition(newPosition, out positionChange);
}

}

</syntaxhighlight>

== Making it click ==

If you've got an input pointer and you'd like to click it (or vary its downward pressure), you can either:

* Use the convenience method for mouse up/down events from OnGUI:

<syntaxhighlight lang="csharp">

void OnGUI(){

// Returns true if your pointer actually did something (it went down or up)
// You can also directly pass a UnityEngine.Event too.
bool didSomething = MyPointer.HandleEvent();

}

</syntaxhighlight>

* Call the MyPointer.Down and MyPointer.Up methods (Optionally specifying a [https://docs.unity3d.com/ScriptReference/Event-button.html mouse button ID]):

<syntaxhighlight lang="csharp">

// Mousedown event, left button:
MyPointer.Down(0);

// Which is also the same as:
MyPointer.LeftDown();

// Mouseup event, left button:
MyPointer.Up(0);

// Which is the same as:
MyPointer.LeftUp();

</syntaxhighlight>

* Use SetPressure directly - this is useful if you've got some kind of stylus ''(every other option is just an abstraction of SetPressure)''

<syntaxhighlight lang="csharp">

void Update(){

// Update the pointer pressure:
MyPointer.SetPressure(someVaryingField);

}

</syntaxhighlight>

== Accessing all pointers ==

PowerUI implements various standard API's for accessing pointers:

* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1TouchEvent.html TouchEvent].touches
* TouchEvent.targetTouches
* TouchEvent.changedTouches
* TouchEvent.identifier
* ''More!''

The non-standard internal ones:

* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1UIEvent.html#a2daa44fbceddd8510bc2791340a432b4 UIEvent.trigger] - ''MouseEvent, TouchEvent etc; The InputPointer instance this event came from''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#a77189cd51fedf33c73759f641c8380ef InputPointer.All] - ''All active pointers (array created on use; Use AllRaw and PointerCount for better performance)''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#a731d759f87ece43622fb497b5e3d88b3 InputPointer.PointerCount] - ''The number of actual pointers in the AllRaw pointer set''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#aa76092f569304c8fcf6c3bea1f9612e3 InputPointer.AllRaw] - ''The raw set of pointers. Entries beyond PointerCount are random noise/ undefined.''

== Source locations ==

You'll find the implementations of MousePointer, FingerPointer etc here:

* PowerUI/Source/Engine/Input/

Virtual Reality Cameras

2017-05-01T04:08:39Z

Bablakeluke:

In virtual reality, it's common to see the middle of the screen being used as the [[Input Pointers|input pointer]]. Think Minecraft and similar. Here's how you set that up in PowerUI using the CameraPointer class.

Note that the UI's you create would almost always be one or more [[World UI|WorldUI's]].

== Creating a CameraPointer ==

* You'll probably want to turn off the mouse pointer (It's used on desktops only). It's the input pointer which is controlled by the mouse.
* In an Awake method, create a CameraPointer for a particular camera.

Here's an example:

<syntaxhighlight lang="csharp">

CameraPointer MyPointer;

void Awake(){

// Disable the system mouse:
PowerUI.Input.CreateSystemMouse=false;

// Create a camera pointer that sits in the middle of the screen (50%,50%):
MyPointer = new CameraPointer(Camera.main,0.5f,0.5f);

// Add it now:
MyPointer.Add();

}

</syntaxhighlight>

Whenever the camera you gave is transformed (i.e. rotated or moved around), the pointer automatically updates itself.

== Laser Pointers ==

You can also entirely override the raycast to create a clickable/ hoverable input ray in any direction. Check out the [[Input Pointers#Virtual Reality|input pointers]] page for an example custom laser input pointer.

== Making it click ==

See the section on [[Input Pointers#Making it click|input pointers]] about making them click.

Input Pointers

2017-05-01T04:07:03Z

Bablakeluke: /* Virtual Reality */

An input pointer is [https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events#term_pointer any kind of pointing device] which presses, hovers, or both. A mouse, a finger and a stylus are the three main ones. They are related to the (draft) [https://w3c.github.io/pointerevents/ W3C Pointer Events specification]. Here's some specific notes about the input pointers available in PowerUI.

== Mouse Input ==

PowerUI assumes that only a desktop platform will have a mouse. A [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1MousePointer.html MousePointer] is created when it's running on a desktop and [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a7527e2574ccda7fb7cdd2d8a28fff6db PowerUI.Input.CreateSystemMouse] is true ''(the default)''. If your project doesn't use a mouse pointer on a desktop platform (it's [[Virtual Reality Cameras|virtual reality]] for example), you'd remove it by setting [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a7527e2574ccda7fb7cdd2d8a28fff6db CreateSystemMouse] to false in an Awake method.

== Touch and Stylus Input ==

PowerUI handles multi-touch input by default on any platform which supports it. It will automatically stack with a mouse input on desktops which also have touchscreens. Each time a new touch is detected, a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1FingerPointer.html FingerPointer] or a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1StylusPointer.html StylusPointer] is created. They fire the various [https://developer.mozilla.org/en-US/docs/Web/API/Touch_events touch events] as well as [https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent mouse events].

All pointers are [https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/isPrimary primary] (which means they all fire those mouse events too).

== Virtual Reality ==

PowerUI has a custom input pointer, a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1CameraPointer.html CameraPointer], for virtual reality. See [[Virtual Reality Cameras|the article]] relating to virtual reality camera's. Alternatively here's a (rough!) laser pointer input example:

<syntaxhighlight lang='csharp'>
using System;
using UnityEngine;

/// <summary>A laser pointer which fires an input ray from e.g. a 3D hand.</summary>
public class LaserPointer : PowerUI.InputPointer{

public Transform Transform;
/// <summary>True if UI's move around.</summary>
public bool MovingUIs;

/// <summary>Setup a laser pointer from the given transform (e.g. a hand object).</summary>
public LaserPointer(Transform transform):this(transform,true){}

/// <summary>Setup a laser pointer from the given transform (e.g. a hand object).</summary>
/// <param name='movingUIs'>Set this to true if your WorldUI's move around.
/// Setting it to false is a small performance saving. If you're not sure, just use true.</param>
public LaserPointer(Transform transform, bool movingUIs){
Transform = transform;
MovingUIs = movingUIs;

// It won't interact with the main UI so just put it offscreen to skip checking entirely:
ScreenX = ScreenY = -1000f;

}

public override bool Raycast(out RaycastHit hit, Camera cam, Vector2 screenPoint){

// Fire off your ray in whatever your pointers direction is; we'll use transform.forward here.
// ('forward' is +ve z):
Ray ray = new Ray(Transform.position, Transform.forward);

return Physics.Raycast(theRay, out hit);
}

public override bool Relocate(out Vector2 delta){

// We can just ignore delta (it's for the main UI):
delta = Vector2.zero;

if(MovingUIs){
// Always recompute.
return true;
}

// Transform moved?
if(Transform!=null && Transform.hasChanged){
Transform.hasChanged = false;
return true;
}

// Don't bother recalculating - it's not moved.
// (Always return true if your UI's are moving instead).
return false;
}

}

</syntaxhighlight>

== Define your own ==

If you're doing something more specialised then you can also define your own input pointer. Multiple Wii controllers, for example. This is very straight forward to do - at a minimum you must inherit from InputPointer:

<syntaxhighlight lang="csharp">

public class MyCustomPointer : InputPointer{
}

</syntaxhighlight>

Then to use it, all you need to do is create and add it:

<syntaxhighlight lang="csharp">
MyCustomPointer pointer = new MyCustomPointer();
pointer.Add();
</syntaxhighlight>

It can be clicked etc or have a pressure value like any other pointer. To move it around, set the Position property (Top left corner is 0,0):

<syntaxhighlight lang="csharp">
pointer.Position = new Vector2(100,100);
</syntaxhighlight>

Alternatively you can put your position update logic inside the pointer itself by overriding the Relocate method:

<syntaxhighlight lang="csharp">

public class MyCustomPointer : InputPointer{

public override bool Relocate(out Vector2 positionChange){

// - Get your latest coordinates here -
Vector2 newPosition = Vector2.zero;

// Try moving it (just returns false if your position wasn't different to the current one):
return TryChangePosition(newPosition, out positionChange);
}

}

</syntaxhighlight>

== Making it click ==

If you've got an input pointer and you'd like to click it (or vary its downward pressure), you can either:

* Use the convenience method for mouse up/down events from OnGUI:

<syntaxhighlight lang="csharp">

void OnGUI(){

// Returns true if your pointer actually did something (it went down or up)
// You can also directly pass a UnityEngine.Event too.
bool didSomething = MyPointer.HandleEvent();

}

</syntaxhighlight>

* Call the MyPointer.Down and MyPointer.Up methods (Optionally specifying a [https://docs.unity3d.com/ScriptReference/Event-button.html mouse button ID]):

<syntaxhighlight lang="csharp">

// Mousedown event, left button:
MyPointer.Down(0);

// Which is also the same as:
MyPointer.LeftDown();

// Mouseup event, left button:
MyPointer.Up(0);

// Which is the same as:
MyPointer.LeftUp();

</syntaxhighlight>

* Use SetPressure directly - this is useful if you've got some kind of stylus ''(every other option is just an abstraction of SetPressure)''

<syntaxhighlight lang="csharp">

void Update(){

// Update the pointer pressure:
MyPointer.SetPressure(someVaryingField);

}

</syntaxhighlight>

== Accessing all pointers ==

PowerUI implements various standard API's for accessing pointers:

* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1TouchEvent.html TouchEvent].touches
* TouchEvent.targetTouches
* TouchEvent.changedTouches
* TouchEvent.identifier
* ''More!''

The non-standard internal ones:

* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1UIEvent.html#a2daa44fbceddd8510bc2791340a432b4 UIEvent.trigger] - ''MouseEvent, TouchEvent etc; The InputPointer instance this event came from''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#a77189cd51fedf33c73759f641c8380ef InputPointer.All] - ''All active pointers (array created on use; Use AllRaw and PointerCount for better performance)''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#a731d759f87ece43622fb497b5e3d88b3 InputPointer.PointerCount] - ''The number of actual pointers in the AllRaw pointer set''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#aa76092f569304c8fcf6c3bea1f9612e3 InputPointer.AllRaw] - ''The raw set of pointers. Entries beyond PointerCount are random noise/ undefined.''

== Source locations ==

You'll find the implementations of MousePointer, FingerPointer etc here:

* PowerUI/Source/Engine/Input/

Input Pointers

2017-04-23T17:54:45Z

Bablakeluke: /* Define your own */

An input pointer is [https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events#term_pointer any kind of pointing device] which presses, hovers, or both. A mouse, a finger and a stylus are the three main ones. They are related to the (draft) [https://w3c.github.io/pointerevents/ W3C Pointer Events specification]. Here's some specific notes about the input pointers available in PowerUI.

== Mouse Input ==

PowerUI assumes that only a desktop platform will have a mouse. A [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1MousePointer.html MousePointer] is created when it's running on a desktop and [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a7527e2574ccda7fb7cdd2d8a28fff6db PowerUI.Input.CreateSystemMouse] is true ''(the default)''. If your project doesn't use a mouse pointer on a desktop platform (it's [[Virtual Reality Cameras|virtual reality]] for example), you'd remove it by setting [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a7527e2574ccda7fb7cdd2d8a28fff6db CreateSystemMouse] to false in an Awake method.

== Touch and Stylus Input ==

PowerUI handles multi-touch input by default on any platform which supports it. It will automatically stack with a mouse input on desktops which also have touchscreens. Each time a new touch is detected, a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1FingerPointer.html FingerPointer] or a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1StylusPointer.html StylusPointer] is created. They fire the various [https://developer.mozilla.org/en-US/docs/Web/API/Touch_events touch events] as well as [https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent mouse events].

All pointers are [https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/isPrimary primary] (which means they all fire those mouse events too).

== Virtual Reality ==

PowerUI has a custom input pointer, a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1CameraPointer.html CameraPointer], for virtual reality. See [[Virtual Reality Cameras|the article]] relating to virtual reality camera's.

== Define your own ==

If you're doing something more specialised then you can also define your own input pointer. Multiple Wii controllers, for example. This is very straight forward to do - at a minimum you must inherit from InputPointer:

<syntaxhighlight lang="csharp">

public class MyCustomPointer : InputPointer{
}

</syntaxhighlight>

Then to use it, all you need to do is create and add it:

<syntaxhighlight lang="csharp">
MyCustomPointer pointer = new MyCustomPointer();
pointer.Add();
</syntaxhighlight>

It can be clicked etc or have a pressure value like any other pointer. To move it around, set the Position property (Top left corner is 0,0):

<syntaxhighlight lang="csharp">
pointer.Position = new Vector2(100,100);
</syntaxhighlight>

Alternatively you can put your position update logic inside the pointer itself by overriding the Relocate method:

<syntaxhighlight lang="csharp">

public class MyCustomPointer : InputPointer{

public override bool Relocate(out Vector2 positionChange){

// - Get your latest coordinates here -
Vector2 newPosition = Vector2.zero;

// Try moving it (just returns false if your position wasn't different to the current one):
return TryChangePosition(newPosition, out positionChange);
}

}

</syntaxhighlight>

== Making it click ==

If you've got an input pointer and you'd like to click it (or vary its downward pressure), you can either:

* Use the convenience method for mouse up/down events from OnGUI:

<syntaxhighlight lang="csharp">

void OnGUI(){

// Returns true if your pointer actually did something (it went down or up)
// You can also directly pass a UnityEngine.Event too.
bool didSomething = MyPointer.HandleEvent();

}

</syntaxhighlight>

* Call the MyPointer.Down and MyPointer.Up methods (Optionally specifying a [https://docs.unity3d.com/ScriptReference/Event-button.html mouse button ID]):

<syntaxhighlight lang="csharp">

// Mousedown event, left button:
MyPointer.Down(0);

// Which is also the same as:
MyPointer.LeftDown();

// Mouseup event, left button:
MyPointer.Up(0);

// Which is the same as:
MyPointer.LeftUp();

</syntaxhighlight>

* Use SetPressure directly - this is useful if you've got some kind of stylus ''(every other option is just an abstraction of SetPressure)''

<syntaxhighlight lang="csharp">

void Update(){

// Update the pointer pressure:
MyPointer.SetPressure(someVaryingField);

}

</syntaxhighlight>

== Accessing all pointers ==

PowerUI implements various standard API's for accessing pointers:

* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1TouchEvent.html TouchEvent].touches
* TouchEvent.targetTouches
* TouchEvent.changedTouches
* TouchEvent.identifier
* ''More!''

The non-standard internal ones:

* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1UIEvent.html#a2daa44fbceddd8510bc2791340a432b4 UIEvent.trigger] - ''MouseEvent, TouchEvent etc; The InputPointer instance this event came from''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#a77189cd51fedf33c73759f641c8380ef InputPointer.All] - ''All active pointers (array created on use; Use AllRaw and PointerCount for better performance)''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#a731d759f87ece43622fb497b5e3d88b3 InputPointer.PointerCount] - ''The number of actual pointers in the AllRaw pointer set''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#aa76092f569304c8fcf6c3bea1f9612e3 InputPointer.AllRaw] - ''The raw set of pointers. Entries beyond PointerCount are random noise/ undefined.''

== Source locations ==

You'll find the implementations of MousePointer, FingerPointer etc here:

* PowerUI/Source/Engine/Input/

Input Pointers

2017-04-23T17:43:52Z

Bablakeluke: /* Define your own */

An input pointer is [https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events#term_pointer any kind of pointing device] which presses, hovers, or both. A mouse, a finger and a stylus are the three main ones. They are related to the (draft) [https://w3c.github.io/pointerevents/ W3C Pointer Events specification]. Here's some specific notes about the input pointers available in PowerUI.

== Mouse Input ==

PowerUI assumes that only a desktop platform will have a mouse. A [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1MousePointer.html MousePointer] is created when it's running on a desktop and [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a7527e2574ccda7fb7cdd2d8a28fff6db PowerUI.Input.CreateSystemMouse] is true ''(the default)''. If your project doesn't use a mouse pointer on a desktop platform (it's [[Virtual Reality Cameras|virtual reality]] for example), you'd remove it by setting [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a7527e2574ccda7fb7cdd2d8a28fff6db CreateSystemMouse] to false in an Awake method.

== Touch and Stylus Input ==

PowerUI handles multi-touch input by default on any platform which supports it. It will automatically stack with a mouse input on desktops which also have touchscreens. Each time a new touch is detected, a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1FingerPointer.html FingerPointer] or a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1StylusPointer.html StylusPointer] is created. They fire the various [https://developer.mozilla.org/en-US/docs/Web/API/Touch_events touch events] as well as [https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent mouse events].

All pointers are [https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/isPrimary primary] (which means they all fire those mouse events too).

== Virtual Reality ==

PowerUI has a custom input pointer, a [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1CameraPointer.html CameraPointer], for virtual reality. See [[Virtual Reality Cameras|the article]] relating to virtual reality camera's.

== Define your own ==

If you're doing something more specialised then you can also define your own input pointer. Multiple Wii controllers, for example. This is very straight forward to do - at a minimum you must inherit from InputPointer:

<syntaxhighlight lang="csharp">

public class MyCustomPointer : InputPointer{
}

</syntaxhighlight>

Then to use it, all you need to do is create and add it:

<syntaxhighlight lang="csharp">
MyCustomPointer pointer = new MyCustomPointer();
pointer.Add();
</syntaxhighlight>

It can be clicked etc or have a pressure value like any other pointer. To move it around, set the Position property (Top left corner is 0,0):

<syntaxhighlight lang="csharp">
pointer.Position = new Vector2(100,100);
</syntaxhighlight>

Alternatively you can put your position update logic inside the pointer itself by overriding the Relocate method:

<syntaxhighlight lang="csharp">

public class MyCustomPointer : InputPointer{

public override bool Relocate(){

// - Get your latest coordinates here -
Vector2 newPosition = Vector2.zero;

// Try moving it (just returns false if your position wasn't different to the current one):
return TryChangePosition(newPosition);
}

}

</syntaxhighlight>

== Making it click ==

If you've got an input pointer and you'd like to click it (or vary its downward pressure), you can either:

* Use the convenience method for mouse up/down events from OnGUI:

<syntaxhighlight lang="csharp">

void OnGUI(){

// Returns true if your pointer actually did something (it went down or up)
// You can also directly pass a UnityEngine.Event too.
bool didSomething = MyPointer.HandleEvent();

}

</syntaxhighlight>

* Call the MyPointer.Down and MyPointer.Up methods (Optionally specifying a [https://docs.unity3d.com/ScriptReference/Event-button.html mouse button ID]):

<syntaxhighlight lang="csharp">

// Mousedown event, left button:
MyPointer.Down(0);

// Which is also the same as:
MyPointer.LeftDown();

// Mouseup event, left button:
MyPointer.Up(0);

// Which is the same as:
MyPointer.LeftUp();

</syntaxhighlight>

* Use SetPressure directly - this is useful if you've got some kind of stylus ''(every other option is just an abstraction of SetPressure)''

<syntaxhighlight lang="csharp">

void Update(){

// Update the pointer pressure:
MyPointer.SetPressure(someVaryingField);

}

</syntaxhighlight>

== Accessing all pointers ==

PowerUI implements various standard API's for accessing pointers:

* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1TouchEvent.html TouchEvent].touches
* TouchEvent.targetTouches
* TouchEvent.changedTouches
* TouchEvent.identifier
* ''More!''

The non-standard internal ones:

* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1UIEvent.html#a2daa44fbceddd8510bc2791340a432b4 UIEvent.trigger] - ''MouseEvent, TouchEvent etc; The InputPointer instance this event came from''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#a77189cd51fedf33c73759f641c8380ef InputPointer.All] - ''All active pointers (array created on use; Use AllRaw and PointerCount for better performance)''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#a731d759f87ece43622fb497b5e3d88b3 InputPointer.PointerCount] - ''The number of actual pointers in the AllRaw pointer set''
* [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1InputPointer.html#aa76092f569304c8fcf6c3bea1f9612e3 InputPointer.AllRaw] - ''The raw set of pointers. Entries beyond PointerCount are random noise/ undefined.''

== Source locations ==

You'll find the implementations of MousePointer, FingerPointer etc here:

* PowerUI/Source/Engine/Input/

Input Pointers

2017-04-23T17:29:19Z

Bablakeluke:

2017-04-21T02:46:34Z

Bablakeluke: /* Can I run x - How compliant is the JavaScript in PowerUI? */

2017-04-19T05:06:14Z

Bablakeluke:

It's very common to have game world objects which can be clicked/ tapped on. However, if your UI is over one of those objects, you might get something called 'click through' - where both the UI and your game world object handle the click.

== Why click through happens ==

Unity doesn't provide a way to block the built in raycast which occurs when the screen is pressed or the mouse is clicked. Click through happens for Unity's built in GUI too. So, because PowerUI can't block it from happening, both Unity's raycast and PowerUI's element resolve occur at the same time - when both happen to get handled, then the click through scenario arises.

== Avoiding it ==

Unity GUI and older versions of PowerUI have a flag which you check from your MonoBehaviour click methods (like OnMouseDown). Due to a wider variety of events (e.g. the touch events) and as PowerUI fully supports multi-touch (which the flag route fails for), there's now two potential routes - both involve catching the event after they've passed through the UI:

=== Use Input.Unhandled ===

See also the [[Event Flow|event flow]]. This special EventTarget receives all events which were not handled by your UI. If you click 'through' your UI, the mouse/touch events are sent here. Grab them using addEventListener:

<syntaxhighlight lang="csharp">
PowerUI.Input.Unhandled.addEventListener("mousedown",delegate(MouseEvent e){

// They clicked on *nothing!* (straight 'through' the UI).
// Send this event wherever you'd like.
// Note that the original raycast (and any GameObject it hit) are available:
if(e.raySuccess){
// It hit something! Use rayHit next.

// Get the clicked gameObject:
GameObject go = e.rayHit.gameObject;

// Try getting a MonoBehaviour called 'MyInputScript':
MyInputScript myInput = go.GetComponent<MyInputScript>();

if(myInput != null){
// Great - forward the event to it:
myInput.MouseDown(e);
}
}

});
</syntaxhighlight>

PowerUI tries to give your input system as much flexibility as possible, so the above route is considered relatively low level and which allows you to pipe those events wherever you need them, but requires a little more scripting to hook it up.

=== Setup an EventTarget MonoBehaviour ===

This is the easier route, but involves PowerUI defining more of your input system. This also has the advantage of being able to correctly handle 3D [[Context Menu|context menu's]] too. Firstly, tick the "Handle 3D Input" box in '''Window > PowerUI > Input Settings''', then typically all you'll need to do is just add "MouseEvent" to e.g. OnMouseDown. Here's an example:

<syntaxhighlight lang="csharp">

// A MonoBehaviour attached to a GameObject with a collider.
public class MyGameworldEvents : MonoBehaviour{

public void OnMouseDown(MouseEvent e){
// To 'convert' a method, all we've really done is add the MouseEvent parameter.
// That makes it much better at dealing with multitouch too.

// This runs when this gameobject got clicked on
// and the UI was not.

}

}

</syntaxhighlight>

This way you can dispatch any event to any gameObject too:

<syntaxhighlight lang="csharp">

// Create whatever event type you'd like:
MissionEvent e= new MissionEvent("missioncomplete");

// Dispatch it to a gameobject:
aGameObject.dispatchEvent(e);

</syntaxhighlight>

<syntaxhighlight lang="csharp">

// A MonoBehaviour attached to a GameObject with a collider.
public class MyGameworldEvents : MonoBehaviour{

public void OnMissionComplete(MissionEvent e){
// Your method must simply start with 'On' and accept exactly 1 event argument.

// This will receive the above missioncomplete event.
}

}

</syntaxhighlight>

Click through

2017-04-19T05:05:48Z

Bablakeluke: /* Setup an EventTarget MonoBehaviour */

Caret

2017-04-17T19:52:37Z

Bablakeluke:

In PowerUI, the caret seen in both textarea's and input elements is a [[Virtual Elements|virtual <caret> element]]. Its appearance comes from the caret selector in the [[User agent stylesheet|user agent stylesheet]] and it's declared like this:

<syntaxhighlight lang="css">

caret{
/* Other position properties removed from here */
/* This is the most important one: */
border-left:1px solid black;
}

</syntaxhighlight>

Its appearance is defined as a '''black left border'''. We may remove the word 'black' in order to make it always default to the font colour in the future. Black is currently present as the default font colour for the PowerUI main UI is ''white'' and a white caret is often unwanted.

== Styling the caret ==

Often a UI will want to style a caret differently from the text. As it's a caret element, you can simply declare a caret style in your HTML like this:

<syntaxhighlight lang="css">
caret{
/* All of my carets will be blue */
border-color:blue;
}
</syntaxhighlight>

The caret acts as a direct child of your textarea or input field, so you can target specific ones using any ordinary selector too:

<syntaxhighlight lang="css">
textarea caret{
/* Carets in textareas will be red */
border-color:red;
}

input caret{
/* Carets in input fields will be white */
border-color:white;
}

#nameField caret{
/* The caret in an input field with the id 'nameField' will be blue */
border-color:blue;
}
</syntaxhighlight>

You could also use border-width to control the thickness of your caret too.