AppoMobi.Maui.DrawnUi 1.0.1.5-pre

AppoMobi.Maui.DrawnUi

Rendering engine for .Net MAUI to draw your UI on a skia canvas, with gestures and animations, from games to business apps.

Supports iOS, MacCatalyst, Android, Windows.

The current development state is PRE-ALPHA, many features remain to be implemented, the project is active.

This readme is heavily under construction, a lot of properties and use cases are not documented.

What's new

• SkiaCarousel
• SkiaDrawer
• Scrolling and other bug fixes

Development Notes

To notice:

• Expect this repo to be updated very often and breaking changes to occure
• Expect fps in minimum to double in Release builds (on Windows the lib fps in manually flex-capped at 200).
• In the demo app you can return to root view inside same tab on reselecting its icon (the Fun screen has no GoBack button)

Maui limitations:

• Xaml Hot-Reload revealed itsself not working for views added dynamically at runtime, despite using VisualDiagnostics.OnChildAdded, need to investigate.
• Code-behind HotReload not working when changing code for controls and demo running.

Known Bugs:

• Padding not working inside label
• Aligned to End layout wrong calculation of width for type Column
• SkiaMauiElement is living his own life, maui elements are not working in a stable way.
• Margins and Padding are overall working okay but in same rare cases they contract the size of the element event when there is plenty of space around.

ToDo:

• SkiaEditor is just started, need to add a scroll inside, handle more stuff, add attachable text filters etc.
• Re-enable zoom gesture for SkiaScroll and add a demo, was ok (except for windows) but was disabled while working on templated cells.
• Restore the case dynamic templates for a skia scroll (was disabled at some time) and provide a demo in a form of chat messages recycled scroll
• SkiaSlider, basically have everything ready for it from other projects
• Rewrite the WheelPicker scroll calculations to so when scroll starts it already targets the perfect end cell position without snapping being needed after.
• Bind Rive Android+iOS, it's working fine on Windows, could be awesome for creating games.
• After reworking Snap from scrollTo to Bounce create SkiaCarousel.
• Add support for Minimim and Maximum size requests options for layout.
• Create drawer animator for many cases, add demos after that.
• SkiaGrid requires definitions to be set by dev to work, need to generate defaults if not set, corresponding to added views.
• Need to rework WheelPicker to add 3d transforms props for an intuitive use.
• FastShell used in Demo was coded to be used for Maui views, so need rework it to make compatible with drawn ui.
• Add header and footer for templated SkiaLayout
• Add options for fullscreen, have them ready for maui need just need to inject to drawn ui.
• Add diagnostic helper to dump visual trees especially animators.
• Add retry mechanics to image loader
• Recenter repeating code in some helper that would read app resources and web urls.
• Will add separate example for using drawn ui in a normal maui app as canvases here and there.
• Will add more animated tabs controls to with visual the looks of best flutter tabs plugins
• Etc etc..

Features

• Draw your UI using SkiaSharp with hardware acceleration

• Easily create your controls and animations

• Design in Xaml or code-behind

• 2D and 3D Transforms

• Animations targeting max fps

• Gestures support for panning, scrolling and zooming (rotation incoming)

• Caching system for elements and images

• Optimized for performance, rendering only visible elements, recycling templates etc

• Prebuilt Basic Ui Elements

  • SkiaShape (Rounded rectangle, Circle, Gauge, more to come) can wrap other elements
  • SkiaLabel, multiline with many options
  • SkiaImage with options and filters
  • SkiaSvg with many options
  • SkiaLottie with tint customization
  • SkiaRive (todo ios and android)
  • SkiaLayout (Absolute, Grid, Vertical stack, Horizontal stack, todo Masonry) with templates support
  • SkiaScroll (Horizonal, Vertical, Both) with zoom support and adjustable inertia, bounce, snap and much more (todo header, footer)
  • SkiaScroll + SkiaLayout = CollectionView-like control with refresh, custom refresh indicator, load more etc
  • SkiaHotspot to handle gestures in a easy way
  • SkiaMauiElement for when skia is not enough

• Derived custom controls

  • SkiaButton include anything inside, text, images etc
  • SkiaScrollLooped for neverending scrolls
  • SkiaDrawer to swipe in and out your controls
  • SkiaCarousel swipe and slide controls inside a carousel
  • SkiaEditor we can type over canvas too
  • SkiaCursor to blink where you type
  • SkiaHoverMask to overlay a clipping shape
  • SkiaLabelFps for developement
  • SkiaDecoratedGrid to draw shapes between rows and columns
  • ScrollPickerWheel for creating wheel pickers
  • RefreshIndicator can use lottie and anything for your scroll refresh view
  • SkiaTabsSelector create top and bottom tabs
  • SkiaViewSwitcher switch your views, pop, push and slide
  • Create your own!

