Difference between revisions of "Upgrading to PowerUI 2"

Revision as of 23:44, 15 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 change, 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");

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

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.