Siticone Logo
Siticone UI
DOCS
v2025.12.15
Docs Form

Complete control guide

Siticone Form

SiticoneForm is a borderless WinForms Form with a themed title bar, DPI-aware control-box glyphs, edge resizing, drag-to-edge snapping, placement persistence, system-theme integration, optional Windows 11 backdrops, closing safeguards, and fade animation. This guide documents the complete public API shown in the supplied control source.

Public properties127
Public methods12
Public events8
Snap zones8
Windows integration Theme, accent and backdrop support

Follow the Windows app theme, use the Windows accent color, detect platform support, and opt into Mica, Acrylic, or Mica Alt.

Window interaction Resize, drag, maximize and snap

The borderless window retains familiar edge resizing, title-bar dragging, working-area maximize behavior, and seven useful snap destinations.

Application chrome Six configurable title-bar buttons

Close, maximize, minimize, help, pin, and settings buttons have independent visibility, glyph sizing, and normal, hover, and pressed colors.

What stays compatible?

The control derives from System.Windows.Forms.Form. You can continue to add controls in the Visual Studio designer and use ordinary inherited members such as ShowDialog(), DialogResult, Owner, Shown, and FormClosed. The deliberate exceptions are listed in Compatibility members.

Quick start

Change the base class of an existing WinForms window from Form to SiticoneForm. Keep InitializeComponent() exactly where the designer generated it.

C# — inherit from SiticoneForm
using SiticoneNetFrameworkUI;

public partial class MainWindow : SiticoneForm
{
    public MainWindow()
    {
        InitializeComponent();

        FormTitle = "My application";
        StartPosition = FormStartPosition.CenterScreen;
    }
}

A practical first configuration

This keeps the familiar window actions, hides optional buttons until they are useful, and leaves DPI scaling enabled.

C# — recommended starting configuration
public MainWindow()
{
    InitializeComponent();

    FormTitle = "Dashboard";
    ShowCloseBox = true;
    ShowMaximizeBox = true;
    ShowMinimizeBox = true;

    ShowHelpBox = false;
    ShowPinToTopBox = false;
    ShowSettingsBox = false;

    DragTitleBar = true;
    EnableFormResizing = true;
    EnableDpiScaling = true;
    MaximizeToWorkingArea = true;
}

Important constructor defaults

These values are applied by a new SiticoneForm() before your form-specific configuration runs.

AreaInitial valueWhat it means
BorderFormBorderStyle.NoneThe custom title bar replaces the standard Windows caption and border.
Start positionCenterScreenThe first show is centered unless you select another StartPosition or restore saved placement.
ThemeFormThemeVariant.LightDefaultThe theme engine applies its light default colors at construction.
ScalingAutoScaleMode.DpiThe form and its custom chrome are prepared for per-display DPI scaling.
Application fontSegoe UI, 9pt, RegularInherited Font is initialized for ordinary form content.
Title fontSegoe UI, 9pt, BoldFormTitleFont controls the title text independently.
All six title-bar buttonsVisibleHide Help, Pin, or Settings if your application does not use their events.
Fade and shadowEnabledThe normal fade duration is 160 ms and the native drop-shadow switch is on.
Dragging and resizingEnabledThe title bar drags the form and a 6 logical-pixel edge grip resizes it.
SnappingEnabledEdge snapping, snap preview, and restore-on-drag behavior are enabled.
Closing safeguardsDisabledConfirmation, countdown, and closing prevention are opt-in.
Windows 11 backdropDisabled / NoneThe form paints an ordinary opaque themed surface until enabled.
Use FormTitle for the visible caption

FormTitle updates both the custom title text and the underlying window text. The inherited-looking Text member remains public for compatibility, but it is hidden from the designer and setting it directly does not update the custom title field.

Themes and manual colors

The theme engine owns the form surface, title bar, six control-box buttons, legacy hover colors, and snap-preview accent until you manually customize an individual color. A manual color remains in place during ordinary theme refreshes unless you explicitly reset customization.

Select a theme supplied by your installed package

FormThemeVariant is defined by the library's form-theme helper. The supplied SiticoneForm source proves LightDefault as the default. Use IntelliSense to choose any additional variant available in the exact package version referenced by your application.

C# — apply a selected theme reliably
private void ChangeTheme(FormThemeVariant selectedTheme)
{
    // ApplyTheme clears manual color flags first, then applies the variant.
    ApplyTheme(selectedTheme);
}

private void RestoreDocumentedDefaultTheme()
{
    ApplyTheme(FormThemeVariant.LightDefault);
}

Choose the correct refresh method

MemberPreserves custom colors?Use it when
RefreshTheme()YesYou want the current variant reapplied only to properties that the application has not manually customized.
ApplyTheme(variant)NoYou want the chosen variant to take full control of every theme-managed color immediately.
ResetColorCustomizations()Clears the flagsYou want to return ownership to the theme engine. Call RefreshTheme() afterward to repaint with the current theme.
RefreshAppearance()YesYou changed chrome sizing or visibility in a batch and want metrics, buttons, and painting refreshed; it does not select a theme.
C# — reset manual colors without changing the selected variant
private void UseThemeColorsAgain()
{
    ResetColorCustomizations();
    RefreshTheme();
}

Keep a custom form background while themes change

Set BackColorCustomizable before assigning BackColor. This explicitly exempts the form surface from theme painting while the title bar and buttons may continue to follow ThemeVariant.

C# — theme the chrome but keep your own surface color
BackColorCustomizable = true;
BackColor = Color.FromArgb(18, 20, 42);

// The title bar and control-box colors can still use the selected theme.
RefreshTheme();

ForceThemeBackColorOverride defaults to true. When ThemeVariant changes, it clears manual BackColor and ForeColor customization flags so the new variant can apply. BackColorCustomizable is the stronger, explicit exemption for the background.

Turn the theme engine off for a completely manual design

C# — fully manual colors
EnableThemeEngine = false;

BackColor = Color.FromArgb(20, 22, 28);
ForeColor = Color.White;
TitleBarBackColor = Color.FromArgb(12, 14, 19);
TitleBarForeColor = Color.White;

CloseButtonBackColor = Color.Transparent;
CloseButtonHoverBackColor = Color.FromArgb(190, 35, 45);
CloseButtonHoverForeColor = Color.White;

RefreshAppearance();

Windows theme and accent color

