Kostom.net

Responsive Base Element


Whirl USS-Framework includes a powerful internal system called the ResponsiveBaseEngine. This engine is responsible for all responsive behavior in Whirl, including:
  • Media Queries (sm:…, md:…, lg:…, etc.)
  • Orientative Classes (pt:…, ls:…)
  • Any custom responsive features created by the user (e.g., custom rules, gap systems, size-based switches, etc.)

Unity does not support some native CSS features, so Whirl implements responsiveness entirely in C#, using a flexible extension system built around an abstract base class.

Note: It's important that you use <element>.AddClass(...,...) and <element>.RemoveClass(...,...) to add/remove utility class from an element, also use <element>.AddChild(...,...) or <element>.RemoveChild(...,...) to add/remove a child element to the visual root tree, or else the ResponsiveBaseElement would not recognize the element.

How to Use Responsive Base Element

  • Custom ResponsiveBaseElement:
    ResponsiveBaseElement is based on ScriptableObject, which means that you can create a custom one by inheriting from ResponsiveBaseElement. After creating it, create an instance in the asset folder and attach it to the ResponsiveBaseElements section on the WhirlCompilerSettings you want it to affect. This would automatically be detected whenever the WhirlCompilerSettings is used.

  • Runtime:
    Attach the WhirlManager script to your scene, add the Themes (default + overrides) and your WhirlCompilerSettings to it.

  • Editor:
    On any VisualElement that's attached to the root, you can call `<element> .InitializeResponsive(...)`, this method takes a WhirlCompilerSettings, and it only needs to be called on any element once. Check the example below.

void Create() {
    WhirlCompilerSettings settings = GetWhirlSettings();
    var element = new VisualElement();
    .....
    root.Add(element);

    // element is attached to the root
    element.InitializeResponsive(settings);
    
    // or this way
    root.InitializeResponsive(settings);
}

WhirlCompilerSettings GetWhirlSettings() {
    ....
}

Creating Custom Responsive Features

Anyone can add an unsupported feature that work exactly like built-in features such as breakpoints and orientation. To do this, simply create a new class that extends ResponsiveBaseElement and implement the desired behavior inside it.

The ResponsiveBaseElement is ScriptableObject-based, which means that you should create an instance of the ScriptableObject in your project if you want the editor windows to automatically detect and use it, but you need to add it to your WhirlManager for runtime use.

Example:
using UnityEngine.UIElements;
using Kostom.WhirlUSS;
public class CustomResponsiveElement : ResponsiveBaseElement

Here's the content inside ResponsiveBaseElement:

// this is the class that is responsible for the
// ResponsiveBaseElements, it’s responsible for the lifetime of
// VisualElements and it’s only one instance per document
public ResponsiveStyleSheet? responsiveStyleSheet  { get; internal set; }

// defines if a class is compatible with this ResponsiveBaseElement
public abstract bool CheckCompatibility(string @class);

// this method is called when the matching element no longer fits the criteria
public abstract void Reset(VisualElement element)

// this method is called the first time an element fits the
// criteria even if it already exists in the document
public abstract void Initialize(VisualElement element)

// this method is called to check if an element can be removed
// this is meant to manage space and performance
public abstract bool CanRemoveElement(VisualElement element)

// this method is called when a class is added to a VisualElement that
// already fits the criteria of the class using .AddClass(..)
public virtual void OnClassAdded(VisualElement element, string @class) { }

// this method is called when a class is removed from a VisualElement that
// still fits the criteria using .RemoveClass(..);
// this is called before CanRemoveElement(..) method;
public virtual void OnClassRemoved(VisualElement element, string @class) { }

// this method is called to get all compatible classes for a VisualElement with the right symbols
// e.g : instead of ---;
public List<string>? GetCompatibleClasses(VisualElement element)

// this method is called to get the root VisualElement used by the responsive class
public VisualElement? GetRootElement(VisualElement element)

This is also used to create the Media Query, Orientative Query and Gap system.