Custom CSS Property - Revision history

188.222.158.94 at 21:58, 12 March 2017

2017-03-12T21:58:18Z

188.222.158.94: /* Formal Syntax and specifications */

2017-03-12T21:48:11Z

‎Formal Syntax and specifications

188.222.158.94 at 21:44, 12 March 2017

2017-03-12T21:44:46Z

188.222.158.94: /* Composite Properties */

2017-03-12T21:43:37Z

‎Composite Properties

188.222.158.94: /* Aliases */

2017-03-12T21:23:57Z

‎Aliases

188.222.158.94: /* Initial value and inheritance */

2017-03-12T21:18:44Z

‎Initial value and inheritance

188.222.158.94 at 20:16, 12 March 2017

2017-03-12T20:16:39Z

188.222.158.94: /* A basic property */

2017-03-12T19:51:26Z

‎A basic property

188.222.158.94 at 19:48, 12 March 2017

2017-03-12T19:48:50Z

188.222.158.94: Created page with "TODO!"

2017-03-12T19:39:41Z

Created page with "TODO!"

New page

TODO!

← Older revision		Revision as of 21:58, 12 March 2017
Line 54:		Line 54:

	</syntaxhighlight>		</syntaxhighlight>
		+
		+	== A normal value ==
		+
		+	If you'd like your property to accept the 'normal' keyword then you'd override '''GetNormalValue'''. It's 0 by default.

	== Aliases ==		== Aliases ==

@@ Line 158: / Line 158: @@
 ! Class to use
 |-
-| a || b
+| a &#124;&#124; b
 | Spec.AnyOf
 |-
@@ Line 170: / Line 170: @@
 | Spec.Optional
 |-
-| a | b
+| a &#124; b
 | Spec.OneOf
 |-
@@ Line 192: / Line 192: @@
 |}
-Declaring a specification is generally convenient as that's how they're actually defined. However, if you want to parse the value in a custom way (there are a few properties which can't be defined using the web specification format), use '''OnReadValue'' instead. ''animation'' is an example of a CSS property that does that.
+Declaring a specification is generally convenient as that's how they're actually defined. However, if you want to parse the value in a custom way (there are a few properties which can't be defined using the web specification format), use '''OnReadValue''' instead. ''animation'' is an example of a CSS property that does that.
 == Knowing when the computed value of your property changed ==

@@ Line 145: / Line 145: @@
 Simple composite example: text-decoration (and the two properties it references)
 Complex composite example: font
 == Knowing when the computed value of your property changed ==

@@ Line 105: / Line 105: @@
 == 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.
+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 formal syntax as a ''specification'' or manually parse your value.
 <syntaxhighlight lang="csharp">
@@ Line 122: / Line 124: @@
      protected override Spec.Value GetSpecification(){
-         // Todo! See text-decoration as a nice example.
+         // Let's define the composite formal syntax as this:
+     }
@@ Line 130: / Line 141: @@
 </syntaxhighlight>
 == Knowing when the computed value of your property changed ==

@@ Line 94: / Line 94: @@
 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).
+For example, text-indent is an alias of padding[3] (the same as padding-left). If you used a % in text-indent, you would expect it to be ''a % of the width'' (the x or horizontal axis). To make that real, take a look at padding.cs where you'll see this:
 == Composite Properties ==

@@ Line 46: / Line 46: @@
      // Or as text:
-     InitialValueText="hello-keyword";
+     InitialValueText="0 50%";
      // Does it inherit?

← Older revision		Revision as of 20:16, 12 March 2017
Line 31:		Line 31:

	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.		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:
		+
		+	<syntaxhighlight lang="csharp">
		+
		+	// 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="hello-keyword";
		+
		+	// Does it inherit?
		+	Inherits=true;
		+
		+	}
		+
		+	</syntaxhighlight>
		+
		+	== 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:
		+
		+	<syntaxhighlight lang="csharp">
		+
		+	// 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);
		+	}
		+
		+	</syntaxhighlight>
		+
		+	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.
		+
		+	<syntaxhighlight lang="csharp">
		+
		+	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.
		+
		+	}
		+
		+	}
		+
		+	</syntaxhighlight>
		+
		+

	== Knowing when the computed value of your property changed ==		== Knowing when the computed value of your property changed ==

@@ Line 7: / Line 7: @@
 <syntaxhighlight lang="csharp">
 using Css;
@@ Line 26: / Line 25: @@
 At the very least, you must:
-* Inherit from an appropriate type of element (it'll almost always be HtmlElement that you use)
+* Inherit from an appropriate type of CSS property (it'll almost always be CssProperty that you use)
-* Give it a tag name
+* Give it one or more CSS property names.
-* Give it a class name, which is typically of the form Html''TagName''Element
+* Give it a class name, which is typically just the main name of the property.
 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.

← Older revision		Revision as of 19:48, 12 March 2017
Line 1:		Line 1:
−	~~TODO~~!	+	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:
		+
		+	<syntaxhighlight lang="csharp">
		+
		+	using PowerUI;
		+	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"};
		+
		+	}
		+
		+	}
		+
		+	</syntaxhighlight>
		+
		+	At the very least, you must:
		+
		+	* Inherit from an appropriate type of element (it'll almost always be HtmlElement that you use)
		+	* Give it a tag name
		+	* Give it a class name, which is typically of the form Html''TagName''Element
		+
		+	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.
		+
		+	== Knowing when the computed value of your property changed ==
		+
		+	Whenever a CSS property is recomputed, it fires the '''Apply''' method:
		+
		+	<syntaxhighlight lang="csharp">
		+
		+	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;
		+	}
		+
		+	</syntaxhighlight>
		+
		+	== 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.