WallRizz Documentation

The WallRizz class uses parseArguments() to populate its config object. The behavior of the run() method is determined by several configuration flags. Based on the run() implementation, the following flags trigger specific workflows:

• showKeyMap: Displays keymaps via UserInterface.printKeyMaps() and exits.
• update: Checks for application updates via checkForUpdate() and exits.
• test: Runs extension tests via testExtensions() and exits.
• downloadThemeExtensionScripts: Triggers the ThemeExtensionScriptsDownloadManager to initialize.
• downloadWallpaperDaemonHandlerScript: Triggers the WallpaperDaemonHandlerScriptDownloadManager to initialize.
• inspection: If truthy, the application configuration is printed to the console upon completion.

The Theme class relies on an external command to extract colors from wallpaper files. You must provide this command in your configuration object under the colorExtractionCommand key. The command must use {} as a placeholder for the wallpaper file path.

If the command fails to return valid color strings, the system will throw a SystemError stating: "Make sure the backend is extracting colors correctly."

// Example configuration structure
const config = {
  colorExtractionCommand: 'some-color-tool --path {}',
  processLimit: 4,
  wallpapersDirectory: '/path/to/wallpapers/',
  enableLightTheme: true
};

The --set-interval-callback (or -f) flag allows you to provide a JavaScript IIFE (Immediately Invoked Function Expression) that runs at every interval. This callback can be used to dynamically modify the application's arguments, such as toggling the light theme based on the time of day.

The callback has access to globalThis.USER_ARGUMENTS.

# Example: Switch to light theme between 6 AM and 6 PM
wallrizz -v 3600000 -f "(globalThis.USER_ARGUMENTS ??= {})[ 'enableLightTheme' ] = ((h) => h >= 6 && h < 18)(new Date().getHours())"

The UserInterface class manages the terminal-based display modes for Wallrizz. It supports two distinct view modes determined by the previewMode configuration key:

1. List Mode (previewMode: 'list'): Uses FzfView to provide a fuzzy-searchable list of wallpapers.
2. Gallery Mode (default): Uses GalleryView to provide a visual gallery interface.

To initialize the UI, call the init() method. This method is asynchronous and will render the appropriate view based on your configuration.

// Example initialization logic
const ui = new UserInterface(
  wallpaperList,
  wallpapersDirectory,
  handleSelection,
  getWallpaperPath,
  handleFocus,
  { previewMode: 'list' } // or 'gallery'
);

await ui.init();

The Theme class maintains a cache of extracted colors to avoid redundant processing.

• Cache Location: The global color cache is stored at ${HOME_DIR}/.cache/WallRizz/colours.json.
• getCachedColours(cacheName): Retrieves the array of hex color strings for a specific wallpaper using its uniqueId. If the color is not in memory, it attempts to load it from the colours.json file.
• createColoursCacheFromWallpapers(): An internal process that runs the colorExtractionCommand for wallpapers that do not yet have entries in the cache. It uses promiseQueueWithLimit (configured via config.processLimit) to manage concurrency.

Use the setThemes(wallpaperId, wallpaperName) method to apply a generated theme to a specific wallpaper. This method iterates through all available theme extension scripts and attempts to apply the cached theme configuration for that wallpaper.

• wallpaperId: The unique identifier for the wallpaper (used to locate the cached .conf file).
• wallpaperName: The name/path of the wallpaper file.

Upon successful application, a "Theme applied." notification is triggered.

// Assuming a Theme instance has been initialized
await themeInstance.setThemes('unique-wp-id', 'wallpaper_image.jpg');

The WallRizz class is the primary entrypoint for the application. It orchestrates the application lifecycle, including argument parsing, updates, extension testing, script downloads, and wallpaper management.

When instantiated, it parses command-line arguments and stores them in this.config. Calling the run() method executes the application's workflow based on the provided configuration flags.

import { WallRizz } from './src/main.js';

const app = new WallRizz();
await app.run();

When encountering system-level failures, Wallrizz uses the SystemError class. This error type extends the standard Error class and includes a description for context and a body for detailed error information (such as stack traces or raw error objects).

You can use the .log() method to print a formatted, colorized error message to stderr. By default, it prints the name and description. If you pass true to the inspect parameter, it will also print the body of the error.

import { SystemError } from './src/core/errors.js';

try {
  // ... some operation
} catch (err) {
  const systemErr = new SystemError(
    'FILE_NOT_FOUND',
    'The requested configuration file was not found.',
    err
  );
  
  // Logs name and description
  systemErr.log();
  
  // Logs name, description, and the detailed error body
  systemErr.log(true);
}

The testExtensions function is a utility designed to validate the current working directory as a valid extension environment.

It attempts to import a main.js file from the current working directory and execute its main() function. If main.js is not found, it provides an interactive CLI prompt (using fzf) allowing the user to automatically fetch and extract an extension template from the WallRizz repository via curl and unzip.

Requirements for template creation:

• curl must be installed.
• unzip must be installed and available in the system path.

import { testExtensions } from './src/extensions/ExtensionHandler.js';

// This will attempt to run main.js in the current directory
// or prompt to create a template if it's missing.
await testExtensions();