ZposDesktop 1.1.0

ZposDesktop

A Windows library that allows applications to keep their windows visible when the user activates "Show Desktop" (Win+D or taskbar button). Perfect for overlay applications, desktop widgets, monitoring tools, and other utilities that should remain accessible even when the desktop is shown.

Features

• 🖥️ Show Desktop Bypass: Keep your windows visible when users press Win+D or click "Show Desktop"
• 🔄 Smart Detection: Automatically detects desktop state changes across Windows versions
• 🎯 Selective Control: Register only specific windows that need to stay visible
• 📱 Multi-Version Support: Works on Windows 10, 11, and handles 24H2+ changes automatically
• 🧩 Easy Integration: Simple C# wrapper with P/Invoke declarations included
• 🔧 Automatic Cleanup: Built-in resource management and cleanup helpers

Quick Start

1. Build the Library

# Clone the repository
git clone https://github.com/yourusername/ZposDesktop.git
cd ZposDesktop

# Build using Visual Studio or MSBuild
msbuild ZposDesktop.sln /p:Configuration=Release

2. Basic Usage (C#)

using ZposDesktop;

// Initialize the library (call once at startup)
if (ZposDesktopHelper.InitializeWithAutoCleanup())
{
    // Register your main form to stay visible during "Show Desktop"
    ZposDesktopHelper.RegisterFormWithAutoCleanup(this);
    
    // Optional: Get notified when desktop state changes
    ZposDesktop.SetDesktopStateCallback(OnDesktopStateChanged);
}

private static void OnDesktopStateChanged(DesktopState state)
{
    Console.WriteLine($"Desktop state changed to: {state}");
}

3. Manual Control

// Initialize
ZposDesktop.Initialize();

// Register specific windows
ZposDesktop.RegisterWindow(myForm);
ZposDesktop.RegisterWindow(anotherWindow.Handle);

// Check current state
var currentState = ZposDesktop.GetDesktopState();
if (currentState == DesktopState.ShowingDesktop)
{
    // Desktop is currently being shown
}

// Cleanup when done
ZposDesktop.Shutdown(); // Note: renamed from Finalize

How It Works

ZposDesktop works by:

1. Monitoring Desktop State: Uses Windows event hooks to detect when "Show Desktop" is activated
2. Z-Order Management: Manipulates window Z-order to position registered windows appropriately
3. Version Compatibility: Adapts its behavior based on Windows version and desktop composition changes
4. Resource Tracking: Maintains a registry of managed windows and their states

The library creates invisible helper windows that act as Z-order anchors, ensuring your registered windows appear in the correct layer when the desktop is shown.

Architecture

• ZposDesktop.dll: Native C++ library that handles Windows API interactions
• ZposDesktop.cs: C# wrapper providing easy .NET integration
• Helper Classes: Automatic resource management and cleanup utilities

API Reference

Core Methods

Desktop States

• ShowingWindows: Normal state, all windows visible
• ShowingDesktop: Desktop is being shown, registered windows stay visible

Helper Methods

• ZposDesktopHelper.InitializeWithAutoCleanup(): Initialize with automatic cleanup on app exit
• ZposDesktopHelper.RegisterFormWithAutoCleanup(form): Register form with automatic cleanup on dispose

System Requirements

• OS: Windows 10 or later
• Framework: .NET Framework 4.5+ or .NET 5+
• Architecture: x64 (can be adapted for x86)

Use Cases

Desktop Widgets

// Perfect for weather widgets, system monitors, etc.
public partial class WeatherWidget : Form
{
    protected override void SetVisibleCore(bool value)
    {
        base.SetVisibleCore(value);
        if (value && !ZposDesktop.IsWindowRegistered(this))
        {
            ZposDesktop.RegisterWindow(this);
        }
    }
}

Overlay Applications

// For gaming overlays, screen annotation tools, etc.
public class GameOverlay : Form
{
    public GameOverlay()
    {
        InitializeComponent();
        this.TopMost = true;
        this.ShowInTaskbar = false;
        
        // Stay visible even during "Show Desktop"
        ZposDesktop.RegisterWindow(this);
    }
}

Monitoring Tools

// For system monitoring, network tools, etc.
public class SystemMonitor : Form
{
    private void SystemMonitor_Load(object sender, EventArgs e)
    {
        // Register to stay accessible
        ZposDesktop.RegisterWindow(this);
        
        // Monitor desktop state changes
        ZposDesktop.SetDesktopStateCallback(state =>
        {
            this.Invoke(() =>
            {
                // Update UI based on desktop state
                statusLabel.Text = $"Desktop State: {state}";
            });
        });
    }
}

Building from Source

Prerequisites

• Visual Studio 2019 or later
• Windows 10 SDK
• .NET development workload

Build Steps

1. Open ZposDesktop.sln in Visual Studio
2. Select your target configuration (Debug/Release)
3. Build Solution (Ctrl+Shift+B)
4. Output files will be in bin/Release or bin/Debug

Project Structure

ZposDesktop/
├── ZposDesktop.cpp          # Main implementation
├── ZposDesktop.h            # C++ header
├── ZposDesktop.cs           # C# wrapper
├── dllmain.cpp              # DLL entry point
├── framework.h              # Windows headers
├── pch.h/cpp                # Precompiled headers
└── ZposDesktop.sln          # Visual Studio solution

Troubleshooting

Common Issues

DLL not found

• Ensure ZposDesktop.dll is in the same directory as your executable
• Check that you're using the correct architecture (x64 vs x86)

Windows not staying visible

• Verify the window is properly registered with IsWindowRegistered()
• Check that initialization was successful
• Some window types may not be compatible (e.g., certain system dialogs)

Performance issues

• The library uses minimal resources, but avoid registering/unregistering windows frequently
• Use the callback system instead of polling GetDesktopState()

Debug Mode

Build in Debug configuration for additional logging and error checking.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Windows desktop management techniques inspired by various Windows internals resources
• Thanks to the community for testing across different Windows versions