README

FMX.UIOverlayLoader

Simple and customizable Delphi/FMX component for displaying a loading overlay. You can use it to prevent the user from interacting with the UI when making API calls or running any long-running asynchronous task. Everything is handled at runtime, so there's no need to add any extra views or components at design time.

✨Features

• Pure FMX & Skia: Built with 100% FMX code and rendered using the powerful components Skia4Delphi for high-quality, cross-platform graphics.
• Vector-Based Spinner: Uses SVG for the spinner icon instead of a bitmap image. This results in a smaller component footprint and perfectly crisp visuals on any screen resolution.
• Highly Customizable: Easily change the overlay's background color, opacity, spinner color, stroke color, corner radius, and more.
• Predefined & Custom Spinners: Includes several built-in spinner styles and allows you to load your own custom SVG spinner from a file.
• Runtime Implementation: No need to clutter your form design. The overlay is created and managed entirely through code.
• Customizable Animations: Control the spinner's animation style (e.g., Linear, Bounce, Elastic) and velocity.
• Z-Order Support: Properly handles display over native controls using the ControlType property.

🚀Getting Started

Follow these steps to integrate TUIOverlayLoader into your FMX project.

Prerequisites

You must have the Skia4Delphi library installed in your RAD Studio environment.

Integration

1. Add the FMX.UIOverlayLoader.pas unit to your project's search path.
2. Include the unit in the uses clause of the form where you want to display the OverlayLoader.
3. Declare a TUIOverlayLoader object variable in your form's private section.
4. In your form's OnCreate event, create an instance of the loader. Remember to free it in the OnDestroy event.
5. Use the SetOverloadingForm method to specify which form the overlay should cover. This is mandatory and must be called before Show.

Basic Usage

Here is a minimal example of how to use the component.

uses
  FMX.UIOverlayLoader;

type
  TMyForm = class(TForm)
    ButtonShow: TButton;
    procedure ButtonShowClick(Sender: TObject);
    procedure FormCreate(Sender: TObject);
    procedure FormDestroy(Sender: TObject);
  private
    { Private declarations }
    FLoader: TUIOverlayLoader;
  public
    { Public declarations }
  end;

//...

procedure TMyForm.FormCreate(Sender: TObject);
begin
  FLoader := TUIOverlayLoader.Create(Self);
  FLoader.SetOverloadingForm(Self);
end;

procedure TMyForm.FormDestroy(Sender: TObject);
begin
  FLoader.Free;
end;

procedure TMyForm.ButtonShowClick(Sender: TObject);
begin
  // Show the loader
  FLoader.Show;

  // Simulate a long-running task
  TTask.Run(procedure
    begin
      Sleep(3000); 
      TThread.Synchronize(nil, procedure
      begin
        FLoader.Hide;
      end);
    end);
end;

🎨Customization & Examples

You can customize almost every visual aspect of the loader at runtime.

Change Colors and Opacity

Adjust the background and spinner colors to match your application's theme.

procedure TMyForm.FormCreate(Sender: TObject);
begin
  FLoader := TUIOverlayLoader.Create(Self);
  FLoader.SetOverloadingForm(Self);

  // Customize the overlay background
  FLoader.BackgroundColor := TAlphaColors.Lightgoldenrodyellow;
  FLoader.BackgroundOpacity := 0.5;

  // Customize the spinner colors (using a predefined model)
  FLoader.SpinnerType := TSpinnerType.stModel1;
  FLoader.SpinnerColor := TAlphaColors.Steelblue; // Affects the 'fill' attribute in the SVG
  FLoader.SpinnerStrokeColor := TAlphaColors.Red; // Affects the 'stroke' attribute in the SVG
end;

Use a Custom Size

Set SpinnerSize to ssCustom to define a specific width and height for the spinner. Otherwise, it will use the predefined dimensions (e.g., ssSmall is 48x48).

procedure TMyForm.FormCreate(Sender: TObject);
begin
  FLoader := TUIOverlayLoader.Create(Self);
  FLoader.SetOverloadingForm(Self);

  FLoader.SpinnerSize := TSpinnerSize.ssCustom;
  FLoader.SpinnerWidth := 100;
  FLoader.SpinnerHeight := 100;
end;

Load a Custom SVG Spinner

Use the LoadFromFile method to replace the default spinner with your own SVG icon.

procedure TMyForm.FormCreate(Sender: TObject);
begin
  FLoader := TUIOverlayLoader.Create(Self);
  FLoader.SetOverloadingForm(Self);

  // This will automatically set SpinnerType to stCustom
  FLoader.LoadFromFile('\Path\To\Your\custom-spinner.svg');

  // You can still customize its color
  FLoader.SpinnerColor := TAlphaColors.Orange;
end;

Customize the Spinner's Background

You can add a background with rounded corners directly behind the spinner for better visibility.

procedure TMyForm.FormCreate(Sender: TObject);
begin
  FLoader := TUIOverlayLoader.Create(Self);
  FLoader.SetOverloadingForm(Self);

  FLoader.SpinnerBackgroundColor := TAlphaColors.White;
  FLoader.SpinnerBackgroundOpacity := 0.8;
  FLoader.SpinnerBackgroundRadius := 16; // Corner radius
end;

Adjust Animation

Change the animation's interpolation type and duration (velocity).

procedure TMyForm.FormCreate(Sender: TObject);
begin
  FLoader := TUIOverlayLoader.Create(Self);
  FLoader.SetOverloadingForm(Self);

  // Make the animation faster (lower duration = faster)
  FLoader.SpinnerVelocity := 0.5; // 0.5 seconds per 360-degree rotation

  // Change the animation curve
  FLoader.SpinnerMotion := TSpinnerMotion.Bounce;
end;

📚API Reference

Properties

Methods