@vertigis/viewer-spec/messaging/registry/system.d.ts

VertiGIS Viewer Specification

import type Point from "@arcgis/core/geometry/Point.js";
import type { Action } from "@vertigis/arcgis-extensions/support/Action.js";
import type { CoordinateOptionProperties } from "../../app-config/web/CoordinateModelProperties.js";
import type { Command } from "../Command.js";
import { CommandRegistry } from "../CommandRegistry.js";
import type { Event } from "../Event.js";
import { EventRegistry } from "../EventRegistry.js";
import type { Operation } from "../Operation.js";
import { OperationRegistry } from "../OperationRegistry.js";
import type { Blob, File, HasFeatures, HasFiles, HasGeometry, HasLayers, HasMaps, HasUITarget, ModelRef } from "../common.js";
/**
 * Arguments for the system.download-file operation.
 */
export interface DownloadArgs {
    /**
     * The blob to download.
     */
    result?: Blob | Record<string, unknown> | string;
    /**
     * A filename for the download.
     */
    name?: string;
    /**
     * Optionally specify the record attribute to be used as the result content.
     * Defaults to 'result'.
     */
    resultAttribute?: string;
    /**
     * Optionally specify the record attribute to be used as the file name.
     * Defaults to 'name'.
     */
    fileNameAttribute?: string;
    /**
     * Optionally specify the file name extension to be used if the file name
     * does not end with one. Defaults to '.json'.
     */
    fileNameExtension?: string;
}
/**
 * Arguments for the system.repeat-action command.
 */
export interface RepeatActionArgs {
    /**
     * The actions to be repeatedly executed.
     */
    action?: Action;
    /**
     * The number of times actions will be executed. If omitted or given a value
     * of less than 1, actions will continue to be executed until manual
     * termination.
     */
    repetitions?: number;
}
/**
 * Arguments for the system.read-file operation.
 */
export interface ReadFileArgs extends HasUITarget {
    /**
     * The accept parameter for the file input. See
     * {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept}.
     */
    accept?: string;
    /**
     * If present, indicates that the user may choose more than one file.
     */
    multiple?: boolean;
    /**
     * If present, overrides the default title of the dialog that prompts the
     * user for a file.
     */
    promptTitle?: string;
    /**
     * If present, overrides the default message of the dialog that prompts the
     * user for a file.
     */
    promptMessage?: string;
    /**
     * If present, provides information about what file types are accepted by
     * this dialog, eg: "*.jpg, *.gif and *.bmp files accepted".
     */
    fileTypeDescription?: string;
}
/**
 * Well-known location-based tokens that can be used in the system.open-url
 * command arguments. Location.Map.ZoomLevel is not supported by Mobile; the
 * supported levels and their associated numeric values can be found here:
 * https://developers.arcgis.com/documentation/mapping-apis-and-services/reference/zoom-levels-and-scale/.
 */
export type LocationToken = "Location.Geolocation.Latitude" | "Location.Geolocation.Longitude" | "Location.Feature.Latitude" | "Location.Feature.Longitude" | "Location.Map.Center.Latitude" | "Location.Map.Center.Longitude" | "Location.Map.Scale" | "Location.Map.ZoomLevel" | "Location.Map.TopLeft.Latitude" | "Location.Map.TopLeft.Longitude" | "Location.Map.TopRight.Latitude" | "Location.Map.TopRight.Longitude" | "Location.Map.BottomLeft.Latitude" | "Location.Map.BottomLeft.Longitude" | "Location.Map.BottomRight.Latitude" | "Location.Map.BottomRight.Longitude";
/**
 * Well-known layer-based tokens that can be used in the system.open-url command
 * arguments. NOTE: Not all layer types support extents, urls, min/max scales,
 * and/or min/max zoom levels.
 */
export type LayerToken = "Layer.Extent.TopLeft.Latitude" | "Layer.Extent.TopLeft.Longitude" | "Layer.Extent.TopRight.Latitude" | "Layer.Extent.TopRight.Longitude" | "Layer.Extent.BottomLeft.Latitude" | "Layer.Extent.BottomLeft.Longitude" | "Layer.Extent.BottomRight.Latitude" | "Layer.Extent.BottomRight.Longitude" | "Layer.Extent.MaxScale" | "Layer.Extent.MinScale" | "Layer.Extent.MaxZoomLevel" | "Layer.Extent.MinZoomLevel" | "Layer.ID" | "Layer.Title" | "Layer.URL";
/**
 * The haptic style.
 */
export type HapticStyle = "light" | "medium" | "heavy" | "success" | "warning" | "error";
/**
 * VertiGIS Studio Web's arguments for the system.open-url command.
 */
export interface WebOpenUrlArgs extends Omit<OpenUrlArgs, "context">, HasMaps, HasFeatures, HasGeometry, HasLayers {
}
/**
 * Arguments for the system.open-url command.
 */
export interface OpenUrlArgs {
    /**
     * The URL to open.
     */
    url: string;
    /**
     * The coordinate option to use when formatting coordinate tokens. Valid
     * options must support latitude and longitude. Can be a reference to an
     * existing 'coordinate-option' item, or inline JSON defining a coordinate
     * option item.
     */
    coordinateOption?: ModelRef | CoordinateOptionProperties;
    /**
     * An object containing arguments that this command was originally executed
     * with. This property is populated automatically when using a bound action.
     * The URL will be the configured value, and the context is automatically
     * populated as the argument that was passed into the execute method when
     * the command was executed in context.
     */
    context?: unknown;
    /**
     * The locale to use for number token substitution. Accepts a valid locale
     * code (example: "en", "fr" or "de-AT"), or "device" or "invariant" which
     * will use the device's current culture or the invariant culture,
     * respectively. Default is invariant culture.
     */
    numberFormatterLocale?: string;
}
/**
 * Arguments for the system.disable-background-location-updates command.
 */
