Siticone TaskbarStateController

The SiticoneTaskbarStateController is a powerful non-visual component designed to manipulate the Windows Taskbar directly from your WinForms application. It provides programmatic control over taskbar visibility, auto-hide behaviors, grouping modes, and system theme settings, allowing for immersive fullscreen experiences or custom desktop environments.

Behavior & State

Properties controlling the primary state and behavior of the Windows Taskbar.

Property	Type	Description & Usage Example
`IsAutoHide`	bool	taskbarCtrl.IsAutoHide = true; Determines if the taskbar automatically hides when not in use. Setting this property modifies the Windows user settings immediately.
`IsVisible`	bool	taskbarCtrl.IsVisible = false; Shows or hides the entire taskbar window. Useful for creating kiosk modes or immersive full-screen applications.
`GroupingMode`	TaskbarGroupingMode	taskbarCtrl.GroupingMode = TaskbarGroupingMode.Never; Controls how taskbar buttons are grouped (Always, WhenFull, or Never).
`LockTaskbarChanges`	bool	taskbarCtrl.LockTaskbarChanges = true; Temporarily locks state changes. When true, setting properties like IsAutoHide or GroupingMode will not trigger system updates or events.

Read-Only Information

Properties that provide information about the current physical state of the taskbar.

Property	Type	Description
`Bounds`	Rectangle	Rectangle r = taskbarCtrl.Bounds; Gets the current bounding rectangle (position and dimensions) of the taskbar on the screen.
`Size`	Size	Size s = taskbarCtrl.Size; Gets the current width and height of the taskbar.
`TaskbarHandle`	IntPtr	IntPtr hWnd = taskbarCtrl.TaskbarHandle; Gets the native window handle (HWND) of the Windows Taskbar ("Shell_TrayWnd"). Useful for advanced P/Invoke operations.

Public Methods

Methods for interacting with the taskbar, refreshing state, and applying system-wide settings.

ShowTaskbar() / HideTaskbar()

// Temporarily hides the taskbar to maximize screen real estate.
public void ToggleImmersiveMode(bool enable)
{
                if (enable)
    {
        taskbarCtrl.HideTaskbar();
    }
                else
    {
                // Force the taskbar to reappear if it was hidden or auto-hidden
        taskbarCtrl.ShowTaskbar();
    }
}

Use these methods to programmatically toggle the visibility of the taskbar window.

FlashTaskbar(int duration)

// Flashes the taskbar to draw the user's attention.
// Useful for notifications when your application is not in focus.
// The duration parameter specifies how long (in ms) the flash effect lasts.
taskbarCtrl.FlashTaskbar(1000);

ApplySettings(bool isAutoHide)

// Applies basic taskbar settings in a single batch operation.
// Returns true if the operation was successful.
bool success = taskbarCtrl.ApplySettings(true); // Enable Auto-Hide

SetThemeMode(TaskbarThemeMode theme)

// Modifies the Windows system theme setting for apps and taskbar.
// Can switch between Light, Dark, or System Default.
taskbarCtrl.SetThemeMode(TaskbarThemeMode.Dark);

Additional Utilities

Method	Description
`RefreshTaskbarState()`	Queries the OS for the current taskbar configuration and updates the component's properties (`IsVisible`, `IsAutoHide`, `GroupingMode`). Call this if settings might have been changed externally.
`IsTaskbarCurrentlyVisible()`	Returns a boolean indicating if the taskbar window is effectively visible to the user, checking the actual window style flags.
`GetTaskbarScreen()`	Returns the `Screen` object where the taskbar is currently located (useful for multi-monitor setups).
`GetWorkingArea()`	Returns the `Rectangle` representing the screen's working area (screen bounds minus taskbar).
`BackupSettings()`	Creates a `TaskbarSettings` object capturing the current state. Useful for restoring state after your app closes.
`RestoreDefaults()`	Resets the taskbar to standard Windows defaults (Visible, No Auto-Hide).

Events

Comprehensive event system for monitoring state changes and errors.

Event Handling

// 1. TaskbarStateChanged
// Fires when any major property (AutoHide, Visibility, Grouping) changes.
taskbarCtrl.TaskbarStateChanged += (s, e) => 
{
                Console.WriteLine($"Taskbar state changed: {e.ChangeType}");
};

