Smartphone Widget API Documentation

The smartphone-widget module provides an API to allow other modules to register their own smartphone apps and interact with the widget's functionalities.

1. Accessing the API Object

All API functions can be accessed through the game.modules.get('smartphone-widget').api object. This object is safely accessible within Foundry VTT's setup or ready hooks.

Recommendation: It's best to perform initial registrations like registerApp in the setup hook. For functionalities that rely on sockets, use them after the socketlib.ready hook.

let smartphoneApi;

Hooks.once('setup', () => {
    // It's convenient to store the API object in a variable.
    smartphoneApi = game.modules.get('smartphone-widget')?.api;

    if (!smartphoneApi) {
        ui.notifications.error("My Addon requires the 'Smartphone Widget' module to be active.");
        return;
    }

    // Perform initial registrations like registerApp and registerBadgeUpdater here.
});

2. Core API

registerApp(appData)

Registers a new smartphone application. Registered apps will appear in the App Store and can be installed by users if enabled by the GM. This should be called in the setup hook.

• appData (Object): An object containing the information for the app to be registered.
  • id (String, Required): A unique ID for the app (e.g., 'questlog').
  • name (String): The display name of the app (using a localization key is recommended).
  • icon (String): A Font Awesome icon class (e.g., 'fas fa-scroll').
  • color (String): The background color for the home screen icon (Hex code).
  • category (String): The category to be displayed in the App Store (e.g., 'game', 'social', 'utility'). This value is used as a localization key: SMARTPHONE.apps.appstore.{category}.
  • appClass (Class, Required): The main class for the app, which must extend BaseApp.

Example:

// Run inside the 'setup' hook
smartphoneApi.registerApp({
    id: 'questlog',
    name: game.i18n.localize("SMARTPHONE.apps.questlog.title"),
    icon: 'fas fa-scroll',
    color: '#8B4513',
    category: 'utility', // Uses the SMARTPHONE.apps.appstore.utility key
    appClass: QuestLogApp // QuestLogApp is a class that extends BaseApp
});

3. UI Interaction API

registerBadgeUpdater(appId, handler)

Registers a method for calculating the notification badge count for a specific app icon. Once registered, the provided handler will be executed whenever updateBadge is called, automatically updating the badge count. This should be called in the setup hook.

• appId (String): The unique ID of the app for which to register the badge.