• Animated Effects

  • Ripple
  • Shimmer
  • BlinkColors
  • (todo Pulse)
  • Commit yours!

• Animators

  • _todo add info

• Transforms

  • TranslationX
  • TranslationY
  • ScaleX
  • ScaleY
  • Rotation
  • CameraAngleX
  • CameraAngleY
  • CameraAngleZ
  • SkewX
  • SkewY
  • Perspective1
  • Perspective2

Demo App

todo add more tabs animations, chat example, complex scroll example (aliexpress, auchan), 2d game example (checkers, arkanoid)

Installation

Install the package AppoMobi.Maui.DrawnUi from NuGet.

After that initialize the library inside your MauiProgram.cs file:

builder.UseDrawnUi<App>();

Quick Start

You will be mainly using Maui view Canvas that will wrap your SkiaControls. Anywhere in your existing Maui app you can include a Canvas and start drawing your UI. The Canvas control is aware of its children size and will resize accordingly. At the same time you could set a fixed size for the Canvas and its children will adapt to it.

Xaml

Import the namespace:

  xmlns:draw="http://schemas.appomobi.com/drawnUi/2023/draw"

Consume:

<draw:Canvas>
     <draw:SkiaSvg
        Source="Svg/dotnet_bot.svg"
        LockRatio="1"
		HorizontalOptions="Center"
        TintColor="White"
        WidthRequest="44" />
</draw:Canvas>

As you can see in this example the Maui view Canvas will adapt it's size to drawn content and should take 44x44 pts.

Code behind

	_todo_

Please check the demo app, it contains many examples of usage.

todo put important explanation about caching again

Gestures

To make your root Canvas catch gestures you need to attach a TouchEffect to it. After that skia controls can process gestures in multiple ways:

• Implementing an ISkiaGestureListener interface and overriding OnGestureReceived.
• Attaching a HandleGestures effect that has properties similar SkiaHotspot.
• Including a SkiaHotspot as a child.
• Using a SkiaButton.

todo give examples

Caching System

Controls Rendering Result

todo

Caching is set using a property UseCache of the following type:

/// <summary>
/// Usage of cache requires IsClippedToBounds to be true
/// </summary>
public enum SkiaCacheType
{
	None,

	/// <summary>
	/// Create and reuse SKPicture,
	/// </summary>
	Operations,

	/// <summary>
	/// The cached surface will use the same graphic context as your canvas
	/// </summary>
	Bitmap
}

You should tweak your design caching to avoid unnecessary re-drawing of elements. The basic approach here is to cache small elements at some level. For example you would cache small children like cells inside a SkiaScroll as Bitmap. At the same time avoid using bitmaps where just Operations type is enough, for example for SkiaSvg results.

When you start using any kind of animations you should start using caching to max your FPS. You can check the DemoApp for such examples.

Loaded Images

We are using the EasyCaching.InMemory library for caching loaded bitmaps. It's impact can much be seen when using recycled cells inside a scroll. todo add options and link to ImageLoader and SkiaImage docs

Transforms

todo

• TranslationX
• TranslationY
• ScaleX
• ScaleY
• Rotation
• CameraAngleX
• CameraAngleY
• CameraAngleZ
• SkewX
• SkewY
• Perspective1
• Perspective2

Animations

todo

One would create animations and effects using animators. Animators are attached to controls, but technically register themselves at the root canvas level and their code is executed on every rendering frame. If the canvas is not redrawing then animators will not be executed. When the canvas has a registered animator running it would constantly force re-drawing itsself until all animators are stopped.

There are two types of animators:

• Animators are executed before the drawing, so you can move and transform elements before the are rendered on the canvas.
• PostAnimators are executed after their parent element was drawn, so you can paint an effect over the existing result, or execute any other post-drawing logic.

Hint: If you need to create a game loop you could put its code inside an animator and attach the animator with the root element as parent.

todo restore from deleted another way of running a game loop that was not redrawing canvas on every tick

Layout

For initial items positionning you would be using SkiaLayout. Its Absolute layout type is already buil-it in every skia control..

