@eclipse-scout/core/dist/d.ts/src/scout.d.ts

Eclipse Scout runtime

import { AdapterData, Locale, ModelAdapterLike, ObjectCreator, ObjectFactoryOptions, ObjectType, Session, UuidPathOptions, Widget } from './index';
/**
 * The minimal model declaration (usually extends {@link ObjectModel}) as it would be used in a nested declaration (e.g. a {@link FormField} within a {@link GroupBox}).
 * The {@link objectType} is optional as sometimes it might be already given by the context (e.g. when passing a {@link MenuModel} to a method {@link insertMenu()} where the method sets a default {@link objectType} if missing).
 */
export type ModelOf<TObject> = TObject extends {
    model?: infer TModel;
} ? TModel : object;
/**
 * Model used to initialize an object instance. Usually the same as {@link ModelOf} but with some minimal required properties (mandatory properties).
 * The definition of the required properties can be done by the object itself by declaring a property called `initModel`.
 * A typical object with an `initModel` adds an e.g. {@link parent} or {@link session} property which needs to be present when initializing an already created instance.
 */
export type InitModelOf<TObject> = TObject extends {
    initModel?: infer TInitModel;
} ? TInitModel : ModelOf<TObject>;
/**
 * Model required to create a new object as child of an existing. To identify the object an {@link objectType} is mandatory.
 * But as the properties required to initialize the instance are derived from the parent, no other mandatory properties are required.
 */
export type ChildModelOf<TObject> = ModelOf<TObject> & {
    objectType: ObjectType<TObject>;
};
/**
 * A full object model declaring all mandatory properties. Such models contain all information to create ({@link objectType}) and initialize (e.g. {@link parent}) a new object.
 */
export type FullModelOf<TObject> = InitModelOf<TObject> & ChildModelOf<TObject>;
/**
 * Represents an instance of an object or its minimal model ({@link ModelOf}).
 */
export type ObjectOrModel<T> = T | ModelOf<T>;
/**
 * Represents an instance of an object or its child model ({@link ChildModelOf}).
 */
export type ObjectOrChildModel<T> = T | ChildModelOf<T>;
/**
 * Represents an instance of an object or its type ({@link ObjectType}).
 */
export type ObjectOrType<T> = T | ObjectType<T>;
export type Constructor<T = object> = new (...args: any[]) => T;
export type AbstractConstructor<T = object> = abstract new (...args: any[]) => T;
export type DeepPartial<T> = T extends object ? {
    [P in keyof T]?: DeepPartial<T[P]>;
} : T;
export interface ObjectWithType {
    objectType: string;
}
/**
 * Represents an object having an uuid.
 */