FollowSystemTheme switches between SystemLightThemeVariant and SystemDarkThemeVariant when the Windows app preference changes. The light choice defaults to LightDefault. The dark choice resolves a variant named DarkDefault when that value exists in the installed enum and otherwise falls back to LightDefault.

C# — follow Windows automatically
public MainWindow()
{
    InitializeComponent();

    FollowSystemTheme = true;
    UseSystemAccentColor = true;
}

private void refreshThemeButton_Click(object sender, EventArgs e)
{
    // Useful after your own settings workflow changes Windows-related options.
    SyncWithSystemTheme();
}
System theme test SiticoneForm.IsSystemInDarkMode()

Returns whether Windows currently requests dark app mode. If the preference cannot be read, it safely returns false.

Effective accent AccentColor

Returns the Windows accent when UseSystemAccentColor is true; otherwise it returns the theme-driven snap accent.

C# — inspect the effective Windows integration
private void ShowThemeStatus()
{
    bool windowsUsesDarkApps = SiticoneForm.IsSystemInDarkMode();
    bool formLooksDark = IsDarkTheme;
    Color effectiveAccent = AccentColor;

    statusLabel.Text =
        "Windows dark: " + windowsUsesDarkApps +
        "; Form dark: " + formLooksDark +
        "; Accent: " + effectiveAccent;
}

Windows 11 backdrops

Backdrops are opt-in and require Windows build 22621 or newer. Set both EnableBackdrop = true and a non-None BackdropType. Earlier Windows versions safely continue without the material.

FormBackdropTypeNumeric valueMeaning
None0No system material; the form paints its own opaque background.
Auto1Lets Windows choose the material.
Mica2Uses the wallpaper-tinted main-window Mica material.
Acrylic3Uses the transient-window Acrylic material.
MicaAlt4Uses the tabbed-window Mica variant.
C# — enable Mica with a safe fallback
private void ConfigureBackdrop()
{
    if (SiticoneForm.IsBackdropSupported)
    {
        EnableFadeAnimation = false;
        EnableBackdrop = true;
        BackdropType = FormBackdropType.Mica;
        AutoBackdropBackColor = true;
    }
    else
    {
        EnableBackdrop = false;
        BackdropType = FormBackdropType.None;
        RefreshTheme();
    }
}
Backdrop and opacity-based fades should not be combined

A DWM backdrop and a layered, partially transparent window are incompatible. The form skips its startup fade while a backdrop is active. For a predictable configuration, set EnableFadeAnimation = false whenever you enable a backdrop.

C# — let the user switch materials
private void SetBackdrop(FormBackdropType material)
{
    bool supported = SiticoneForm.IsBackdropSupported;

    EnableFadeAnimation = !supported || material == FormBackdropType.None;
    EnableBackdrop = supported && material != FormBackdropType.None;
    BackdropType = supported ? material : FormBackdropType.None;
}

private void ShowBackdropStatus()
{
    statusLabel.Text = IsBackdropActive
        ? "System backdrop enabled"
        : "Opaque themed background";
}

Title bar, icon and DPI

Title-bar measurements and control-box glyph measurements are logical values based on a 96-DPI design baseline. With EnableDpiScaling = true, the control scales them for the current display. The title icon is rendered from the best available icon frame for the required physical size.

C# — configure the caption and icon
FormTitle = "Patient dashboard";
FormTitleFont = new Font("Segoe UI", 10f, FontStyle.Bold);
TitleBarHeight = 42;
TitleLeftPadding = 12;

Icon = Properties.Resources.ApplicationIcon;
IconSize = 22;
ShowTitleBarIcon = true;
ShowTitleBarText = true;

Create an icon-only or text-only caption

C# — title-bar visibility combinations
private void UseTextOnlyCaption()
{
    ShowTitleBarIcon = false;
    ShowTitleBarText = true;
}

private void UseIconOnlyCaption()
{
    ShowTitleBarIcon = true;
    ShowTitleBarText = false;
}

Tune control-box dimensions for your design

C# — DPI-aware title-bar sizing
EnableDpiScaling = true;

TitleBarHeight = 40;
ControlBoxButtonWidth = 56;
IconSize = 21;

CloseButtonIconSize = 5.5f;
MaximizeButtonIconSize = 5.5f;
MinimizeButtonIconSize = 5.5f;
HelpButtonIconSize = 2.9f;
PinButtonIconSize = 5.5f;
SettingsButtonIconSize = 5.5f;
ControlBoxIconStrokeWidth = 1.8f;

RefreshAppearance();
Reading the current scale

DpiScaleFactor is DeviceDpi / 96 while DPI scaling is enabled and 1 when it is disabled. You normally do not multiply the documented logical size properties yourself.

Control box

The title bar contains six independently visible buttons. Close, maximize, minimize, and pin perform their actions automatically. Help and Settings intentionally expose events so your application decides what to open.

ButtonVisibility propertyBuilt-in behavior
CloseShowCloseBoxRuns the configured countdown or confirmation behavior, raises the applicable close event, and begins the close sequence.
Maximize / RestoreShowMaximizeBoxCalls ToggleMaximizeState().
MinimizeShowMinimizeBoxSets WindowState to Minimized.
HelpShowHelpBoxRaises HelpButtonClicked; your handler opens the relevant help experience.
Pin to topShowPinToTopBoxToggles IsPinned and TopMost, then raises PinToTopClicked.
SettingsShowSettingsBoxRaises SettingsClicked; your handler opens settings.

Show only the buttons your application uses

C# — control-box visibility
ShowCloseBox = true;
ShowMaximizeBox = true;
ShowMinimizeBox = true;

ShowHelpBox = true;
ShowSettingsBox = true;
ShowPinToTopBox = false;

Connect Help and Settings to your own windows

C# — optional button events
public MainWindow()
{
    InitializeComponent();

    ShowHelpBox = true;
    ShowSettingsBox = true;

    HelpButtonClicked += MainWindow_HelpButtonClicked;
    SettingsClicked += MainWindow_SettingsClicked;
}

private void MainWindow_HelpButtonClicked(object sender, EventArgs e)
{
    using (HelpWindow help = new HelpWindow())
    {
        help.ShowDialog(this);
    }
}

private void MainWindow_SettingsClicked(object sender, EventArgs e)
{
    using (SettingsWindow settings = new SettingsWindow())
    {
        settings.ShowDialog(this);
    }
}

Customize a button for normal, hover, and pressed states

