pdbe-molstar/lib/extensions/state-gallery/manager.d.ts

Molstar implementation for PDBe

import { PluginContext } from 'molstar/lib/mol-plugin/context';
import { BehaviorSubject } from 'rxjs';
import { PreemptiveQueueResult } from '../../helpers';
import { StateGalleryConfigValues } from './config';
/** Shape of data coming from `https://www.ebi.ac.uk/pdbe/static/entry/{entryId}.json`[entryId] */
export interface StateGalleryData {
    entity?: {
        [entityId: string]: {
            image: Image[];
            database?: {
                [databaseName: string]: {
                    [domainId: string]: {
                        image: Image[];
                    };
                };
            };
        };
    };
    assembly?: {
        [assemblyId: string]: {
            image: Image[];
            preferred?: boolean;
        };
    };
    entry?: {
        all?: {
            image: Image[];
        };
        bfactor?: {
            image: Image[];
        };
        ligands?: {
            [compId: string]: {
                image: Image[];
                entity?: string;
                number_of_instances?: number;
            };
        };
        mod_res?: {
            [compId: string]: {
                image: Image[];
            };
        };
    };
    validation?: {
        geometry?: {
            deposited?: {
                image: Image[];
            };
        };
    };
    image_suffix?: string[];
    last_modification?: string;
}
/** Categories of images/states */
export declare const ImageCategory: readonly ["Entry", "Assemblies", "Entities", "Ligands", "Modified residues", "Domains", "Miscellaneous"];
export type ImageCategory = typeof ImageCategory[number];
/** Information about one image (3D state) */
export interface Image {
    /** Image filename without extension (.molj, _image-800x800.png, .caption.json...), used to construct URL */
    filename: string;
    /** Short description of the image */
    alt?: string;
    /** Long description of the image, with HTML markup */
    description?: string;
    /** Long description of the image, plaintext */
    clean_description?: string;
    /** Assignment to a category (does not come from the API) */
    category?: ImageCategory;
    /** Short title for display in the UI (does not come from the API) */
    title?: string;
    /** Additional information (e.g. entity name) for display in the UI as subtitle (does not come from the API) */
    subtitle?: string;
}
/** Current status of a StateGalleryManager ('ready' = last requested image loaded successfully or no image requested yet, 'loading' = last requested image not resolved yet, 'error' = last requested image failed to load) */
export type LoadingStatus = 'ready' | 'loading' | 'error';
/** Provides functionality to get list of images (3D states) for an entry, load individual images, keeps track of the currently loaded image.
 * Use async `StateGalleryManager.create()` to create an instance. */
export declare class StateGalleryManager {
    readonly plugin: PluginContext;
    /** Entry identifier, i.e. '1cbs' */
    readonly entryId: string;
    /** Data retrieved from API */
    readonly data: StateGalleryData | undefined;
    /** Config values */
    readonly options: StateGalleryConfigValues;
    /** List of images (3D states) for entry `this.entryId` */
    readonly images: Image[];
    /** Maps image filename to its index within `this.images` */
    private readonly filenameIndex;
    /** BehaviorSubjects for current state of the manager */
    readonly events: {
        /** Image that has been requested to load most recently. */
        requestedImage: BehaviorSubject<Image | undefined>;
        /** Image that has been successfully loaded most recently. Undefined if another state has been requested since. */
        loadedImage: BehaviorSubject<Image | undefined>;
        /** Loading status. */
        status: BehaviorSubject<LoadingStatus>;
    };
    /** True if at least one image has been loaded (this is to skip animation on the first load) */
    private firstLoaded;
    private constructor();
    /** Create an instance of `StateGalleryManager` and retrieve list of images from API.
     * Options that are not provided will use values from plugin config. */
    static create(plugin: PluginContext, entryId: string, options?: Partial<StateGalleryConfigValues>): Promise<StateGalleryManager>;
    /** Load an image (3D state). Do not call directly; use `load` instead, which handles concurrent requests. */
    private _load;
    private readonly loader;
    /** Request to load an image (3D state). When there are multiple concurrent requests, some requests may be skipped (will resolve to `{ status: 'cancelled' }` or `{ status: 'skipped' }`) as only the last request is really important. */
    load(img: Image | string): Promise<PreemptiveQueueResult<void>>;
    /** Move to next/previous image in the list. */
    private shift;
    /** Request to load the previous image in the list */
    loadPrevious(): Promise<PreemptiveQueueResult<void>>;
    /** Request to load the next image in the list */
    loadNext(): Promise<PreemptiveQueueResult<void>>;
    /** Cache for MOLJ states from API */
    private readonly cache;
    /** Fetch a MOLJ state from API */
    private fetchSnapshot;
    /** Get MOLJ state for the image (get from cache or fetch from API) */
    getSnapshot(filename: string): Promise<string>;
    /** Get full image information based on filename. Return `undefined` if image with given filename is not in the list. */
    private getImageByFilename;
}