export interface ObjectWithUuid {
    /**
     * The unique identifier property of the object.
     *
     * This property alone may not be unique within a widget tree (e.g. if template widgets are used).
     * To get a more unique id use {@link buildUuidPath} instead.
     */
    uuid: string;
    /**
     * Parent to be used instead of the default parent when computing the uuid path for the object.
     *
     * @see buildUuidPath
     */
    uuidParent?: ObjectWithUuid;
    /**
     * Computes a unique identifier for the object.
     *
     * Compared to {@link uuid} it also considers the {@link classId} property and may use a fallback logic if none of these two properties are available, see {@link ObjectIdProvider.uuid}.
     *
     * This property alone may not be unique within a widget tree (e.g. if template widgets are used).
     * To get a more unique id use {@link buildUuidPath} instead.
     *
     * @param useFallback Optional boolean specifying if a fallback identifier may be created in case an object has no specific identifier set. The fallback may be less stable. Default is true.
     * @returns the uuid for the object or null.
     */
    buildUuid(useFallback?: boolean): string;
    /**
     * Computes a unique identifier for the object considering parent objects (if existing).
     *
     * Note: The returned id may not be unique within the application! E.g. if the same form is opened twice, its children will share the same ids.
     * @param options Optional {@link UuidPathOptions} controlling the computation of the path.
     * @see ObjectIdProvider.uuidPath.
     */
    buildUuidPath(options?: UuidPathOptions): string;
    /**
     * Sets the {@link uuid} property.
     */
    setUuid(uuid: string): any;
}
export interface ObjectWithId<TId = string> {
    id: TId;
}
export interface ObjectModel<TObject = object> {
    objectType?: ObjectType<TObject>;
}
export interface ObjectModelWithId<TId = string> {
    id?: TId;
}
export interface ObjectModelWithUuid<TObject = object> extends ObjectModel<TObject> {
    /**
     * A unique identifier for the object. Typically, a new random UUID can be used.
     */
    uuid?: string;
    /**
     * Parent to be used instead of the default parent when computing the uuid path for the object.
     *
     * @see ObjectWithUuid.buildUuidPath
     */
    uuidParent?: ObjectWithUuid;
}
export interface ReloadPageOptions {
    /**
     * If true, the page reload is not executed in the current thread but scheduled using setTimeout().
     * This is useful if the caller wants to execute some other code before reload. The default is false.
     */
    schedule?: boolean;
    /**
     * If true, the body is cleared first before reload. This is useful to prevent
     * showing "old" content in the browser until the new content arrives. The default is true.
     */
    clearBody?: boolean;
    /**
     * The new URL to load. If not specified, the current location is used (window.location).
     */
    redirectUrl?: string;
}
declare function create<T>(objectType: Constructor<T>, model?: InitModelOf<T>, options?: ObjectFactoryOptions): T;
declare function create<T>(model: FullModelOf<T>, options?: ObjectFactoryOptions): T;
declare function create(objectType: string, model?: object, options?: ObjectFactoryOptions): any;
declare function create(model: {
    objectType: string;
    [key: string]: any;
}, options?: ObjectFactoryOptions): any;
declare function create<T>(objectType: ObjectType<T> | FullModelOf<T>, model?: InitModelOf<T>, options?: ObjectFactoryOptions): T;
declare function widget<T extends Widget>(widgetIdOrElement: string | number | HTMLElement | JQuery, partIdOrType?: string | Constructor<T>): T;
declare function widget(widgetIdOrElement: string | number | HTMLElement | JQuery, partId?: string): Widget;
export declare const scout: {
    objectFactories: Map<string | Constructor<object>, ObjectCreator>;
    /**
     * Returns the first of the given arguments that is not null or undefined. If no such element
     * is present, the last argument is returned. If no arguments are given, undefined is returned.
     */
    nvl(...args: any[]): any;
    /**
     * Use this method in your functions to assert that a mandatory parameter is passed
     * to the function. Throws an error when value is not set.
     *
     * @param type if this optional parameter is set, the given value must be of this type (instanceof check)
     * @returns the value (for direct assignment)
     */
    assertParameter<T>(parameterName: string, value?: T, type?: Constructor | AbstractConstructor): T;
    /**
     * Use this method to assert that a mandatory property is set. Throws an error when value is not set.
     *
     * @param type if this parameter is set, the value must be of this type (instanceof check)
     * @returns the value (for direct assignment)
     */
    assertProperty(object: object, propertyName: string, type?: Constructor | AbstractConstructor): any;
    /**
     * Throws an error if the given value is null or undefined. Otherwise, the value is returned.
     *
     * @param value value to check
     * @param msg optional error message when the assertion fails
     */
    assertValue<T_1>(value: T_1, msg?: string): T_1;
    /**
     * Throws an error if the given value is not an instance of the given type. Otherwise, the value is returned.
     *
     * @param value value to check
     * @param type type to check against with "instanceof"
     * @param msg optional error message when the assertion fails
     */
    assertInstance<T_2>(value: any, type: Constructor<T_2> | AbstractConstructor<T_2>, msg?: string): T_2;
    /**
     * Checks if one of the arguments from 1-n is equal to the first argument.
     * @param args to check against the value, may be an array or a variable argument list.
     */
    isOneOf(value: any, ...args: any[]): boolean;
    create: typeof create;
    /**
     * Ensures the given parameter is an object.
     *
     * If it is an object, it will be returned as it is.
     * If it is an {@link ObjectType}, {@link scout.create} is used to create the object.
     *
     * @param model will be passed to {@link scout.create} if an object needs to be created and ignored otherwise.
     */
    ensure<T_3 extends object>(objectOrType: ObjectOrType<T_3>, model?: InitModelOf<T_3>): T_3;
    /**
     * Prepares the DOM for scout in the given document. This should be called once while initializing scout.
     * If the target document is not specified, the global "document" variable is used instead.
     *
     * This is used by apps (App, LoginApp, LogoutApp)
     *
     * Currently, it does the following:
     * - Remove the <noscript> tag (obviously there is no need for it).
     * - Remove <scout-text> tags (they must have been processed before, see texts.readFromDOM())
     * - Remove <scout-version> tag (it must have been processed before, see App._initVersion())
     * - Add a device / browser class to the body tag to allow for device specific CSS rules.
     * - Add browser locale to DOM so screen readers read text correctly (may get replaced if actual locale of user is loaded)
     * - If the browser is Google Chrome, add a special meta header to prevent automatic translation.
     */
    prepareDOM(targetDocument: Document): void;
    /**
     * Installs a global 'mousedown' interceptor to invoke 'aboutToBlurByMouseDown' on value field before anything else gets executed.
     */
    installGlobalMouseDownInterceptor(myDocument: Document): void;
    /**
     * Because Firefox does not set the active state of a DOM element when the mousedown event
     * for that element is prevented, we set an 'active' CSS class instead. This means in the
     * CSS we must deal with :active and with .active, where we need same behavior for the
     * active state across all browsers.
     *
     * Typically, you'd write something like this in your CSS:
     * ```
     *   button:active, button.active { ... }
     * ```
     */
    installSyntheticActiveStateHandler(myDocument: Document): void;
    /**
     * Sets locale of the document, important for screen readers
     * @param locale
     */
    setDocumentLocale(locale: Locale): void;
    widget: typeof widget;
    /**
     * Helper to get the model adapter for a given adapterId. If there is more than one
     * session, e.g. in case of portlets, the second argument specifies the partId of the session
     * to be queried. If not specified explicitly, the first session is used. If the session or
     * the adapter could not be found, null is returned.
     */
    adapter(adapterId: string, partId: string): ModelAdapterLike;
    /**
     * @returns the session for the given partId. If the partId is omitted, the first session is returned.
     */
    getSession(partId?: string): Session;
    /**
     * This method exports the adapter with the given ID as JSON, it returns a plain object containing the
     * configuration of the adapter. You can transform that object into JSON by calling <code>JSON.stringify</code>.
     * This method can only be called through the browser JavaScript console.
     * Here's an example of how to call the method:
     *
     * JSON.stringify(exportAdapter(4))
     */
    exportAdapter(adapterId: string, partId: string): AdapterData;
    /**
     * Reloads the entire browser window.
     */
    reloadPage(options?: ReloadPageOptions): void;
    /**
     * @param factories Object that contains the object type as key and the that constructs the object as value.
     *          If you prefer using a class reference as object type rather than a string, please use {@link addObjectFactory} to register your factory.
     * @see create
     */
    addObjectFactories(factories: Record<string, ObjectCreator>): void;
    /**
     * @param objectType ObjectType to register the factory for.
     * @param factory Function that constructs the object.
     * @see create
     */
    addObjectFactory(objectType: ObjectType, factory: ObjectCreator): void;
    cloneShallow(template: object, properties?: object, createUniqueId?: boolean): object;
    /**
     * Enables or disables the layout spy that visualizes the cell bounds of the logical grid for debugging purposes.
     * The spy can be enabled on elements that belong to a widget using a {@link LogicalGridLayout}, e.g. {@link GroupBox}, {@link TileGrid}, etc.
     */
    setLogicalGridSpyEnabled(elem: HTMLElement, enabled: boolean): void;
};
export {};
//# sourceMappingURL=scout.d.ts.map