Every button has a foreground property for its glyph and a background property for its surface in each state. The theme engine treats manual assignments as customizations and leaves them in place during RefreshTheme().

C# — close-button state colors
CloseButtonForeColor = Color.FromArgb(220, 225, 232);
CloseButtonBackColor = Color.Transparent;

CloseButtonHoverForeColor = Color.White;
CloseButtonHoverBackColor = Color.FromArgb(190, 35, 45);

CloseButtonPressForeColor = Color.White;
CloseButtonPressBackColor = Color.FromArgb(145, 24, 34);

RotateCloseIconOnHover = true;

Apply one interaction palette to all non-close buttons

C# — coherent button palette
private void ApplyControlBoxPalette(Color normal, Color hover, Color pressed)
{
    MaximizeButtonForeColor = normal;
    MinimizeButtonForeColor = normal;
    HelpButtonForeColor = normal;
    PinToTopButtonForeColor = normal;
    SettingsButtonForeColor = normal;

    MaximizeButtonHoverForeColor = hover;
    MinimizeButtonHoverForeColor = hover;
    HelpButtonHoverForeColor = hover;
    PinToTopButtonHoverForeColor = hover;
    SettingsButtonHoverForeColor = hover;

    MaximizeButtonPressForeColor = pressed;
    MinimizeButtonPressForeColor = pressed;
    HelpButtonPressForeColor = pressed;
    PinToTopButtonPressForeColor = pressed;
    SettingsButtonPressForeColor = pressed;

    RefreshAppearance();
}
Legacy shared hover properties are narrower than their names suggest

OnHoverControlIconColor and OnHoverControlBackColor update the Maximize, Minimize, and Help buttons. Pin and Settings have their own legacy aliases, and Close has its own pair. New code should prefer the explicit per-button state properties.

Dragging, resizing and maximizing

Title-bar dragging

DragTitleBar defaults to true. A small movement threshold distinguishes an intended drag from a click or double-click, so double-click maximize remains usable when EnableTitleBarDoubleClick is true.

C# — standard movable, resizable window
DragTitleBar = true;
EnableTitleBarDoubleClick = true;

EnableFormResizing = true;
ResizeBorderThickness = 6;

MaximizeToWorkingArea = true;
EnableSnapRestoreOnDrag = true;

Drag from passive content surfaces

DragEntireForm adds drag behavior to the form surface and passive descendants that are a Panel, Label, PictureBox, or GroupBox. Interactive controls such as buttons, text boxes, lists, and grids retain their normal mouse behavior.

C# — dashboard-style whole-surface dragging
public FloatingSummaryWindow()
{
    InitializeComponent();

    DragEntireForm = true;
    DragTitleBar = true;
    EnableFormResizing = false;
}
Do not use DragEntireForm when the empty surface must receive a different drag gesture

When enabled, a left-button drag on the form background or supported passive surfaces moves the window. Leave it false if those surfaces implement their own drag selection, drawing, or rearrangement behavior.

Programmatic maximize and restore

C# — toggle and react to window state
public MainWindow()
{
    InitializeComponent();
    MaximizeStateChanged += MainWindow_MaximizeStateChanged;
}

private void maximizeButton_Click(object sender, EventArgs e)
{
    ToggleMaximizeState();
}

private void MainWindow_MaximizeStateChanged(object sender, EventArgs e)
{
    layoutPanel.Padding = IsMaximized
        ? new Padding(16)
        : new Padding(24);
}

MaximizeToWorkingArea = true keeps the taskbar visible. If you set it to false, the form clears its custom maximized bounds and lets Windows use its normal maximize metrics.

Window snapping

Drag snapping uses the working area of the screen under the pointer. The top edge maximizes; the left and right edges use half-screen layouts; corners use quarter-screen layouts. Releasing a drag applies the candidate zone.

FormSnapZoneNumeric valueResult
None0No snap destination is active.
Maximize1Fills the screen working area.
Left2Uses the left half of the working area.
Right3Uses the right half of the working area.
TopLeft4Uses the top-left quarter.
TopRight5Uses the top-right quarter.
BottomLeft6Uses the bottom-left quarter.
BottomRight7Uses the bottom-right quarter.

Enable or disable snapping independently from its preview

C# — snapping configuration
EnableWindowSnapping = true;
EnableSnapRestoreOnDrag = true;

EnableSnapPreview = true;
SnapTriggerDistance = 12;
SnapPreviewCornerRadius = 10;
SnapPreviewBorderThickness = 2;
SnapPreviewOpacity = 0.92d;
SnapPreviewAnimationDuration = 300;

Setting EnableSnapPreview = false hides the visual overlay but does not disable snapping. Set EnableWindowSnapping = false when the drag itself must never change the window into a snap zone.

Customize the preview

C# — branded snap preview
UseSystemAccentColor = false;

SnapPreviewColor = Color.FromArgb(52, 211, 153);
SnapPreviewBorderColor = Color.FromArgb(167, 243, 208);
SnapPreviewCornerRadius = 12;
SnapPreviewBorderThickness = 2;
SnapPreviewOpacity = 0.85d;
SnapPreviewAnimationDuration = 180;

Snap from application commands

C# — programmatic layouts
private void dockLeftMenuItem_Click(object sender, EventArgs e)
{
    SnapTo(FormSnapZone.Left);
}

private void dockBottomRightMenuItem_Click(object sender, EventArgs e)
{
    SnapTo(FormSnapZone.BottomRight);
}

private void maximizeMenuItem_Click(object sender, EventArgs e)
{
    SnapTo(FormSnapZone.Maximize);
}
SnapTo(None) is intentionally a no-op

SnapTo(FormSnapZone.None) does not restore the window. Use ToggleMaximizeState() for maximize/restore behavior or assign ordinary bounds for your own layout command.

Resolve a zone without moving the form

C# — test a screen-coordinate point
private void ShowCandidateZone(Point screenPoint)
{
    Rectangle targetBounds;
    FormSnapZone zone = ResolveSnapZone(screenPoint, out targetBounds);

    if (zone == FormSnapZone.None)
    {
        statusLabel.Text = "No snap target";
        return;
    }

    statusLabel.Text = zone + " -> " + targetBounds;
}

Observe candidate changes and completed snaps

C# — snap events
public MainWindow()
{
    InitializeComponent();

    SnapZoneChanged += MainWindow_SnapZoneChanged;
    Snapped += MainWindow_Snapped;
}

