Difference between revisions of "Custom CSS Property"

Revision as of 21:18, 12 March 2017

Custom CSS properties can be a great way to reuse functionality and extend PowerUI. They're designed to be simple to make, so simple copy and pasting skills or basic coding skills can be all that's required. Let's get started!

A basic property

The most basic CSS property (A C# file) looks like this:

using Css;

// hello-world
public class HelloWorld: CssProperty{
    
    public override string[] GetProperties(){
    
        // One or more names (sometimes prefixed) that your property handles:
        return new string[]{"hello-world"};
        
    }
    
}

At the very least, you must:

• Inherit from an appropriate type of CSS property (it'll almost always be CssProperty that you use)
• Give it one or more CSS property names.
• Give it a class name, which is typically just the main name of the property.
• Optionally put it in the Css.Properties namespace.

Place it somewhere outside the PowerUI folders. This is just incase you update PowerUI, as you won't want to loose your changes. It can go anywhere you find appropriate.

Initial value and inheritance

Typically you'll want to define an initial value (default none) and if your property inherits or not (default no). That's done in the constructor:

// Constructor for the above CSS property
public HelloWorld(){
    
    // Either set it as a Css value:
    // (such as the common 'auto' one, made available as AUTO for convenience)
    // InitialValue=AUTO;
    
    // Or as text:
    InitialValueText="0 50%";
    
    // Does it inherit?
    Inherits=true;
    
}

Aliases

An aliased property is once which updates the internal value of some other set value. For example 'scroll-top' is an alias for scroll[0]. In CSS there are 4 main types:

• Point aliases. property-x and property-y.
• Colour aliases. property-r, property-g, property-b and property-a.
• Square aliases. property-top, property-left, property-bottom, property-right.
• Logical aliases. property-block-start, property-inline-end, property-block-end, property-inline-start.

Note that they alias in the order seen above. I.e. property-b is property[3]. To setup these common aliases:

// Called to setup aliases.
public override void Aliases(){
    
    // Only call the one(s) you actually want
    // (you _could_ call them all, but it would probably be confusing!)
    
    // Point (x,y):
    // PointAliases2D();
    
    // Point (x,y,z):
    // PointAliases3D();
    
    // Colour:
    // ColourAliases();
    
    // Square (top,left,bottom,right) *and* logical:
    // SquareAliases();
    
    // Something else - see below for more!
    Alias("some-random-css-property",ValueAxis.None,0);
}

Above we're also mapping 'some-random-css-property' to the 0th index of 'this' property (the one that -x, -top, -r etc also map to). You also specify which axis it uses too - that's important for resolving %.

For example, text-indent is an alias of padding-left. If you used a % in text-indent, you would expect it to be a % of the width (the x or horizontal axis).

Composite Properties

Composite properties set multiple CSS properties all at once. background, border, animation etc are all examples of composite properties. In this case, you derive from CssCompositeProperty instead, and either define the specification or manually parse your value.

using Css;

// hello-composition basics (using a spec)
public class HelloComposition : CssCompositeProperty{
   
    // GetProperties is the same:
    public override string[] GetProperties(){
        return new string[]{"hello-composition"};
    }
    
    // Define the specification:
    protected override Spec.Value GetSpecification(){
        
        // Todo! See text-decoration as a nice example.
        
    }
    
}

Knowing when the computed value of your property changed

Whenever a CSS property is recomputed, it fires the Apply method:

public override ApplyState Apply(ComputedStyle style,Value value){
    
    // This property has changed on the given computed style!
    // Properties that render things add or remove a Renderer to the renderable data.
    // Take a look at the background-color property for example.
    
    // Unless you're caching the value as something else, 
    // you'll almost always just return Ok:
    return ApplyState.Ok;
}

Finding built-in properties

Currently there are 3 major groups of CSS properties in PowerUI:

• Core - Path/To/PowerUI/Spark/Properties
• SVG extensions - Path/To/PowerUI/Source/SVG/Css Properties
• MathML extensions - Path/To/PowerUI/Source/Extras/MathML/Css Properties

Checking your property is available

An easy sanity check is to make sure your new property is being correctly detected by PowerUI. To do that:

• Go to Window > PowerUI > Supported CSS
• Look for e.g. your-property-name

If PowerUI is successfully detecting your property, it will be visible on this list.