Core Window Guide

This guide covers the InfiniFrameWindowBuilder the foundation for creating all InfiniFrame windows. It walks through the builder pattern, single-file packaging, and provides a complete reference to every window feature.

For a conceptual overview of how the feature system works, see Window Features Architecture.

Contents

• Building a Window
• Single-File Native Packaging
• Builder Quick Reference
• Feature Guides

Building a Window

All windows are created through InfiniFrameWindowBuilder using a fluent API.

using InfiniFrame;

var window = InfiniFrameWindowBuilder.Create()
    .SetTitle("My App")
    .SetSize(1280, 720)
    .Center()
    .SetStartPageUrl("https://myapp.local")
    .Build();

window.WaitForClose();

Build() creates and displays the native window immediately on the calling thread. The returned IInfiniFrameWindow gives you full control over the window at runtime.

Single-File Native Packaging

When your app is published as a single-file executable with embedded InfiniFrame native binaries, call InfiniFrameSingleFileBootstrap.Initialize() before creating any windows.

using InfiniFrame;

public static class Program {
    [STAThread]
    public static void Main(string[] args) {
        InfiniFrameSingleFileBootstrap.Initialize();

        var window = InfiniFrameWindowBuilder.Create()
            .SetTitle("My App")
            .SetSize(1280, 720)
            .Center()
            .SetStartPageUrl("app://index.html")
            .Build();

        window.WaitForClose();
    }
}

Initialize() is idempotent and safe to call once at startup. Use it for packaged deployments created by InfiniLore.InfiniFrame.SingleFile (or any equivalent flow that embeds native files as resources), not for standard development runs where native binaries are already present beside your app.

Builder Quick Reference

Every builder method maps to a feature. The table below shows the most common methods and their corresponding feature guides.

Window appearance

Method	Feature	Guide
SetTitle(string)	Decorations	Decorations
SetIconFile(string)	Decorations	Decorations
SetBackgroundColor(string?)	Decorations	Decorations
SetChromeless(bool)	Decorations	Decorations
SetTransparent(bool)	Decorations	Decorations

Size and position

Method	Feature	Guide
SetSize(int, int)	Size	Size
SetMinSize(int, int)	Size	Size
SetMaxSize(int, int)	Size	Size
SetLocation(int, int)	Position	Position
Center()	Position	Position

Window state

Method	Feature	Guide
SetMaximized(bool)	State	State
SetMinimized(bool)	State	State
SetFullScreen(bool)	State	State
SetTopMost(bool)	State	State
SetResizable(bool)	Size	Size

Content

Method	Feature	Guide
SetStartPageUrl(string?)	Page Navigation	Page Navigation
SetStartPageContent(string?)	Page Navigation	Page Navigation
SetUrl(Uri?)	Page Navigation	Page Navigation
RegisterCustomSchemeHandler(...)	Page Navigation	Page Navigation

Browser settings

Method	Feature	Guide
SetDevToolsEnabled(bool)	Debugging	Debugging
SetRemoteDebuggingPort(int?)	Debugging	Debugging
SetContextMenuEnabled(bool)	Browser	Browser
SetUserAgent(string?)	Browser	Browser
EnableStatusBar(bool)	Browser	Browser
EnableIgnoreCertificateErrors(bool)	Browser	Browser
EnableWebSecurity(bool)	Browser	Browser
SetBrowserControlInitParameters(string)	Browser	Browser

Other features

Method	Feature	Guide
SetMenuBar(InfiniFrameMenuBar)	Menu	Native Menu
EnableNotifications(bool)	Notifications	Notifications
SetInstanceArbitrationMode(...)	Instance Arbitration	Instance Arbitration
AddTrustedOrigin(string)	Browser	Browser

Events

Property	Guide
builder.Events.WindowCreated	Lifecycle
builder.Events.WindowClosingRequested	Lifecycle
builder.Events.WindowSizeChanged	Lifecycle
builder.Events.WebMessageReceived	JavaScript Interop
builder.MessageHandlers	JavaScript Interop

Runtime access

After Build(), all features are accessible through window.Features.<Name> or as extension methods on IInfiniFrameWindow:

// Extension methods (fluent chaining)
window.SetSize(800, 600);
window.SetTitle("New Title");
window.Close();

