@eclipse-scout/core
Version:
Eclipse Scout runtime
493 lines • 22.1 kB
TypeScript
/// <reference types="jquery" />
import { BusyIndicatorOptions, DisabledStyle, DisplayParent, DisplayViewId, EnumObject, Event, EventHandler, FileChooser, FileChooserController, FormController, FormEventMap, FormLifecycle, FormModel, FormRevealInvalidFieldEvent, GlassPaneRenderer, GroupBox, InitModelOf, KeyStroke, KeyStrokeContext, MessageBox, MessageBoxController, MessageBoxes, NotificationBadgeStatus, ObjectOrChildModel, Point, PopupWindow, PropertyChangeEvent, Rectangle, Status, StatusOrModel, TreeVisitResult, ValidationResult, Widget } from '../index';
export type DisplayHint = EnumObject<typeof Form.DisplayHint>;
export declare class Form extends Widget implements FormModel, DisplayParent {
model: FormModel;
eventMap: FormEventMap;
self: Form;
animateOpening: boolean;
askIfNeedSave: boolean;
validationFailedText: string;
emptyMandatoryElementsText: string;
invalidElementsErrorText: string;
invalidElementsWarningText: string;
askIfNeedSaveText: string;
data: any;
exclusiveKey: () => any;
displayViewId: DisplayViewId;
displayHint: DisplayHint;
maximized: boolean;
headerVisible: boolean;
displayParent: DisplayParent;
dialogs: Form[];
views: Form[];
messageBoxes: MessageBox[];
fileChoosers: FileChooser[];
focusedElement: Widget;
closable: boolean;
cacheBounds: boolean;
cacheBoundsKey: string;
resizable: boolean;
movable: boolean;
rootGroupBox: GroupBox;
/**
* Indicates whether the form needs to be saved.
* If set to true, a marker will be visible in the form header or tab, unless {@link saveNeededVisible} is set to false.
*
* The value will be computed by {@link updateSaveNeeded}.
*/
saveNeeded: boolean;
saveNeededVisible: boolean;
formController: FormController;
messageBoxController: MessageBoxController;
fileChooserController: FileChooserController;
closeKeyStroke: KeyStroke;
showOnOpen: boolean;
initialFocus: Widget;
renderInitialFocusEnabled: boolean;
formLoading: boolean;
formLoaded: boolean;
/**
* true if the form was saved (e.g. by calling {@link ok} or {@link save}) since it was created.
*/
formSaved: boolean;
/** set by PopupWindow if this form has displayHint=Form.DisplayHint.POPUP_WINDOW */
popupWindow: PopupWindow;
title: string;
subTitle: string;
iconId: string;
status: Status;
uiCssClass: string;
lifecycle: FormLifecycle;
detailForm: boolean;
/** @internal */
blockRendering: boolean;
validators: FormValidator[];
protected _defaultValidator: FormValidator;
$statusIcons: JQuery[];
$header: JQuery;
$statusContainer: JQuery;
$close: JQuery;
$saveNeeded: JQuery;
$icon: JQuery;
$title: JQuery;
$subTitle: JQuery;
$dragHandle: JQuery;
protected _modal: boolean;
protected _glassPaneRenderer: GlassPaneRenderer;
protected _preMaximizedBounds: Rectangle;
protected _resizeHandler: (Event: any) => boolean;
protected _windowResizeHandler: () => void;
protected _mainBoxSaveNeededChangeHandler: EventHandler<PropertyChangeEvent>;
constructor();
static DisplayHint: {
readonly DIALOG: "dialog";
readonly POPUP_WINDOW: "popupWindow";
readonly VIEW: "view";
};
protected static _NOTIFICATION_BADGE_STATUS_CODE: number;
protected _init(model: InitModelOf<this>): void;
protected _createKeyStrokeContext(): KeyStrokeContext;
protected _render(): void;
protected _renderProperties(): void;
protected _postRender(): void;
protected _destroy(): void;
protected _remove(): void;
/** @see FormModel.modal */
setModal(modal: boolean): void;
get modal(): boolean;
protected _renderModal(): void;
protected _installLifecycle(): void;
protected _createLifecycle(): FormLifecycle;
setExclusiveKey(exclusiveKey: any): void;
protected _setExclusiveKey(exclusiveKey: any): void;
/**
* Loads the data and renders the form afterward by adding it to the desktop.
*
* Calling this method is equivalent to calling {@link load} first and once the promise is resolved, calling {@link show}.
*
* Keep in mind that the form won't be rendered immediately after calling {@link open}. Because promises are always resolved asynchronously,
* {@link show} will be called delayed even if {@link load} does nothing but return a resolved promise.
*
* This is only relevant if you need to access properties which are only available when the form is rendered (e.g. {@link $container}), which is not recommended anyway.
*/
open(): JQuery.Promise<void>;
/**
* Initializes the life cycle and calls the {@link _load} function.
* Does nothing, if form is still loading (= {@link formLoading} is true).
*
* @param allowReload controls whether loading should be allowed even if it has already been loaded once (= if {@link formLoaded is true}).
* @returns promise which is resolved when the form is loaded.
*/
load(allowReload?: boolean): JQuery.Promise<void>;
/**
* Enables the {@link BusyIndicator} while the given action runs.
*
* @see setBusy
*/
withBusyHandling<T>(action: () => JQuery.Promise<T>, opts?: Pick<BusyIndicatorOptions, 'renderDelay'>): JQuery.Promise<T>;
/**
* @deprecated use {@link withBusyHandling}.
*/
protected _withBusyHandling<T>(action: () => JQuery.Promise<T>, opts?: Pick<BusyIndicatorOptions, 'renderDelay'>): JQuery.Promise<T>;
/**
* @returns promise which is resolved when the form is loaded, respectively when the 'load' event is triggered.
*/
whenLoad(): JQuery.Promise<Event<Form>>;
/**
* Lifecycle handle function registered for 'load'.
*/
protected _onLifecycleLoad(): JQuery.Promise<void>;
protected _setFormLoading(loading: boolean): void;
/**
* This function is called when an error occurs in the {@link _onLifecycleLoad} function or when the {@link _load} function returns with a rejected promise.
* By default, the error is forwarded to the {@link ErrorHandler}, the form is closed and a rejected promise is returned so a caller of {@link load} may catch the error.
*/
protected _handleLoadErrorInternal(error: any): JQuery.Promise<void>;
/**
* Default load error handler. May be overridden by sub-classes.
*/
protected _handleLoadError(error: any): JQuery.Promise<void>;
/**
* Method may be implemented to load the data.
* By default, a resolved promise containing {@link data} is returned.
*/
protected _load(): JQuery.Promise<any>;
/**
* @returns promise which is resolved when the form is post loaded, respectively when the 'postLoad' event is triggered.
*/
whenPostLoad(): JQuery.Promise<Event<Form>>;
protected _onLifecyclePostLoad(): JQuery.Promise<void>;
/**
* This function is called when an error occurs in the {@link _onLifecyclePostLoad} function or when the {@link _postLoad} function returns with a rejected promise.
* By default, the error is forwarded to the {@link ErrorHandler} and a rejected promise is returned.
*/
protected _handlePostLoadErrorInternal(error: any): JQuery.Promise<void>;
/**
* Default postLoad error handler. May be overridden by sub-classes.
*/
protected _handlePostLoadError(error: any): JQuery.Promise<void>;
protected _postLoad(): JQuery.Promise<void>;
/** @see FormModel.data */
setData(data: any): void;
/**
* Imports the {@link data} to the form.
*/
importData(): void;
/**
* Exports the form to {@link data}.
*/
exportData(): any;
/**
* Saves and closes the form.
*
* **Note:** The resulting promise will be resolved even if the form does not require save and therefore even if {@link _save} is not called.
* If you only want to be informed when save is required and {@link _save} executed then you could use {@link whenSave} or `on('save')` instead.
*
* @returns promise which is resolved when the save completes and rejected on an error.
*/
ok(): JQuery.Promise<void>;
/**
* Saves the changes without closing the form.
*
* **Note:** The resulting promise it will be resolved even if the form does not require save and therefore even if {@link _save} is not called.
* If you only want to be informed when save is required and {@link _save} executed then you could use {@link whenSave} or `on('save')` instead.
*
* @returns promise which is resolved when the save completes and rejected on an error.
*/
save(): JQuery.Promise<void>;
/**
* @returns promise which is resolved when the form is saved, respectively when the 'save' event is triggered.
*/
whenSave(): JQuery.Promise<Event<Form>>;
protected _onLifecycleSave(): JQuery.Promise<void>;
/**
* This function is called when an error occurs in {@link _onLifecycleSave} or when {@link _save} returns with a rejected promise.
* By default, the error is forwarded to the {@link ErrorHandler} and the promise is rejected so a caller of {@link save} may catch the error.
*/
protected _handleSaveErrorInternal(error: any): JQuery.Promise<void>;
/**
* Default save error handler. May be overridden by sub-classes.
*/
protected _handleSaveError(error: any): JQuery.Promise<void>;
protected _handleErrorInternal(error: any, phase: string, errorHandler: (error: any) => JQuery.Promise<void>): JQuery.Promise<void>;
/**
* Default error handler for {@link _load}, {@link _save} and {@link _postLoad}. May be overridden by subclasses.
* @returns A promise that resolves when the error is handled.
*/
protected _handleError(error: any): JQuery.Promise<void>;
/**
* Validates the form.
*
* @returns a promise resolved with the validation result as {@link Status}.
*/
validate(): JQuery.Promise<Status>;
/**
* The function is called every time {@link _lifecycleValidate} is called. The function should be used
* to implement an overall validate logic which is not related to a specific field. For instance, you
* could validate the state of an internal member variable.
*
* You should return a {@link Status} object with severity ERROR or WARNING in case the validation fails.
*/
protected _validate(): Status | JQuery.Promise<Status>;
/**
* This function is called by the lifecycle, for instance when the 'ok' function is called.
* The function is called every time the 'ok' function is called, which means it runs even when
* there is not a single touched field. The function should be used to implement an overall validate
* logic which is not related to a specific field. For instance, you could validate the state of an
* internal member variable.
*
* Do not override this method, use {@link _validate} instead.
*/
_lifecycleValidate(): Status | JQuery.Promise<Status>;
/** @see FormModel.validators */
addValidator(validator: FormValidator): void;
/** @see FormModel.validators */
removeValidator(validator: FormValidator): void;
/** @see FormModel.validators */
setValidators(validators: FormValidator | FormValidator[]): void;
protected _setValidators(validators: FormValidator | FormValidator[]): void;
/**
* Called when the validation of this form failed.
* @param status The {@link Status} that describes why the validation failed. It is always invalid (error or warning).
* @internal
*/
_handleInvalid(status: Status): JQuery.Promise<Status>;
protected _showFormInvalidMessageBox(status: Status): JQuery.Promise<Status>;
protected _createStatusMessageBox(status: Status): MessageBoxes;
/**
* This function is called by the lifecycle, when {@link save} is called.
*
* The data given to this function is the result of {@link exportData} which was called in advance.
*/
protected _save(data: any): JQuery.Promise<void>;
/**
* Resets the form to its initial state.
*/
reset(): JQuery.Promise<void>;
/**
* @returns promise which is resolved when the form is reset, respectively when the 'reset' event is triggered.
*/
whenReset(): JQuery.Promise<Event<Form>>;
protected _onLifecycleReset(): void;
/**
* Closes the form if there are no changes made. Otherwise, it shows a message box asking to save the changes.
*/
cancel(): JQuery.Promise<void>;
/**
* Closes the form and discards any unsaved changes.
*/
close(): JQuery.Promise<void>;
/**
* @returns promise which is resolved when the form is closed, respectively when the 'close' event is triggered.
*/
whenClose(): JQuery.Promise<Event<Form>>;
protected _onLifecycleClose(): void;
/**
* Destroys the form and removes it from the desktop.
*/
protected _close(): void;
/**
* This function is called when the user presses the "x" icon.
*
* It will either call {@link #close()} or {@link #cancel()}, depending on the enabled and visible system buttons, see {@link _abort}.
*/
abort(): void;
/**
* @returns promise which is resolved when the form is aborted, respectively when the 'abort' event is triggered.
*/
whenAbort(): JQuery.Promise<Event<Form>>;
/**
* Will call {@link #close()} if there is a close menu or button, otherwise {@link #cancel()} will be called.
*/
protected _abort(): void;
/** @internal */
_afterAbort(): void;
revealInvalidField(validationResult: ValidationResult): void;
protected _revealInvalidField(validationResult: ValidationResult): void;
protected _createRevealInvalidFieldEvent(validationResult: ValidationResult): FormRevealInvalidFieldEvent;
/**
* Override this method to provide a keystroke which closes the form.
* The default implementation returns an AbortKeyStroke which handles the ESC key and calls {@link abort}.
*
* The keystroke is only active if {@link closable} is set to true.
*/
protected _createCloseKeyStroke(): KeyStroke;
protected _setClosable(closable: boolean): void;
/** @see FormModel.closable */
setClosable(closable: boolean): void;
protected _renderClosable(): void;
protected _onCloseIconClick(): void;
/** @see FormModel.resizable */
setResizable(resizable: boolean): void;
protected _renderResizable(): void;
protected _onResize(event: Event): boolean;
/** @see FormModel.movable */
setMovable(movable: boolean): void;
protected _renderMovable(): void;
protected _onDialogMouseDown(): void;
/**
* @see Desktop.activateForm
*/
activate(): void;
show(): void;
hide(): void;
/**
* Checks whether the form is shown, which means whether a form has been added to the form stack of the display parent, e.g. by using {@link showForm}.
*
* It does not necessarily mean the user can see the content of the form for sure,
* e.g. if the form is opened as a view the tab may be inactive because another view is active, or in case of a dialog it may be hidden behind another dialog or shown in an inactive view.
*/
isShown(): boolean;
protected _renderHeader(): void;
protected _removeHeader(): void;
/** @see FormModel.rootGroupBox */
setRootGroupBox(rootGroupBox: ObjectOrChildModel<GroupBox>): void;
protected _setRootGroupBox(rootGroupBox: GroupBox): void;
protected _renderRootGroupBox(): void;
/**
* Updates the {@link saveNeeded} property based on the {@link GroupBox.saveNeeded} state of the {@link rootGroupBox} and the result of {@link _computeSaveNeeded}.
*/
updateSaveNeeded(): void;
/**
* Used by {@link updateSaveNeeded} to update the {@link saveNeeded} property.
*
* Can be implemented to add a custom save needed check for this specific form.
*
* By default, there is no implementation and {@link saveNeeded} depends on the state of the {@link rootGroupBox} which itself depends on the state of its fields.
*
* @returns true if the form needs to be saved, false if only the state of the group should be considered
*/
protected _computeSaveNeeded(): boolean;
/**
* Marks the root group box as saved so that {@link saveNeeded} returns false.
*
* *Note*: {@link saveNeeded} may still return true afterward if a custom save needed computation is active, see {@link _computeSaveNeeded}.
*
* @see GroupBox.markAsSaved
* @see touch
*/
markAsSaved(): void;
protected setSaveNeeded(saveNeeded: boolean): void;
protected _renderSaveNeeded(): void;
/** @see FormModel.askIfNeedSave */
setAskIfNeedSave(askIfNeedSave: boolean): void;
/** @see FormModel.displayViewId */
setDisplayViewId(displayViewId: DisplayViewId): void;
/** @see FormModel.displayHint */
setDisplayHint(displayHint: DisplayHint): void;
/** @see FormModel.saveNeededVisible */
setSaveNeededVisible(visible: boolean): void;
protected _renderSaveNeededVisible(): void;
protected _renderCssClass(cssClass?: string, oldCssClass?: string): void;
/** @see FormModel.status */
setStatus(status: StatusOrModel): void;
protected _setStatus(status: StatusOrModel): void;
protected _renderStatus(): void;
protected _renderSingleStatus(status: Status, $prevIcon: JQuery): JQuery;
addStatus(status: Status): void;
removeStatus(status: Status): void;
getNotificationBadgeText(): string;
setNotificationBadgeText(notificationBadgeText: string): void;
protected _getNotificationBadgeStatus(): NotificationBadgeStatus;
/** @see FormModel.showOnOpen */
setShowOnOpen(showOnOpen: boolean): void;
isDialog(): boolean;
isPopupWindow(): boolean;
isView(): boolean;
protected _onMove(newOffset: {
top: number;
left: number;
}): void;
moveTo(position: Point): void;
position(): void;
updateCacheBounds(): void;
appendTo($parent: JQuery): void;
/** @see FormModel.headerVisible */
setHeaderVisible(headerVisible: boolean): void;
protected _renderHeaderVisible(): void;
/** @see FormModel.title */
setTitle(title: string): void;
protected _renderTitle(): void;
/** @see FormModel.subTitle */
setSubTitle(subTitle: string): void;
protected _renderSubTitle(): void;
/** @see FormModel.iconId */
setIconId(iconId: string): void;
protected _renderIconId(): void;
protected _setViews(views: Form[]): void;
setDisabledStyle(disabledStyle: DisabledStyle): void;
/** @see FormModel.displayParent */
setDisplayParent(displayParent: DisplayParent): void;
protected _setDisplayParent(displayParent: DisplayParent): void;
/** @see FormModel.maximized */
setMaximized(maximized: boolean): void;
protected _renderMaximized(): void;
protected _onWindowResize(): void;
protected _maximize(): void;
prefBounds(): Rectangle;
protected _attach(): void;
/**
* Method invoked when:
* - this is a 'detailForm' and the outline content is displayed;
* - this is a 'view' and the view tab is selected;
* - this is a child 'dialog' or 'view' and its 'displayParent' is attached;
*/
protected _postAttach(): void;
/**
* Method invoked when:
* - this is a 'detailForm' and the outline content is hidden;
* - this is a 'view' and the view tab is deselected;
* - this is a child 'dialog' or 'view' and its 'displayParent' is detached;
*/
protected _detach(): void;
renderInitialFocus(): void;
/**
* This method returns the HtmlElement (DOM node) which is used by FocusManager/FocusContext/Popup
* to focus the initial element. The impl. of these classes relies on HtmlElements, so we can not
* easily use the focus() method of FormField here. Furthermore, some classes like Button
* are sometimes 'adapted' by a ButtonAdapterMenu, which means the Button itself is not rendered, but
* we must know the $container of the adapter menu to focus the correct element. That's why we call
* the getFocusableElement() method.
*/
protected _initialFocusElement(): any;
protected _installFocusContext(): void;
protected _uninstallFocusContext(): void;
/**
* Touches the {@link rootGroupBox} so that {@link saveNeeded} returns true even if no field value has changed.
*
* @see GroupBox.touch
* @see markAsSaved
*/
touch(): void;
/**
* Function required for objects that act as 'displayParent'.
*
* @returns true if this form is currently accessible to the user
*/
inFront(): boolean;
/**
* Visits all form-fields of this form in pre-order (top-down).
*/
visitFields(visitor: (FormField: any) => TreeVisitResult | void): void;
/**
* Visits all dialogs, messageBoxes and fileChoosers of this form in pre-order (top-down).
* filter is an optional parameter.
*/
visitDisplayChildren(visitor: (child: Form | MessageBox | FileChooser) => void, filter?: (child: Form | MessageBox | FileChooser) => boolean): void;
storeCacheBounds(bounds: Rectangle): void;
readCacheBounds(): Rectangle;
protected _getCacheBoundsStorageKey(): string;
/** @see BusySupport.setBusy */
setBusy(busy: boolean | BusyIndicatorOptions): void;
/**
* @returns the form the widget belongs to (returns the first parent which is a {@link Form}).
*/
static findForm(widget: Widget): Form;
/**
* @returns the first form which is not an inner form of a wrapped form field
*/
static findNonWrappedForm(widget: Widget): Form;
}
export type FormValidator = (form: Form) => Status | JQuery.Promise<Status>;
//# sourceMappingURL=Form.d.ts.map