// 2. TaskbarStateChanging
// Fires BEFORE a change occurs. Allows you to cancel the operation.
taskbarCtrl.TaskbarStateChanging += (s, e) => 
{
                if (e.ChangeType == TaskbarChangeType.Visibility)
    {
                // Prevent the taskbar from being hidden
        e.Cancel = true;
    }
};

// 3. TaskbarError
// Fires when a Win32 API call fails or permission is denied.
taskbarCtrl.TaskbarError += (s, e) => 
{
                MessageBox.Show($"Error: {e.Message}\nDetails: {e.Exception?.Message}");
};

Enumerations

Enumerations used by the controller for configuration.

TaskbarGroupingMode Enum

public enum TaskbarGroupingMode
{
                // Always group similar taskbar buttons (Default Windows behavior).
    Always = 0,
    
                // Group taskbar buttons only when the taskbar is full.
    WhenFull = 1,
    
                // Never group taskbar buttons; always show labels.
    Never = 2
}

TaskbarThemeMode Enum

public enum TaskbarThemeMode
{
                // Resets to Windows default theme settings.
    Default = 0,
    
                // Forces Light theme for System and Apps.
    Light = 1,
    
                // Forces Dark theme for System and Apps.
    Dark = 2,
    
                // Custom theme configuration (reserved for future use).
    Custom = 3
}

Detailed Usage Examples

Example 1: Immersive Gaming/Kiosk Mode

This example demonstrates how to create a "Focus Mode" that hides the taskbar when your application starts and restores it when the application closes. It includes error handling and state backup to ensuring the user's desktop isn't left in a broken state.

C# - Immersive Mode

private TaskbarSettings _originalSettings;

// Call this when your form loads or "Focus Mode" is activated
private void EnterFocusMode()
{
                try 
    {
                // 1. Backup current settings so we can restore them later
        _originalSettings = siticoneTaskbarStateController1.BackupSettings();

                // 2. Hide the taskbar completely
        siticoneTaskbarStateController1.IsVisible = false;
        
                // 3. Optional: Set Auto-Hide as a fallback
        siticoneTaskbarStateController1.IsAutoHide = true;
    }
                catch (Exception ex)
    {
                MessageBox.Show("Failed to enter focus mode: " + ex.Message);
    }
}

// Call this when your form closes
private void ExitFocusMode()
{
                if (_originalSettings != null)
    {
                // 4. Restore the user's original desktop configuration
        siticoneTaskbarStateController1.RestoreSettings(_originalSettings);
    }
                else
    {
                // Fallback if backup failed
        siticoneTaskbarStateController1.ShowTaskbar();
    }
}

Example 2: Intelligent Notification System

Use the taskbar controller to grab the user's attention when a long-running background process completes.

C# - Taskbar Notification

private async void StartLongProcess_Click(object sender, EventArgs e)
{
                // Start a heavy task
                await Task.Delay(5000); 

                // Process Complete!
    
                // Check if the taskbar is currently visible. 
                // If not (e.g., user is watching a movie), momentarily show it.
                if (!taskbarCtrl.IsTaskbarCurrentlyVisible())
    {
        taskbarCtrl.ShowTaskbar();
                // Wait briefly for the animation
                await Task.Delay(500);
    }

                // Flash the taskbar 3 times (default logic) for 1 second
    taskbarCtrl.FlashTaskbar(1000);
    
                MessageBox.Show("Export completed successfully!");
}

Example 3: System Theme Manager

Create a simple utility to toggle the entire Windows System theme between Light and Dark mode directly from your app.

C# - Theme Switcher

private void BtnToggleTheme_Click(object sender, EventArgs e)
{
                // Toggle between Dark and Light mode
                if (toggleSwitch.Checked)
    {
                // Switch Windows to Dark Mode
        taskbarCtrl.SetThemeMode(TaskbarThemeMode.Dark);
        lblStatus.Text = "System Theme: Dark";
    }
                else
    {
                // Switch Windows to Light Mode
        taskbarCtrl.SetThemeMode(TaskbarThemeMode.Light);
        lblStatus.Text = "System Theme: Light";
    }
}