private void MainWindow_SnapZoneChanged(object sender, FormSnapEventArgs e)
{
    snapStatusLabel.Text = e.Zone == FormSnapZone.None
        ? "Move freely"
        : "Release to use " + e.Zone;
}

private void MainWindow_Snapped(object sender, FormSnapEventArgs e)
{
    snapStatusLabel.Text = "Snapped to " + e.Zone + " at " + e.Bounds;
}

Save and restore window placement

SaveWindowPlacement() returns a compact, culture-independent string containing normal bounds and maximized state. RestoreWindowPlacement() validates the token, honors MinimumSize, rejects off-screen placement, changes StartPosition to Manual, and returns whether restoration succeeded.

  1. Create a user-scoped string setting such as MainWindowPlacement.
  2. Restore it when the form is first shown.
  3. Save a fresh token when the window closes successfully.
C# — persist placement with application settings
protected override void OnShown(EventArgs e)
{
    base.OnShown(e);

    string savedPlacement = Properties.Settings.Default.MainWindowPlacement;

    if (!RestoreWindowPlacement(savedPlacement))
    {
        StartPosition = FormStartPosition.CenterScreen;
    }
}

protected override void OnFormClosed(FormClosedEventArgs e)
{
    Properties.Settings.Default.MainWindowPlacement = SaveWindowPlacement();
    Properties.Settings.Default.Save();

    base.OnFormClosed(e);
}

Store placement somewhere else

C# — storage-agnostic placement methods
private void RestoreFromProfile(string placementFromProfile)
{
    bool restored = RestoreWindowPlacement(placementFromProfile);

    if (!restored)
    {
        StartPosition = FormStartPosition.CenterScreen;
    }
}

private string CaptureForProfile()
{
    return SaveWindowPlacement();
}
Disconnected monitors are handled safely

Restoration succeeds only when a meaningful part of the saved window intersects a currently connected screen's working area. Invalid, empty, unknown-version, non-positive-size, and unreachable tokens return false.

Closing safeguards and animation

The custom Close button supports prevention, a click-again-to-cancel countdown, optional confirmation, a cancellable custom event, and an animated close. These options have a defined precedence.

SituationWhat the Close button doesImportant detail
PreventFormClosing = trueDoes nothing and closing is cancelled.This is the strongest safeguard and also cancels the eventual framework closing path.
A countdown is already activeStops and clears the countdown.The second click cancels the pending Close-button request.
EnableCloseCountdown = trueStarts at CloseCountdownDuration.When countdown is enabled, the confirmation dialog and custom FormClosing event are not used for that Close-button request.
Countdown is off and confirmation is onShows the Yes/No confirmation dialog.Choosing No ends the request.
Confirmation accepted or disabledRaises the custom FormClosing event.Set CancelEventArgs.Cancel = true to stop this Close-button request.
Request is acceptedRuns the close fade when enabled, then closes.FadeDuration = 0 or EnableFadeAnimation = false makes the transition immediate.

Ask for confirmation

C# — confirmation dialog
EnableCloseCountdown = false;
EnableCloseConfirmation = true;

CloseConfirmationTitle = "Close application";
CloseConfirmationMessage = "Are you sure you want to close the application?";

Use a cancellable countdown

C# — close countdown
EnableCloseCountdown = true;
CloseCountdownDuration = 5;
CloseCountdownFont = new Font("Segoe UI", 10f, FontStyle.Bold);

// The first Close-button click starts the countdown.
// Clicking the Close button again before zero cancels it.
Countdown takes precedence over confirmation

If both EnableCloseCountdown and EnableCloseConfirmation are true, a Close-button click uses the countdown path. It does not show the confirmation dialog after the countdown reaches zero.

Temporarily block all closing

C# — protect a critical operation
private async void saveButton_Click(object sender, EventArgs e)
{
    PreventFormClosing = true;

    try
    {
        await SaveImportantWorkAsync();
    }
    finally
    {
        PreventFormClosing = false;
    }
}

Cancel a normal custom Close-button request

C# — custom FormClosing event
public EditorWindow()
{
    InitializeComponent();

    EnableCloseCountdown = false;
    FormClosing += EditorWindow_FormClosing;
}

private void EditorWindow_FormClosing(object sender, CancelEventArgs e)
{
    if (!hasUnsavedChanges) return;

    DialogResult answer = MessageBox.Show(
        this,
        "Discard the unsaved changes?",
        "Unsaved changes",
        MessageBoxButtons.YesNo,
        MessageBoxIcon.Warning);

    e.Cancel = answer != DialogResult.Yes;
}
The public FormClosing event is a custom, shadowing event

It uses CancelEventArgs and is raised by the custom Close button when countdown is disabled and confirmation has been accepted. It is not raised by the countdown reaching zero or by the public Close() method. Use inherited FormClosed when you need notification after every successful close.

Close from code

C# — programmatic animated close
private void exitAfterSaveButton_Click(object sender, EventArgs e)
{
    // Starts the Siticone close sequence directly.
    // It does not display the configured countdown or confirmation dialog.
    Close();
}

Configure fade timing

C# — fast, subtle window fade
EnableFadeAnimation = true;
FadeDuration = 140;

// Valid assignments are clamped between 0 and 5000 milliseconds.
// Set FadeDuration to 0 for an immediate transition.

Public events

EventEvent argumentsWhen it occursRecommended use
IsPinnedChangedIsPinnedChangedEventArgsAfter IsPinned changes through its public setter, including a Pin-button toggle.Persist the new e.IsPinned state or update pin-related UI.
MaximizeStateChangedEventArgsAfter the control's maximize/restore workflows change state, including its toggle command, maximize snap, or drag restore.Reflow UI that should differ between normal and maximized layouts. Directly assigning every possible WindowState value is not documented to raise it.
HelpButtonClickedEventArgsWhen the visible Help title-bar button receives a left click.Open contextual help, documentation, or a support dialog.
FormClosingCancelEventArgsBefore an ordinary custom Close-button request continues, when countdown is disabled and confirmation is accepted.Cancel that specific request by setting e.Cancel = true. See the closing notes above.
PinToTopClickedEventArgsAfter the Pin button toggles IsPinned.Track that the action came from the button. Read IsPinned for the new state.
SettingsClickedEventArgsWhen the visible Settings title-bar button receives a left click.Open your application's settings window or menu.
SnapZoneChangedFormSnapEventArgsDuring a move operation when the candidate zone changes, including a change back to None.Show text or application UI describing the current candidate. e.Bounds is the proposed target.
SnappedFormSnapEventArgsAfter a drag snap or SnapTo() request has been applied.Persist layout choices or update UI after snapping.