// Direct feature access
window.Features.Size.SetSize(800, 600);
window.Features.Decorations.SetTitle("New Title");
window.Features.Lifecycle.Close();

Feature Guides

Each window feature has a dedicated guide covering both builder configuration and runtime control:

Core features

Feature	Description	Guide
Size	Window dimensions, min/max constraints, resizability	Builder + Runtime
Position	Window placement, centering, monitor-aware positioning	Builder + Runtime
State	Maximized, minimized, fullscreen, topmost, zoom	Builder + Runtime
Decorations	Title, icon, chromeless mode, transparency, background color	Builder + Runtime
Browser	Context menu, media, web security, clipboard, user agent, status bar	Builder + Runtime
Debugging	DevTools, remote debugging, web inspector, diagnostics	Builder + Runtime
Page Navigation	Load URLs/HTML, navigation interception, custom URL schemes	Builder + Runtime
Lifecycle	Window close, ready wait, teardown, events, cross-thread invocation	Runtime

Dialogs and system integration

Feature	Description	Guide
File Dialogs	Open/save file and folder dialogs	Runtime
Notifications	Native desktop notifications, rich notifications, async callbacks	Builder + Runtime
Native Menu	Menu bar configuration, runtime menu manipulation	Builder + Runtime
Taskbar	Progress indicators and flash notifications	Builder + Runtime
Monitors	Display enumeration, work area, DPI	Runtime

Input and messaging

Feature	Description	Guide
Drag and Drop	File drop handling, extension filtering	Runtime
JavaScript Execution	Execute arbitrary JS in the browser control	Runtime
JavaScript Interop	Two-way C#/JS messaging, InfiniFrame.Js	Runtime
Invoke	Cross-thread dispatch to the window's native thread	Runtime

Configuration

Feature	Description	Guide
Instance Arbitration	Single-instance enforcement, elevation detection	Builder
Custom Window Chrome	Blazor components and JS API for chromeless windows	Builder + Runtime

Taskbar Progress and Flash

InfiniFrame provides cross-platform taskbar integration for progress indicators and flash notifications. Access the taskbar feature through window.Features.Taskbar.

Platform Support

Feature	Windows	macOS	Linux
Progress states	Yes	Yes	Desktop-dependent
Flash notifications	Yes	Yes	Desktop-dependent
Capability detection	Yes	Yes	Yes

Platform details:

• Windows: Full support via ITaskbarList3 COM and FlashWindowEx
• macOS: Progress via dock tile badge label, flash via NSApp.requestUserAttention
• Linux: D-Bus StatusNotifierItem + UnityLauncherEntry (GNOME may report IsSupported=false)

Progress Indicator

// Show download progress (current, total)
window.Features.Taskbar.SetProgress(TaskbarProgressState.Normal, 75, 100);

// Show indeterminate progress
window.Features.Taskbar.SetProgress(TaskbarProgressState.Indeterminate, 0, 0);

// Show error state
window.Features.Taskbar.SetProgress(TaskbarProgressState.Error, 0, 0);

// Clear progress
window.Features.Taskbar.ClearProgress();

Flash Notifications

// Flash all windows continuously (count 0 = until user interacts)
window.Features.Taskbar.SetFlash(TaskbarFlashMode.All, 0);

// Flash timer-based
window.Features.Taskbar.SetFlash(TaskbarFlashMode.Timer, 3);

// Stop flashing
window.Features.Taskbar.StopFlash();

Capability Detection

InfiniFrameTaskbarCapabilities caps = window.Features.Taskbar.Capabilities;

if (caps.SupportsProgress) {
    window.Features.Taskbar.SetProgress(TaskbarProgressState.Normal, 50, 100);
} else {
    // Fallback to in-app progress indicator
    Console.WriteLine("Taskbar progress not supported on this platform");
}

Examples

• InfiniFrameExample.WebApp.React (examples/InfiniFrameExample.WebApp.React) - custom URL scheme handler and web messaging with DI-resolved services
• InfiniFrameExample.BlazorWebView (examples/InfiniFrameExample.BlazorWebView) - window builder configuration with size, position, and icon
• InfiniFrameExample.SingleFileExe (examples/InfiniFrameExample.SingleFileExe) - embedded static assets and single-file native bootstrap