Added PowerInfo

src/KappaDuck.Quack/Interop/SDL/SDL3.System.cs

@@ -1,10 +1,16 @@
 // Copyright (c) KappaDuck.
 // Licensed under the MIT license.
 
+using KappaDuck.Quack.System;
+
 namespace KappaDuck.Quack.Interop.SDL;
 
 internal static partial class SDL3
 {
+    [LibraryImport(nameof(SDL3), EntryPoint = "SDL_GetPowerInfo")]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial PowerState GetPowerInfo(out int seconds, out int percent);
+
     [LibraryImport(nameof(SDL3), EntryPoint = "SDL_OpenURL", StringMarshalling = StringMarshalling.Utf8)]
     [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
     [return: MarshalAs(UnmanagedType.U1)]

src/KappaDuck.Quack/System/PowerInfo.cs

@@ -0,0 +1,86 @@
+// Copyright (c) KappaDuck.
+// Licensed under the MIT license.
+
+namespace KappaDuck.Quack.System;
+
+/// <summary>
+/// Provides a snapshot of the system's power supply, e.g. laptop battery status.
+/// </summary>
+public readonly record struct PowerInfo
+{
+    private PowerInfo(PowerState state, int? percentage, TimeSpan? remaining)
+    {
+        State = state;
+        Percentage = percentage;
+        Remaining = remaining;
+    }
+
+    /// <summary>
+    /// Gets a snapshot of the current power supply.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// You should never take the power status for granted. Batteries (especially failing ones) can
+    /// report incorrect values, and the values reported here are best estimates based on what the
+    /// hardware reports. It's not uncommon for older batteries to lose stored power much faster than
+    /// reported, or completely drain when reporting it has 20% left, etc.
+    /// </para>
+    /// <para>
+    /// Battery status can change at any time, so if your application depends on accurate power status,
+    /// refresh the values by reading this property again, and perhaps ignore changes until they seem
+    /// stable for a few seconds. A platform may only report battery percentage or time left, not both.
+    /// </para>
+    /// <para>
+    /// On some platforms retrieving power details can be expensive; for continuous display, read it
+    /// about once a minute rather than every frame.
+    /// </para>
+    /// </remarks>
+    public static PowerInfo Current
+    {
+        get
+        {
+            PowerState state = SDL3.GetPowerInfo(out int seconds, out int percent);
+
+            int? percentage = percent < 0 ? null : percent;
+            TimeSpan? remaining = seconds < 0 ? null : TimeSpan.FromSeconds(seconds);
+
+            return new PowerInfo(state, percentage, remaining);
+        }
+    }
+
+    /// <summary>
+    /// Gets the power state of the system.
+    /// </summary>
+    public PowerState State { get; }
+
+    /// <summary>
+    /// Gets the battery charge between 0 and 100, or <see langword="null"/> if it can't be determined.
+    /// </summary>
+    public int? Percentage { get; }
+
+    /// <summary>
+    /// Gets the estimated battery life remaining, or <see langword="null"/> if it can't be determined.
+    /// </summary>
+    public TimeSpan? Remaining { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether the system is running on battery (not plugged in).
+    /// </summary>
+    public bool IsOnBattery => State == PowerState.OnBattery;
+
+    /// <summary>
+    /// Gets a value indicating whether the battery is charging.
+    /// </summary>
+    public bool IsCharging => State == PowerState.Charging;
+
+    /// <summary>
+    /// Gets a value indicating whether the battery is fully charged.
+    /// </summary>
+    public bool IsCharged => State == PowerState.Charged;
+
+    /// <summary>
+    /// Gets a value indicating whether a battery is present.
+    /// </summary>
+    public bool HasBattery => State is PowerState.OnBattery or PowerState.Charging or PowerState.Charged;
+
+}

src/KappaDuck.Quack/System/PowerState.cs

@@ -0,0 +1,40 @@
+// Copyright (c) KappaDuck.
+// Licensed under the MIT license.
+
+namespace KappaDuck.Quack.System;
+
+/// <summary>
+/// Represents the current power state.
+/// </summary>
+public enum PowerState
+{
+    /// <summary>
+    /// An error occurred while determining the power state.
+    /// </summary>
+    Error = -1,
+
+    /// <summary>
+    /// The power state could not be determined (e.g., no battery).
+    /// </summary>
+    Unknown = 0,
+
+    /// <summary>
+    /// The system is running on battery power.
+    /// </summary>
+    OnBattery = 1,
+
+    /// <summary>
+    /// The system is plugged in but does not have a battery available.
+    /// </summary>
+    NoBattery = 2,
+
+    /// <summary>
+    /// The system is plugged in and charging the battery.
+    /// </summary>
+    Charging = 3,
+
+    /// <summary>
+    /// The system is plugged in and the battery is fully charged.
+    /// </summary>
+    Charged = 4
+}