Pin a utility window and save the state

C# — pin-to-top workflow
public UtilityWindow()
{
    InitializeComponent();

    ShowPinToTopBox = true;
    PinToTopPinnedIconColor = Color.DodgerBlue;
    IsPinnedChanged += UtilityWindow_IsPinnedChanged;
}

private void UtilityWindow_IsPinnedChanged(object sender, SiticoneForm.IsPinnedChangedEventArgs e)
{
    Properties.Settings.Default.UtilityWindowPinned = e.IsPinned;
    Properties.Settings.Default.Save();
}
IsPinned and TopMost represent the same window state

Assigning IsPinned also synchronizes TopMost and raises IsPinnedChanged. Assigning TopMost synchronizes the pin state and glyph, but its setter does not raise IsPinnedChanged. Prefer IsPinned when event notification matters.

Complete public property reference

The following tables document every public property declared by the supplied SiticoneForm source, including designer-hidden, read-only, compatibility, and legacy members. “Theme-managed” means the effective initial color comes from FormThemeVariant.LightDefault; the source does not hard-code that provider's public palette into the property contract.

Theme, surface and Windows appearance

PropertyTypeDefault / rangePurpose and usage
ThemeVariantFormThemeVariantLightDefaultSelects the library theme used for non-customized form, title-bar, control-box, and snap-accent colors.ThemeVariant = FormThemeVariant.LightDefault;
EnableThemeEnginebooltrueWhen false, theme application stops changing colors so your assignments remain fully manual.EnableThemeEngine = false;
BackColorColorTheme-managedForm surface color. A manual assignment is tracked as a customization.BackColor = Color.FromArgb(18, 20, 42);
ForeColorColorTheme-managedForm foreground color. A manual assignment is tracked as a customization.ForeColor = Color.White;
BackColorCustomizableboolfalseExplicitly exempts BackColor from theme painting. Setting it back to false returns the surface to the theme.BackColorCustomizable = true;
ForceThemeBackColorOverridebooltrueWhen ThemeVariant changes, clears manual BackColor and ForeColor flags so the new theme can apply.ForceThemeBackColorOverride = false;
FollowSystemThemeboolfalseAutomatically chooses the configured light or dark variant as the Windows app theme changes.FollowSystemTheme = true;
SystemLightThemeVariantFormThemeVariantLightDefaultVariant selected when Windows requests light apps and FollowSystemTheme is enabled.
SystemDarkThemeVariantFormThemeVariantDarkDefault when available; otherwise LightDefaultVariant selected when Windows requests dark apps and FollowSystemTheme is enabled.
UseSystemAccentColorboolfalseUses the Windows personalization accent for accent-driven colors such as the snap preview.UseSystemAccentColor = true;
EnableBackdropboolfalseMaster switch for a supported Windows 11 system backdrop. A non-None BackdropType is also required.
BackdropTypeFormBackdropTypeNoneSelects Auto, Mica, Acrylic, MicaAlt, or None. Requires Windows build 22621 or newer.BackdropType = FormBackdropType.Mica;
AutoBackdropBackColorbooltrueWhen a backdrop is active, manages the form surface needed for the DWM material. Disable only when you deliberately manage the backdrop surface yourself.
UseRoundedCornersbooltrueRequests rounded window corners on Windows 11. Earlier Windows versions ignore the request safely.
EnableDropShadowbooltrueControls the native drop-shadow window style. Configure it before handle creation for a predictable result.
ForceDropshadowboolfalseKeeps the focused border/shadow visual treatment while inactive, removing the usual active/inactive visual distinction.

Title bar, icon, layout and DPI

PropertyTypeDefault / rangePurpose and usage
FormTitlestring"Form Title"Visible custom caption. Also updates the underlying window text and taskbar caption.FormTitle = "Dashboard";
FormTitleFontFontSegoe UI, 9pt, BoldFont used only for the custom caption text.
TitleBarBackColorColorTheme-managedFills the custom title-bar area. Manual assignment becomes a preserved customization.
TitleBarForeColorColorTheme-managedColor used to draw FormTitle.
TitleLeftPaddingint10 logical pxSpace from the left window edge to the title-bar icon or text.
TitleBarHeightint36 logical px; minimum 1Height shared by the title-bar surface and control-box buttons.TitleBarHeight = 42;
ShowTitleBarIconbooltrueShows or hides the custom title-bar icon without changing the taskbar icon.
ShowTitleBarTextbooltrueShows or hides the custom caption text.
IconIconnull until assignedSets the image used by the title bar and standard taskbar integration. Multi-size icon resources give the best high-DPI result.
IconSizeint21 logical px; minimum 1Logical size of the icon in the title bar.
ControlBoxButtonWidthint59 logical px; minimum 1Width applied to every visible title-bar button.
EnableDpiScalingbooltrueScales title-bar height, button width, icon sizes, glyph stroke, resize grip, and other logical chrome metrics for the display DPI.
StartPositionFormStartPositionCenterScreenControls the initial position. Successful placement restoration changes it to Manual.
EnableTitleBarDoubleClickbooltrueLets a left-button title-bar double-click call ToggleMaximizeState().

Window interaction, state and pinning

PropertyTypeDefault / rangePurpose and usage
DragTitleBarbooltrueEnables dragging from the custom caption area.
DragEntireFormboolfalseAlso enables dragging from the form background and passive Panel, Label, PictureBox, and GroupBox descendants.
EnableFormResizingbooltrueEnables edge and corner resizing while the form is in its normal state.
ResizeBorderThicknessint6 logical px; minimum 1Thickness of the invisible resize grip along all edges.
MaximizeToWorkingAreabooltrueUses the current screen working area when maximizing so the taskbar remains visible.
EnableSnapRestoreOnDragbooltrueDragging a snapped window away restores its pre-snap size under the pointer.
TopMostboolfalseKeeps the window above non-topmost windows and synchronizes the pin state.
IsPinnedboolfalsePin-oriented wrapper around TopMost. Its setter raises IsPinnedChanged when the value changes.
PinToTopPinnedIconColorColorTheme-managedGlyph color used while IsPinned is true.

Snapping and preview

