Native wallpaper platform API bindings for desktop apps.

moonbit

native

wallpaper

moon add justjavac/wallpaper@0.1.3

Download zip

Author

justjavac

Version

0.1.3

License

MIT

Repository

github.com/justjavac/moonbit-wallpaper

Last updated

2 months ago

Downloads

Dependencies

justjavac/ffi0.2.3
justjavac/platform0.1.2

README

#justjavac/wallpaper

Native-only MoonBit bindings for desktop wallpaper platform APIs. No shell commands are used.

let status = @wallpaper.apply_current(
  "/home/alice/Pictures/wallpaper.jpg",
  @wallpaper.WallpaperMode::Fill,
)

#
WallpaperMode

source

pub(all) enum WallpaperMode {
  Fill
  Fit
  Stretch
  Center
  Span
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

How the wallpaper should be fitted to the desktop.

Windows maps these values to WallpaperStyle and TileWallpaper, and Linux maps them to GNOME picture-options. macOS currently applies the image source only because AppKit does not expose a matching cross-version layout mode in the API used by this package.

Choose the mode that best matches the desktop behavior you want. Fill is the package default for examples because it maps to common "cover the screen" behavior on Windows and GNOME. Fit preserves the whole image, Stretch may distort it, Center leaves the image at its natural size, and Span is intended for multi-monitor layouts where the platform supports that concept.

Example

test {
  inspect(@wallpaper.WallpaperMode::Fill.to_string(), content="Fill")
  inspect(@wallpaper.WallpaperMode::Span.to_string(), content="Span")
}

impl Show for WallpaperMode

fn output(self : WallpaperMode, logger : &Logger) -> Unit

source

Render a wallpaper layout mode using the same spelling as its enum constructor.

The output is intended for diagnostics and examples. Platform-specific tokens such as Windows registry values or GNOME picture-options strings remain private implementation details and are not exposed through Show.

Example

test {
  inspect(@wallpaper.WallpaperMode::Fill.to_string(), content="Fill")
}

#
WallpaperRequest

source

pub(all) struct WallpaperRequest {
  platform : @justjavac/platform.Os
Os
  source : String
  mode : WallpaperMode
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A request to apply a wallpaper through a specific platform API.

platform uses justjavac/platform directly. Windows, MacOS, and Linux select the corresponding native implementation, while UnknownOs returns UnsupportedPlatform.

source is expected to be an absolute local file path for Windows and macOS. For Linux the binding accepts either an absolute path or an existing file:// URI and normalizes plain paths to the URI form expected by GNOME GSettings.

Construct a request when you already know which platform branch you want to exercise, such as in a desktop app that stores a target OS in configuration or in tests that need deterministic status handling. Most applications can use apply_current instead, which fills platform from @platform.os().

Example

test {
  let request : @wallpaper.WallpaperRequest = {
    platform: UnknownOs,
    source: "/tmp/wallpaper.jpg",
    mode: Fit,
  }
  inspect(@wallpaper.apply(request), content="UnsupportedPlatform")
}

impl Show for WallpaperRequest

fn output(self : WallpaperRequest, logger : &Logger) -> Unit

source

Render a wallpaper request with all public fields visible.

This is useful while debugging application flows because it includes the requested platform, source string, and layout mode in one value. The format follows the derived Debug representation and should be treated as diagnostic text rather than a serialization format.

Example

test {
  let request : @wallpaper.WallpaperRequest = {
    platform: Linux,
    source: "/tmp/wallpaper.jpg",
    mode: Fit,
  }
  inspect(
    request.to_string(),
    content="{ platform: Linux, source: \"/tmp/wallpaper.jpg\", mode: Fit }",
  )
}

#
WallpaperStatus

source

pub(all) enum WallpaperStatus {
  Applied
  UnsupportedPlatform
  UnsupportedDesktop
  InvalidSource
  NativeFailure
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Result of applying a wallpaper request through the platform API.

Applied means the platform API accepted the request. UnsupportedPlatform is returned for UnknownOs or an operating system without an implementation. UnsupportedDesktop is used when the OS is supported but the expected desktop service is unavailable, such as GNOME GSettings on Linux. InvalidSource means the source path was empty. NativeFailure means the platform API was present but rejected the update.

Match on the status when callers need distinct fallback behavior, or use WallpaperStatus::is_success when a boolean branch is enough. The function APIs return statuses instead of raising so UI code can decide whether to retry, show a platform-specific message, or ignore unsupported desktops.

Example

test {
  inspect(@wallpaper.WallpaperStatus::Applied.is_success(), content="true")
  inspect(
    @wallpaper.WallpaperStatus::UnsupportedDesktop.is_success(),
    content="false",
  )
}

impl Show for WallpaperStatus

fn output(self : WallpaperStatus, logger : &Logger) -> Unit

source

Render a wallpaper status using the same spelling as its enum constructor.

The output is useful for logs and user-facing fallback messages when native APIs are unavailable or reject an update. Use WallpaperStatus::is_success when code needs a boolean success branch.

Example

test {
  inspect(
    @wallpaper.WallpaperStatus::UnsupportedPlatform.to_string(),
    content="UnsupportedPlatform",
  )
}

#
WallpaperStatus::is_success

source

fn WallpaperStatus::is_success(self : WallpaperStatus) -> Bool

Return whether a wallpaper status represents a successful update.

This helper is useful when callers want a boolean branch while still keeping the detailed status available for logging or user messages.

Only Applied is considered successful. Unsupported platforms, unsupported desktops, validation failures, and native API rejections all return false so callers can handle every non-applied outcome through one fallback branch when detailed recovery is not needed.

Example

test {
  inspect(@wallpaper.WallpaperStatus::Applied.is_success(), content="true")
  inspect(
    @wallpaper.WallpaperStatus::NativeFailure.is_success(),
    content="false",
  )
}

#
apply

source

fn apply(request : WallpaperRequest) -> WallpaperStatus

Apply a wallpaper request through the target platform API.

No shell commands or script runners are used. Windows calls Win32 APIs, macOS calls AppKit through the Objective-C runtime, and Linux calls GNOME GSettings through GIO. The function returns a WallpaperStatus instead of raising so desktop applications can decide how to surface native failures.

source must be non-empty. Windows and macOS expect a local filesystem path. Linux accepts either a local path or a file:// URI; plain paths are normalized before entering the GSettings API. A request whose platform is UnknownOs never reaches a desktop API and returns UnsupportedPlatform.

Example

test {
  let request : @wallpaper.WallpaperRequest = {
    platform: UnknownOs,
    source: "/tmp/wallpaper.jpg",
    mode: Fill,
  }
  inspect(@wallpaper.apply(request), content="UnsupportedPlatform")
}

#
apply_current

source

fn apply_current(source : String, mode : WallpaperMode) -> WallpaperStatus

Apply a wallpaper source on the current operating system.

This is a convenience wrapper around justjavac/platform.os and apply. It has the same side effects as apply, so callers should pass a real local image path and be prepared to handle a non-Applied status.

Use this for the common case where the application wants to apply a wallpaper to the machine it is running on. It performs the same empty-source validation as apply before any native desktop API is called.

Example

test {
  inspect(@wallpaper.apply_current("", Center), content="InvalidSource")
}

#
supports_platform

source

fn supports_platform(platform : @justjavac/platform.Os
Os) -> Bool

Return whether an operating system has a native apply implementation.

Windows uses Win32 user and registry APIs, macOS uses AppKit through the Objective-C runtime, and Linux uses GNOME GSettings through the GIO C API. UnknownOs is always unsupported.

This checks only whether the package has code for the operating system. It does not verify a specific desktop session, image path, permissions, or user settings service. On Linux, for example, this returns true for the OS even though apply may later return UnsupportedDesktop when GNOME GSettings is unavailable.

Example

test {
  inspect(@wallpaper.supports_platform(Linux), content="true")
  inspect(@wallpaper.supports_platform(UnknownOs), content="false")
}

Source Files

Site source Report issue Packages Build queue Skills Statistics

wallpaper

#justjavac/wallpaper

#WallpaperMode

Example

Example

#WallpaperRequest

Example

Example

#WallpaperStatus

Example

Example

#WallpaperStatus::is_success

Example

#apply

Example

#apply_current

Example

#supports_platform

Example

Source Files

#
WallpaperMode

#
WallpaperRequest

#
WallpaperStatus

#
WallpaperStatus::is_success

#
apply

#
apply_current

#
supports_platform