Difference between revisions of "Upgrading to PowerUI 2"

Revision as of 03:39, 18 February 2017

PowerUI 2 includes a completely new CSS engine, vast new visual effects and a broad focus on standards compliance. It has been in development for over a year so there are a lot of things that you'll need to be aware of when upgrading a project from earlier versions of PowerUI.

Check out the new example scenes

Most of the example scenes have changed, and there's many new ones in there displaying some of the new features too.

Slow compile times? Precompile PowerUI

PowerUI 2 has considerably more code than before - each time you update any C# file, it will all get recompiled. If you're getting long compile times, precompile PowerUI by going to Window -> PowerUI -> Precompile. You no longer need to include your custom PowerUI extensions in this either, so you can continue to add custom tags etc without needing to recompile.

The DOM (Element -> HtmlElement)

PowerUI now has a standards compliant DOM. That means API's like getElementById return a Dom.Element object when what you probably want is a HtmlElement - HtmlElement has things like style. That would likely result in a lot of casting:

// 1.9:
Element ele=aDocument.getElementById("hello");

// 2.0:
HtmlElement ele=aDocument.getElementById("hello") as HtmlElement;

So instead, use the new convenience methods. That article also describes why this is required too:

// 1.9:
Element ele=aDocument.getElementById("hello");

// 2.0:
HtmlElement ele=aDocument.getById("hello");

Nitro has been depreciated

The version of Nitro currently in PowerUI 2 is getting replaced with an entirely new engine (called Nitrassic - it's Jurassic combined with Nitro's performance, flexibility and ability to be precompiled). In the meantime though, the older Nitro engine is unsupported (and has been for a little while) so you should expect it to pose a challenge if you are porting larger volumes of Nitro.

On the whole most people don't use Nitro anyway so this 'gap' isn't expected to be too much of an issue. The update was phased like this to hopefully make it easier to update from earlier versions to 2 in steps as new Nitro is almost entirely ECMAScript compliant ('real Javascript') - it's case sensitive, for example. However, it brings us a big step closer to supporting major libraries like jQuery inside Unity, as well as saying hello to a much nicer scripting environment (bye bye to those occasional cryptic errors!)

Events - upgrading your event handlers

PowerUI now entirely follows W3C events. That means there's now a wide range of new event objects, like KeyboardEvent, which you'll receive instead of the previous "UIEvent" object.

For example, keydown receives a KeyboardEvent. mousemove receives a MouseEvent.

You'll find the name of the correct event to use in the MDN event reference.

PowerUI 1.9:

anElement.onmousedown=delegate(UIEvent e){
 // runs when the element was clicked
};

public static void MyKeyboardHandler(UIEvent e){
 // used by e.g. onkeydown="MyClass.MyKeyboardHandler"
}

PowerUI 2:

anElement.onmousedown=delegate(MouseEvent e){
 // runs when the element was clicked
};


public static void MyKeyboardHandler(KeyboardEvent e){
 // used by e.g. onkeydown="MyClass.MyKeyboardHandler"
}

So, broadly, you ctrl+f for UIEvent and swap the name for the appropriate event.

Forms

Form events were made consistent. Both onsubmit and the custom ondone methods now receive a FormEvent (which is FormData renamed). Make sure you rename FormData.

Custom Elements (TagHandler)

PowerUI now has a compliant HTML5 parser, without sacrificing speed or flexibility. That meant that there were changes to the way how these work.

If you have any custom tags - that's any custom classes that derived from HtmlTagHandler - you'll need to slightly restructure them to the newer, simpler format:

// 1.9:
public class MyNewTag : HtmlTagHandler{
    
    // Relocated
    public override string GetTags(){
        return new string[]{"mytag"};
    }

    // Totally removed this:
    public override Wrench.TagHandler GetInstance(){
        return new MyNewTag();
    }
}

// 2.0:

[Dom.TagName("mytag")]
public class MyNewTag : HtmlElement{
    
}

Button

The button element was long known for its quirky behaviour. It's now standards compliant.

Default styles

The user agent stylesheet was renamed to xhtml-style.html and is in the same location as before, when it was called style.html - Path/To/PowerUI/Resources/xhtml-style.html. It contains all of the core style for elements, including the default style for scrollbars etc.

The stylesheet has changed considerably between 1.9 and 2.0. Some common examples:

• html and body no longer default to a height of 100%.

• body now has the standard 8px margin.

• All input elements were restyled to use a more generic colour scheme by default.

Using the 1.9 stylesheet won't work as a quick fix. This is because elements like table now entirely define their behaviour through CSS, so swapping out the stylesheet would result in random missing selectors (such as the one which declares 'table' as using 'display:table;', for example - that wasn't in 1.9).