PropertyTypeDefault / rangePurpose and usage
EnableWindowSnappingbooltrueAllows edge and corner zones to be applied when a drag is released.
EnableSnapPreviewbooltrueShows the visual candidate overlay. Turning it off leaves snap behavior enabled.
SnapTriggerDistanceint12 logical px; minimum 1Distance from a working-area edge at which a zone becomes active.
SnapPreviewColorColorTheme-managed accentBase fill/accent color of the preview. Manual assignment is preserved across ordinary theme refreshes.
SnapPreviewBorderColorColorTheme-managed light accentOutline color of the preview. Manual assignment is preserved across ordinary theme refreshes.
SnapPreviewCornerRadiusint10 logical px; minimum 0Corner radius of the preview overlay.
SnapPreviewBorderThicknessint2 logical px; minimum 0Configured outline thickness of the preview.
SnapPreviewOpacitydouble0.92; clamped 0..1Peak opacity of the preview overlay.
SnapPreviewAnimationDurationint300 ms; clamped 0..2000Preview fade duration. Zero makes it appear and disappear immediately.

Control-box visibility and glyph sizing

PropertyTypeDefault / rangePurpose and usage
ShowMaximizeBoxbooltrueShows the Maximize/Restore button.
ShowMinimizeBoxbooltrueShows the Minimize button.
ShowHelpBoxbooltrueShows the Help button that raises HelpButtonClicked.
ShowCloseBoxbooltrueShows the custom Close button.
ShowPinToTopBoxbooltrueShows the Pin button.
ShowSettingsBoxbooltrueShows the Settings button that raises SettingsClicked.
CloseButtonIconSizefloat5; only values > 0 acceptedLogical radius of the Close glyph.
MaximizeButtonIconSizefloat5; only values > 0 acceptedLogical half-width of the Maximize/Restore glyph.
MinimizeButtonIconSizefloat5; only values > 0 acceptedLogical half-width of the Minimize glyph.
HelpButtonIconSizefloat2.7; only values > 0 acceptedLogical size used to construct the Help glyph.
PinButtonIconSizefloat5; only values > 0 acceptedLogical size of the Pin glyph.
SettingsButtonIconSizefloat5; only values > 0 acceptedLogical size of the Settings glyph.
ControlBoxIconStrokeWidthfloat1.8; only values > 0 acceptedLogical line thickness shared by the vector control-box glyphs.

Closing and animation

PropertyTypeDefault / rangePurpose and usage
PreventFormClosingboolfalseCancels form closing and makes the custom Close button ignore clicks while true.
EnableCloseCountdownboolfalseFirst Close-button click starts a countdown; a second click while active cancels it.
CloseCountdownDurationint5 seconds; minimum 1Starting value displayed by the Close-button countdown.
CloseCountdownFontFontSegoe UI, 9pt, BoldFont used for the countdown digits inside the Close button.
EnableCloseConfirmationboolfalseShows a Yes/No dialog for Close-button requests when countdown is disabled.
CloseConfirmationTitlestring"Confirm Close"Title of the built-in confirmation dialog.
CloseConfirmationMessagestring"Are you sure you want to close the application?"Message of the built-in confirmation dialog.
EnableFadeAnimationbooltrueEnables fade-in when shown and fade-out during the Siticone close sequence. Disable for backdrop configurations.
FadeDurationint160 ms; clamped 0..5000Duration used by both fade directions. Zero makes the transition immediate.
RotateCloseIconOnHoverboolfalseAnimates the Close glyph while the pointer hovers over it.

Per-button state colors

All 36 properties below are theme-managed initially. Assigning one property preserves that specific state color through RefreshTheme(). Use ApplyTheme(variant) when you want a theme to reclaim all of them.

Close button

StateGlyph propertyBackground property
NormalCloseButtonForeColorCloseButtonBackColor
HoverCloseButtonHoverForeColorCloseButtonHoverBackColor
PressedCloseButtonPressForeColorCloseButtonPressBackColor

Maximize / Restore button

StateGlyph propertyBackground property
NormalMaximizeButtonForeColorMaximizeButtonBackColor
HoverMaximizeButtonHoverForeColorMaximizeButtonHoverBackColor
PressedMaximizeButtonPressForeColorMaximizeButtonPressBackColor

Minimize button

StateGlyph propertyBackground property
NormalMinimizeButtonForeColorMinimizeButtonBackColor
HoverMinimizeButtonHoverForeColorMinimizeButtonHoverBackColor
PressedMinimizeButtonPressForeColorMinimizeButtonPressBackColor

Help button

StateGlyph propertyBackground property
NormalHelpButtonForeColorHelpButtonBackColor
HoverHelpButtonHoverForeColorHelpButtonHoverBackColor
PressedHelpButtonPressForeColorHelpButtonPressBackColor

Pin-to-top button

StateGlyph propertyBackground property
NormalPinToTopButtonForeColorPinToTopButtonBackColor
HoverPinToTopButtonHoverForeColorPinToTopButtonHoverBackColor
PressedPinToTopButtonPressForeColorPinToTopButtonPressBackColor

Settings button

StateGlyph propertyBackground property
NormalSettingsButtonForeColorSettingsButtonBackColor
HoverSettingsButtonHoverForeColorSettingsButtonHoverBackColor
PressedSettingsButtonPressForeColorSettingsButtonPressBackColor

Legacy control-box aliases

These public aliases remain usable for existing designer files. Prefer the explicit properties in the right column for new code.

Legacy propertyMaps toExact scope
OnHoverPinToTopIconColorPinToTopButtonHoverForeColorPin hover glyph.
OnHoverPinToTopBackColorPinToTopButtonHoverBackColorPin hover background.
OnHoverSettingsIconColorSettingsButtonHoverForeColorSettings hover glyph.
OnHoverSettingsBackColorSettingsButtonHoverBackColorSettings hover background.
OnHoverCloseIconColorCloseButtonHoverForeColorClose hover glyph.
OnHoverCloseButtonBackColorCloseButtonHoverBackColorClose hover background.
OnHoverControlIconColorMaximize, Minimize and Help hover foreground propertiesUpdates those three glyph colors together; it does not update Close, Pin, or Settings.
OnHoverControlBackColorMaximize, Minimize and Help hover background propertiesUpdates those three backgrounds together; it does not update Close, Pin, or Settings.

Read-only, hidden and compatibility properties