You can position your children using familiar properties like HorizonalOptions, VerticalOptions, Margin, parent Padding, WidthRequest, HeightRequest,MinimumWidthRequest, MinimumHeightRequest and additional MaximumWidthRequest, MaximumHeightRequest and LockRatio properties.

For dynamic positionning or other precise cases use TranslationX and TranslationY.

Whn you need to layout children in a more arranged way you will want to wrap them with a SkiaLayout of different LayoutType : Grid, Colum, Row and others.

Layout supports ItemTemplate for most of layout types.

Enhanced usage

When dealing with subviews in code behind you could typically use two ways.

Example for adding a subview:

• set subview property Parent to the new parent. In this case parent layout will not be invalidated, use this for optimized logic when you know what you are doing. You can mainly use this way when just constructing parent, knowing it will be measured at start anyway.
• call parent's method AddSubView passing subview.Parent's layout will be invalidated, and OnChildAdded will be called on parent. For removing a subview the usual options would be:
• set subview property Paren t to null, for soft removal.
• call parent's method RemoveSubView passing subview. Parent's layout will be invalidated, and OnChildRemoved will be called on parent.

In Deep

When XAML would be constructed it would fill SubViews property with views, this property is for high-level access. Views

Will be then filled internally. When you add or remove items in SubViews methods AddSubView and RemoveSubView will be called for managing Views.

Enhanced Usage

Styles

When you want to dynamically change properties in Xaml you might want to use conditional styles. They look like regular Maui styles, but with some nuances:

• When defining style is resources you must set a unique Class attibute
• They are selected at runtime upon Condition or State bindable properties. State is like Maui VisualStatebut you can have several of them applied at same time.

Define a style inside ResourceDictionary:

    <Style
        x:Key="SkiaLabelDefaultStyle"
        Class="SkiaLabelDefaultStyle"
        TargetType="draw:SkiaLabel">
        <Setter Property="TextColor" Value="#E8E3D7" />
        <Setter Property="FontFamily" Value="FontText" />
        <Setter Property="FontSize" Value="15" />
    </Style>

Apply a style:

<draw:SkiaLabel
    Style="{StaticResource SkiaLabelStyle}"
    Text="Simple Styled Label" />

Apply styles upon conditions:

   <views:SkiaShape
    LockRatio="1"
    Type="Circle"
    WidthRequest="16">
    <views:SkiaControl.Styles>
        <views:ConditionalStyle
            State="Normal"
            Style="{x:StaticResource StyleCameraDot}" />
        <views:ConditionalStyle
            Condition="{Binding .}"
            Style="{x:StaticResource StyleCameraDotOn}" />
    </views:SkiaControl.Styles>

</views:SkiaShape>

Same as:

   <views:SkiaShape
    Style="{StaticResource StyleCameraDot}"
    LockRatio="1"
    Type="Circle"
    WidthRequest="16">
    <views:SkiaControl.Styles>
        <views:ConditionalStyle
            Condition="{Binding .}"
            Style="{x:StaticResource StyleCameraDotOn}" />
    </views:SkiaControl.Styles>

</views:SkiaShape>

When the BindingContext (x:Boolean) is True the style StyleCameraDotOn will be applied, otherwise StyleCameraDot will be applied.

To apply styles upon states you will be using standart Maui VisualStates mechanism, or you can even have serveral states at the same time, every SkiaControl has a string[] States bindable property to server this purpose:

   <views:SkiaShape
    States="{Binding VisualStates}"
	LockRatio="1"
	Type="Circle"
	WidthRequest="16">
	<views:SkiaControl.Styles>
		<views:ConditionalStyle
			State="Normal"
			Style="{x:StaticResource StyleCameraDot}" />
		<views:ConditionalStyle
			State="IsOn"
			Style="{x:StaticResource StyleCameraDotOn}" />
	</views:SkiaControl.Styles>

Hints

todo

For SkiaStack of type Row or Column avoid using Fill for children ?? that would require a second measurement pass.

Models

SkiaControl

Base element.

Properties:

LockRatio a numeric value that will be used to calculate the width when the height is set or vice versa. If it's above 0 the max value will be applied, if it's below 0 the min value will be applied. If it's 0 then the ratio will be ignored.

Example 1:

  <draw:SkiaShape
                        LockRatio="1"
                        WidthRequest="40" />

HeightRequest wasn't specified but this control will request 40 by 40 pts.

Example 2:

  <draw:SkiaShape
	LockRatio="-1"
	HeightRequest="30"
	WidthRequest="40" />