export interface BackgroundLocationUpdatesArgs {
    /**
     * The task ID for enabling and disabling background location updates. Once
     * enabled using a certain task ID, background location updates can only be
     * stopped once they are disabled with that same task ID.
     *
     * Cannot be set to null, but if this argument is not provided, a preset
     * default value will be used.
     */
    taskId?: string;
}
/**
 * Arguments for the system.enable-background-location-updates command.
 */
export interface EnableBackgroundLocationUpdateArgs extends BackgroundLocationUpdatesArgs {
    /**
     * The title used in the sticky notification on Android. If null or an empty
     * string, a default title will be used.
     */
    androidNotificationTitle?: string;
    /**
     * The message used in the sticky notification on Android.
     */
    androidNotificationMessage?: string;
}
/**
 * Arguments for the "system.url-opened" event.
 */
export interface UrlOpenedArgs {
    /**
     * The url that was opened, after substituting any tokens.
     */
    url: string;
    /**
     * The list of all locations that were used for token substitution in the
     * URL, if applicable.
     */
    locations: Point[];
}
export declare class SystemCommands extends CommandRegistry {
    protected readonly _prefix = "system";
    /**
     * Displays a sharing link to the user. Web only.
     *
     * @webOnly
     */
    get displaySharingLink(): Command<string>;
    /**
     * Executes Actions repeatedly until manually terminated or until given
     * number of repetitions are fulfilled. Web only.
     *
     * @webOnly
     */
    get repeatAction(): Command<RepeatActionArgs | Action>;
    /**
     * Initiates a file download of the specified Blob to the user. Web only.
     *
     * @webOnly
     */
    get downloadFile(): Command<DownloadArgs | Record<string, unknown> | string>;
    /**
     * Opens a URL, either in the system browser or whatever app is appropriate
     * for the scheme of the URL. If {@link Features} are included as context,
     * then the URL may contain substitution tokens in the format {FIELD_NAME}
     * where FIELD_NAME is the name of a field in the first feature in the
     * context. In this case, the {FIELD_NAME} is substituted with value of the
     * FIELD_NAME field from the feature feature in the {@link Features}, e.g.
     * https://www.google.com/search?q={NAME}, where the value of the NAME field
     * in the first feature from the context is 'Jasper National Park' would
     * produce the result https://www.google.com/search?q=Jasper National Park.
     * Zero to many substitution tokens may be included. If maps are included as
     * context, {@link LocationToken} can be used to access properties on the
     * first map's view. In Web, if both layers and maps are included as
     * context, then {@link LayerToken} can be used to access properties on the
     * first layer.
     */
    get openUrl(): Command<OpenUrlArgs | WebOpenUrlArgs | string>;
    /**
     * Allows to control if the screen should be kept on. Passing true as
     * parameter will keep the screen on, ignoring possible system settings for
     * screen timeouts. Passing false as parameter will make the app respect
     * system settings again. Mobile only.
     *
     * @mobileOnly
     */
    get keepScreenOn(): Command<boolean>;
    /**
     * Enables background location updates. While enabled, the application will
     * continue to execute code while running in the background.
     *
     * Note for iOS: If the user has not accepted location permissions for the
     * app, no code will be allowed to execute in the background. Mobile only.
     *
     * @mobileOnly
     */
    get enableBackgroundLocationUpdates(): Command<EnableBackgroundLocationUpdateArgs>;
    /**
     * Disables background location updates. Mobile only.
     *
     * @mobileOnly
     */
    get disableBackgroundLocationUpdates(): Command<BackgroundLocationUpdatesArgs>;
    /**
     * Performs system haptics with a given style, if the device supports it.
     * Uses 'taptics' when available, otherwise uses vibration. Mobile only.
     *
     * @mobileOnly
     */
    get haptics(): Command<HapticStyle>;
}
export declare class SystemOperations extends OperationRegistry {
    protected readonly _prefix = "system";
    /**
     * Fetch a file from the specified URL. Web only.
     *
     * @webOnly
     */
    get readUrl(): Operation<string, File[]>;
    /**
     * Initiates a file read, using the native browser file input. Web only.
     *
     * @webOnly
     */
    get readFile(): Operation<ReadFileArgs, File[]>;
    /**
     * A synonym for `system.read-file` that attaches the output to an args
     * object for use in command chains. Web only.
     *
     * @webOnly
     */
    get readFiles(): Operation<ReadFileArgs, HasFiles>;
    /**
     * Creates a link to share the shallow state of the application, including
     * map position and scale, layer visibility and current basemap. Web only.
     *
     * @webOnly
     */
    get getSharingLink(): Operation<void, string>;
}
export declare class SystemEvents extends EventRegistry {
    protected readonly _prefix = "system";
    /**
     * Raised when background location updates are enabled. Mobile only.
     *
     * @mobileOnly
     */
    get backgroundLocationUpdatesEnabled(): Event;
    /**
     * Raised when background location updates are disabled. Mobile only.
     *
     * @mobileOnly
     */
    get backgroundLocationUpdatesDisabled(): Event;
    /**
     * Raised when a URL has been opened via the system.open-url command. Mobile
     * only.
     *
     * @mobileOnly
     */
    get urlOpened(): Event<UrlOpenedArgs>;
}