PropertyTypeAccess / valuePurpose and important behavior
DpiScaleFactorfloatRead only; 1 at 96 DPI or when scaling is offCurrent chrome scale relative to the 96-DPI design baseline.
IsMaximizedboolRead onlyTrue for either the standard maximized state or the control's tracked manual maximize state.
FormBorderStyleFormBorderStyleAlways NoneHidden from the designer. Assignments are forced back to FormBorderStyle.None because the control supplies its own chrome.
TextstringHidden compatibility memberSets the underlying window text but not the custom FormTitle field. Use FormTitle for the visible custom caption.
IsWindows11static boolRead onlyTrue when the detected Windows build is at least 22000.
IsBackdropSupportedstatic boolRead onlyTrue when the detected Windows build is at least 22621.
SystemAccentColorstatic ColorRead onlyCurrent Windows accent, with a safe system-highlight fallback when the platform value is unavailable.
AccentColorColorRead onlyEffective accent after applying UseSystemAccentColor.
IsDarkThemeboolRead onlyDetermined from the luminance of the effective form background, not from the variant's name.
IsBackdropActiveboolRead onlyTrue when backdrops are enabled, type is not None, and the detected Windows build supports them.
IsCompositionEnabledboolRead onlyReports whether desktop window composition was available when the window creation parameters were evaluated.
EnableSnapLayoutsboolfalse; no effectDesigner-hidden compatibility property retained so older generated code still compiles. Use EnableWindowSnapping; native Windows 11 caption Snap Layouts are not provided by this borderless style.

Complete public method reference

MethodReturnsWhat it doesTypical call
RefreshTheme()voidReapplies the current theme to every color that is not marked as manually customized, then updates the window when its handle exists.RefreshTheme();
ApplyTheme(FormThemeVariant)voidClears all manual color customization flags, selects the supplied variant, and applies it immediately.ApplyTheme(selectedTheme);
ResetColorCustomizations()voidReturns ownership of all theme-managed colors to the theme engine. Call RefreshTheme()ResetColorCustomizations();
IsSystemInDarkMode()static boolReads the Windows app light/dark preference. Returns false when the preference is unavailable.bool dark = SiticoneForm.IsSystemInDarkMode();
SyncWithSystemTheme()voidRe-evaluates the configured Windows theme and accent options, then reapplies backdrop state.SyncWithSystemTheme();
ResolveSnapZone(Point, out Rectangle)FormSnapZoneEvaluates a screen-coordinate pointer location and returns its candidate zone plus target bounds without moving the form.FormSnapZone zone = ResolveSnapZone(point, out bounds);
SnapTo(FormSnapZone)voidApplies a supported zone using the working area of the screen currently hosting the form. None is ignored.SnapTo(FormSnapZone.Left);
SaveWindowPlacement()stringSerializes normal bounds and maximized state into a compact, culture-independent, versioned token.string token = SaveWindowPlacement();
RestoreWindowPlacement(string)boolValidates and restores a saved token. Returns false for malformed, unsupported, invalid-size, or off-screen data.bool restored = RestoreWindowPlacement(token);
ToggleMaximizeState()voidMoves between normal and maximized state while retaining normal bounds and raising MaximizeStateChanged.ToggleMaximizeState();
Close()voidStarts the Siticone close sequence directly. It bypasses the Close-button countdown, confirmation dialog, and custom FormClosing event.Close();
RefreshAppearance()voidRecalculates control-box metrics and visibility, then repaints the control box and form.RefreshAppearance();

Apply user-selected theme and chrome settings together

C# — settings-screen integration
private void ApplyWindowSettings(
    FormThemeVariant theme,
    bool showHelp,
    bool showSettings,
    int titleHeight)
{
    ApplyTheme(theme);

    ShowHelpBox = showHelp;
    ShowSettingsBox = showSettings;
    TitleBarHeight = titleHeight;

    RefreshAppearance();
}

Public enums and support types

TypePublic membersPurpose
SiticoneFormSiticoneForm()The enhanced borderless Form documented on this page.
FormSnapZoneNone, Maximize, Left, Right, TopLeft, TopRight, BottomLeft, BottomRightIdentifies a drag or programmatic snap destination. Values and behavior are listed in Window snapping.
FormBackdropTypeNone, Auto, Mica, Acrylic, MicaAltIdentifies the requested Windows 11 system material. Values are listed in Windows 11 backdrops.
FormSnapEventArgsFormSnapEventArgs(FormSnapZone zone, Rectangle bounds), Zone, BoundsEvent data for SnapZoneChanged and Snapped.
SiticoneForm.IsPinnedChangedEventArgsIsPinnedChangedEventArgs(bool isPinned), IsPinnedEvent data for IsPinnedChanged.
SiticoneForm.MarginsPublic integer fields: Left, Right, Top, BottomPublic frame-margin data structure retained for backward compatibility. Normal form configuration does not require it.

FormSnapEventArgs

MemberTypeMeaning
ZoneFormSnapZoneCandidate or completed zone associated with the event.
BoundsRectangleProposed or applied screen bounds. A candidate change to None uses an empty rectangle.
FormSnapEventArgs(FormSnapZone, Rectangle)constructorCreates event data from a zone and its associated bounds.

IsPinnedChangedEventArgs

MemberTypeMeaning
IsPinnedboolNew pin state after the public IsPinned value changes.
IsPinnedChangedEventArgs(bool)constructorCreates the event data from the new state.
FormThemeVariant is referenced but not declared by the supplied SiticoneForm source file

It comes from SiticoneNetFrameworkUI.Helpers.FormTheme. This page intentionally does not invent enum values that were not present in the supplied source. The documented, source-proven default is FormThemeVariant.LightDefault; select other values through IntelliSense for your installed version.

More complete recipes

Compact modal dialog

C# — modal window without unnecessary actions
public ConfirmationWindow()
{
    InitializeComponent();

    FormTitle = "Confirm changes";
    StartPosition = FormStartPosition.CenterParent;

    ShowMaximizeBox = false;
    ShowMinimizeBox = false;
    ShowHelpBox = false;
    ShowPinToTopBox = false;
    ShowSettingsBox = false;
    ShowCloseBox = true;

    EnableFormResizing = false;
    EnableTitleBarDoubleClick = false;
    EnableWindowSnapping = false;
}

Always-on-top utility window