This control will request 30 by 30 pts.

SkiaScroll

SkiaScroll is a scrollable container that supports virtualization and recycling of its children.

If you include a SkiaLayout inside a SkiaScroll only visible on screen items will be rendered.

If the include a SkiaLayout that uses ItemTemplate this combination will automatically become virtualized and you will get sort of a CollectionView with recycled cells at your disposal. It is a good practice to use it for long lists of items.

SkiaLayout

SkiaLayout is a container that supports various layout types: Absolute, Grid, Row, Column and others.

It also supports virtualization and recycling of its children with ItemTemplate property.

SkiaShape

SkiaShape is a base class for all shapes. You could fill it, stroke, drop shadows, apply gradients and even clip other controls with it.

SkiaImage

SkiaImage is a control that renders images. It cant apply filters and transformations.

SkiaSvg

SkiaSvg is a control that renders svg files. It cant tint the svg with a color or gradient, and apply some transforms to it.

SkiaLabel

A multi-line label fighting for his place under the sun.

Properties:

FontWeight a numeric value used in case you have properly registered your fonts to support weights. You can use your font the usual Maui way but in case of custom font files used from resources you might want to register them, using the following example:

.ConfigureFonts(fonts =>
{
   fonts.AddFont("Gilroy-Regular.ttf", "FontText", FontWeight.Regular);
   fonts.AddFont("Gilroy-Medium.ttf", "FontText", FontWeight.Medium);
});

Now if you set the FontWeight to 500 the control will use the Gilroy-Medium.ttf file. This might come very handy when your Figma design shows you to use this weight and you want just to pass it over to SkiaLabel.

HorizontalTextAlignment :

public enum DrawTextAlignment
{
	Start,
	Center,
	End,
	FillWords,
	FillWordsFull,
	FillCharacters,
	FillCharactersFull,
}

SkiaLottie

SkiaLottie is a control that renders lottie files. It can even tint some colors inside your animation!

SkiaRive

Actually for Windows only, this plays and controls Rive animation files. Other platforms will be added soon, poke if you would like to help biding some c++;

SkiaDrawer

A drawer is a container that can be opened and closed. It is a subclassed SnappingLayout:SkiaLayout.

It you want to host a ScrollView inside, this one must have Bounces set to false to pass scrolling gestures to drawer at scrolling edges.

Events:

IsOpenChanged Event that will be fired when the open state changes.

Scrolling For when it's scrolling..

Scrolled Scrolling finished.

Properties:

IsOpen Two-way bindable boolean property that controls the drawer state.

InTransition Read-only boolean, to know if transition animation is in progress.

HeaderSize Size in pts (double) of the area the will be visible on screen when drawer is closed.

Direction Type is DrawerDirection:

public enum DrawerDirection
{
   FromBottom,
   FromTop,
   FromLeft,
   FromRight
}

You will still be responsible to set appropriate layout options for every case, like VerticalOptions="End" for FromBottom direction.

Bounces Boolean, rubber effect on bounds

SkiaCarousel

To use as slider or carousel.

Subclassed SnappingLayout : SkiaLayout.

Needs self dimensions to be set or to use Fill, will not adapt to content size. Can use ItemTemplate or directly included children controls, in this last case will auto-set children size to self size. If you use ItemTemplate please set it to Fill the container. Using direct controls instead of ItemTemplate is useful for small number of items when you need to have totally different designs for each cell.

Events:

SelectedIndexChanged: Event fired when the selected index changes.

OnLayoutReady: Event fired when the layout is ready.

OnTransitionChanged: Event fired when a transition state changes.

ItemAppearing: Event fired when an item is appearing.

ItemDisappearing: Event fired when an item is disappearing.

Scrolled: Event fired when scrolling is finished.

Scrolling: Event fired when scrolling is in progress.

Properties:

SelectedIndex Two-way bindable integer property that speaks for itsself.

SidesOffset As title, for when you want to see neighboor items at sides, default is 0.

InTransition: A Boolean property indicating whether the layout is in a transition state.

IsVertical: A Boolean property that defines whether the carousel scrolls vertically; false by default.

IsRightToLeft: A Boolean property that indicates whether the carousel direction is right-to-left; false by default.

LayoutReady: A Boolean property indicating whether the layout is ready.

Bounces: A Boolean property indicating whether the layout has a bounce effect at its edges.

RubberEffect: A double property representing the strength of the rubber band effect at sides when Bounces is True.