C# — pin-capable utility window
public NotesWindow()
{
    InitializeComponent();

    FormTitle = "Quick notes";
    ShowPinToTopBox = true;
    ShowSettingsBox = false;
    ShowHelpBox = false;
    ShowMaximizeBox = false;

    IsPinned = Properties.Settings.Default.NotesWindowPinned;
}

Fixed-size appliance or kiosk window

C# — disable user-driven window geometry changes
EnableFormResizing = false;
EnableWindowSnapping = false;
EnableTitleBarDoubleClick = false;

ShowMaximizeBox = false;
ShowMinimizeBox = false;

MinimumSize = Size;
MaximumSize = Size;

Windows-aware modern window with fallback

C# — system theme, accent and optional Mica
private void ConfigureModernWindowsAppearance()
{
    FollowSystemTheme = true;
    UseSystemAccentColor = true;
    UseRoundedCorners = true;

    if (SiticoneForm.IsBackdropSupported)
    {
        EnableFadeAnimation = false;
        EnableBackdrop = true;
        BackdropType = FormBackdropType.Mica;
    }
    else
    {
        EnableBackdrop = false;
        BackdropType = FormBackdropType.None;
        EnableFadeAnimation = true;
    }

    SyncWithSystemTheme();
}

Restore placement before the first show

C# — avoid visible repositioning
public MainWindow()
{
    InitializeComponent();

    string placement = Properties.Settings.Default.MainWindowPlacement;

    if (!RestoreWindowPlacement(placement))
    {
        StartPosition = FormStartPosition.CenterScreen;
    }

    FormClosed += MainWindow_FormClosed;
}

private void MainWindow_FormClosed(object sender, FormClosedEventArgs e)
{
    Properties.Settings.Default.MainWindowPlacement = SaveWindowPlacement();
    Properties.Settings.Default.Save();
}

Custom theme with a system-colored snap preview

C# — combine manual chrome and Windows accent
EnableThemeEngine = false;

BackColor = Color.FromArgb(16, 18, 24);
ForeColor = Color.White;
TitleBarBackColor = Color.FromArgb(8, 10, 14);
TitleBarForeColor = Color.White;

UseSystemAccentColor = true;
SyncWithSystemTheme();

Color accent = AccentColor;
PinToTopPinnedIconColor = accent;

Keyboard commands for common window layouts

C# — override ProcessCmdKey
protected override bool ProcessCmdKey(ref Message msg, Keys keyData)
{
    if (keyData == (Keys.Control | Keys.Alt | Keys.Left))
    {
        SnapTo(FormSnapZone.Left);
        return true;
    }

    if (keyData == (Keys.Control | Keys.Alt | Keys.Right))
    {
        SnapTo(FormSnapZone.Right);
        return true;
    }

    if (keyData == (Keys.Control | Keys.Alt | Keys.Enter))
    {
        ToggleMaximizeState();
        return true;
    }

    return base.ProcessCmdKey(ref msg, keyData);
}

Apply a batch of visual changes without leaving stale chrome

C# — batch update
private void UseCompactChrome()
{
    SuspendLayout();

    try
    {
        TitleBarHeight = 34;
        ControlBoxButtonWidth = 48;
        IconSize = 18;
        ShowHelpBox = false;
        ShowSettingsBox = false;
    }
    finally
    {
        ResumeLayout(true);
        RefreshAppearance();
    }
}

Troubleshooting and common questions

Question or symptomWhat to check
The form looks themed in the designer but uses unexpected colors at runtime.Confirm the class inherits SiticoneForm, EnableThemeEngine is true, and theme selection occurs after InitializeComponent(). Designer-generated manual color assignments can intentionally remain customized. Call ApplyTheme(ThemeVariant) after initialization when the selected variant must reclaim every color.
My manual BackColor is replaced when I switch themes.Set BackColorCustomizable = true before assigning the background. ForceThemeBackColorOverride defaults to true and normally lets a new variant reclaim BackColor and ForeColor.
A custom button color does not change when ThemeVariant changes.Manual assignments are preserved by design. Use ApplyTheme(newVariant), or call ResetColorCustomizations() followed by RefreshTheme().
The title text did not change after assigning Text.Assign FormTitle. The compatibility Text property does not update the custom title field.
Control-box icons look too small on a high-DPI screen.Keep EnableDpiScaling = true, use a multi-size Icon, and tune the logical per-button icon-size properties rather than multiplying them by DPI yourself. ControlBoxIconStrokeWidth controls line weight.
The Mica or Acrylic material is not visible.Check SiticoneForm.IsBackdropSupported, set EnableBackdrop = true, select a non-None BackdropType, normally leave AutoBackdropBackColor = true, and disable fade animation.
The native Windows 11 Snap Layouts flyout does not appear.This control uses a borderless style. EnableSnapLayouts is a no-effect compatibility property. Use EnableWindowSnapping for the control's drag-to-edge and corner layouts.
Snapping works but no preview appears.Set EnableSnapPreview = true. Preview visibility and actual snapping are separate switches.
The confirmation dialog does not appear.EnableCloseCountdown takes precedence. Also, calling the public Close() method starts the close sequence directly rather than running Close-button confirmation.
My custom FormClosing handler is not called after a countdown or Close().This is the documented scope of the custom shadowing event. Disable countdown for that Close-button event, or use inherited FormClosed for notification after every successful close.
IsPinnedChanged did not fire when I assigned TopMost.Assign IsPinned when you need IsPinnedChanged. The TopMost setter synchronizes state and visuals without raising that custom event.
A saved placement is ignored.The token must come from SaveWindowPlacement(), contain a valid positive size, use the supported version, and remain meaningfully visible on a connected monitor. Treat a false return as a request to use your normal StartPosition.
The border cannot be changed from None.This is intentional. FormBorderStyle is forced to None because SiticoneForm supplies the title bar, control box, resizing, shadow, and window interaction itself.

Runtime theme recovery pattern

C# — guarantee the selected theme after designer initialization
public MainWindow()
{
    InitializeComponent();

    FormThemeVariant selectedTheme = ThemeVariant;
    ApplyTheme(selectedTheme);
}

private void restoreThemeButton_Click(object sender, EventArgs e)
{
    ResetColorCustomizations();
    RefreshTheme();
}
A useful rule of thumb

Use ThemeVariant or RefreshTheme() when custom colors should survive. Use ApplyTheme(variant) when the theme must replace every custom color. Use RefreshAppearance() when dimensions or visibility changed but the selected theme did not.

Back to top