@eclipse-scout/core

/// <reference types="jquery" /> import { AbstractLayout, Action, CloneOptions, Column, DragAndDropHandler, DragAndDropOptions, DropType, EnumObject, EventHandler, FieldStatus, FormFieldEventMap, FormFieldModel, FormFieldValidationResultProvider, GridData, GroupBox, HierarchyChangeEvent, InitModelOf, KeyStrokeContext, LoadingSupport, Menu, ObjectOrChildModel, ObjectOrModel, ObjectOrType, Predicate, PropertyChangeEvent, Status, StatusMenuMapping, StatusOrModel, TableRow, Tooltip, TooltipSupport, TreeVisitor, TreeVisitResult, Widget } from '../../index'; /** * Base class for all form-fields. */ export declare class FormField extends Widget implements FormFieldModel { model: FormFieldModel; eventMap: FormFieldEventMap; self: FormField; dropType: DropType; dropMaximumSize: number; empty: boolean; errorStatus: Status; fieldStyle: FormFieldStyle; gridData: GridData; gridDataHints: GridData; mode: FormFieldMode; fieldStatus: FieldStatus; keyStrokes: Action[]; displayText: string; label: string; labelVisible: boolean; labelPosition: FormFieldLabelPosition; labelWidthInPixel: number; labelUseUiWidth: boolean; labelHtmlEnabled: boolean; mandatory: boolean; statusMenuMappings: StatusMenuMapping[]; menus: Menu[]; menusVisible: boolean; defaultMenuTypes: string[]; preventInitialFocus: boolean; /** If set to true, the field needs to be saved. This will be computed by {@link computeSaveNeeded}. */ saveNeeded: boolean; checkSaveNeeded: boolean; lifecycleBoundary: boolean; statusPosition: FormFieldStatusPosition; statusVisible: boolean; suppressStatus: FormFieldSuppressStatus; /** If set to true, {@link saveNeeded} will return true as well, even if the value has not been changed. */ touched: boolean; tooltipText: string; font: string; foregroundColor: string; backgroundColor: string; labelFont: string; labelForegroundColor: string; labelBackgroundColor: string; tooltipAnchor: FormFieldTooltipAnchor; onFieldTooltipOptionsCreator: (this: FormField) => InitModelOf<TooltipSupport>; dragAndDropHandler: DragAndDropHandler; validationResultProvider: FormFieldValidationResultProvider; $label: JQuery; /** * Note the difference between $field and $fieldContainer: * - $field points to the input-field (typically a browser-text field) * - $fieldContainer could point to the same input-field or when the field is a composite, * to the parent DIV of that composite. For instance: the multi-line-smartfield is a * composite with an input-field and a DIV showing the additional lines. In that case $field * points to the input-field and $fieldContainer to the parent DIV of the input-field. * This property should be used primarily for layout-functionality. */ $field: JQuery; $clearIcon: JQuery; $fieldContainer: JQuery; $icon: JQuery; $pseudoStatus: JQuery; /** * The status is used for error-status, tooltip-icon and menus. */ $status: JQuery; $mandatory: JQuery; protected _menuPropertyChangeHandler: EventHandler<PropertyChangeEvent<any, Menu>>; protected _hierarchyChangeHandler: EventHandler<HierarchyChangeEvent>; constructor(); static FieldStyle: { readonly CLASSIC: "classic"; readonly ALTERNATIVE: "alternative"; }; static SuppressStatus: { /** * Suppress status on icon and field (CSS class). */ readonly ALL: "all"; /** * Suppress status on icon, but still show status on field (CSS class). */ readonly ICON: "icon"; /** * Suppress status on field (CSS class), but still show status as icon. */ readonly FIELD: "field"; }; /** Global variable to make it easier to adjust the default field style for all fields */ static DEFAULT_FIELD_STYLE: "alternative"; static StatusPosition: { readonly DEFAULT: "default"; readonly TOP: "top"; }; static LabelPosition: { readonly DEFAULT: 0; readonly LEFT: 1; readonly ON_FIELD: 2; readonly RIGHT: 3; readonly TOP: 4; readonly BOTTOM: 5; }; static TooltipAnchor: { readonly DEFAULT: "default"; readonly ON_FIELD: "onField"; }; static LabelWidth: { readonly DEFAULT: 0; readonly UI: -1; }; static FULL_WIDTH: number; static Mode: { readonly DEFAULT: "default"; readonly CELLEDITOR: "celleditor"; }; static SEVERITY_CSS_CLASSES: string; protected _createKeyStrokeContext(): KeyStrokeContext; protected _createLoadingSupport(): LoadingSupport; protected _init(model: InitModelOf<this>): void; protected _destroy(): void; protected _initProperty(propertyName: string, value: any): void; /** * This function <strong>extends</strong> the default grid data hints of the form field. * The default values for grid data hints are set in the constructor of the FormField and its subclasses. * When the given gridDataHints is a plain object, we extend our default values. When gridDataHints is * already instanceof GridData we overwrite default values completely. */ private _initGridDataHints; /** * All subclasses of FormField should implement a _render method. It should call the various add* methods provided by the FormField class. * * A possible _render implementation could look like this. * <pre> * this.addContainer(this.$parent, 'form-field'); * this.addLabel(); * this.addField(this.$parent.makeDiv('foo', 'bar')); * this.addMandatoryIndicator(); * this.addStatus(); * </pre> */ protected _render(): void; protected _renderProperties(): void; protected _remove(): void; /** @see FormFieldModel.fieldStyle */ setFieldStyle(fieldStyle: FormFieldStyle): void; protected _renderFieldStyle(): void; protected _renderFieldStyleInternal($element: JQuery): void; /** @see FormFieldModel.mandatory */ setMandatory(mandatory: boolean): void; protected _renderMandatory(): void; /** * Override this function to return another error status property. * The default implementation returns the property 'errorStatus'. */ protected _errorStatus(): Status; /** @see FormFieldModel.errorStatus */ setErrorStatus(errorStatus: StatusOrModel): void; protected _setErrorStatus(errorStatus: StatusOrModel): void; /** * Adds the given (functional) error status to the list of error status. Prefer this function over #setErrorStatus * when you don't want to mess with the internal error states of the field (parsing, validation). */ addErrorStatus(errorStatus: string | Status): void; /** * Create an error status with severity {@link Status.Severity.ERROR} containing the given message. * * @param message The message for the error status. * @returns containing the given message. */ protected _createErrorStatus(message: string): Status; /** * Whether the error status is or has the given status type. */ containsStatus(statusType: abstract new () => Status): boolean; /** @see FormFieldModel.suppressStatus */ setSuppressStatus(suppressStatus: FormFieldSuppressStatus): void; protected _renderSuppressStatus(): void; /** * @returns Whether or not error status icon is suppressed */ protected _isSuppressStatusIcon(): boolean; /** * @returns Whether or not error status CSS class is suppressed on field */ protected _isSuppressStatusField(): boolean; /** * Removes all status (incl. children) with the given type. */ removeErrorStatus(statusType: new () => Status): void; removeErrorStatusByPredicate(predicate: Predicate<Status>): void; clearErrorStatus(): void; /** @internal */ _renderErrorStatus(): void; protected _updateErrorStatusClasses(statusClass: string, hasStatus: boolean): void; protected _updateErrorStatusClassesOnElement($element: JQuery, statusClass: string, hasStatus: boolean): void; /** @see FormFieldModel.tooltipText */ setTooltipText(tooltipText: string): void; /** @internal */ _renderTooltipText(): void; /** @see FormFieldModel.tooltipAnchor */ setTooltipAnchor(tooltipAnchor: FormFieldTooltipAnchor): void; protected _renderTooltipAnchor(): void; protected _updateTooltip(): void; hasStatusTooltip(): boolean; hasOnFieldTooltip(): boolean; /** @see FormFieldModel.onFieldTooltipOptionsCreator */ setOnFieldTooltipOptionsCreator(onFieldTooltipOptionsCreator: (this: FormField) => InitModelOf<TooltipSupport>): void; protected _createOnFieldTooltipOptions(): InitModelOf<TooltipSupport>; protected _renderVisible(): void; /** @see FormFieldModel.label */ setLabel(label: string): void; protected _renderLabel(): void; /** * Renders an empty label for button-like fields that don't have a regular label but which do want to support the 'labelVisible' * property in order to provide some layout-flexibility. Makes sure the empty label has the same height as the other labels, * which is especially important for top labels. */ protected _renderEmptyLabel(): void; protected _renderPlaceholder($field?: JQuery): void; /** * @param $field argument is required by DateField.js, when not set this.$field is used */ protected _removePlaceholder($field?: JQuery): void; /** @see FormFieldModel.labelVisible */ setLabelVisible(visible: boolean): void; protected _renderLabelVisible(): void; /** @see FormFieldModel.labelWidthInPixel */ setLabelWidthInPixel(labelWidthInPixel: number): void; protected _renderLabelWidthInPixel(): void; /** @see FormFieldModel.labelUseUiWidth */ setLabelUseUiWidth(labelUseUiWidth: number): void; protected _renderLabelUseUiWidth(): void; /** @see FormFieldModel.statusVisible */ setStatusVisible(visible: boolean): void; protected _renderStatusVisible(): void; /** @see FormFieldModel.statusPosition */ setStatusPosition(statusPosition: FormFieldStatusPosition): void; protected _renderStatusPosition(): void; /** * The tooltip of the {@link fieldStatus}, if it is shown. */ tooltip(): Tooltip; protected _updateFieldStatus(): void; protected _isInitialShowStatus(): boolean; /** * Computes whether the $status should be visible based on statusVisible, errorStatus and tooltip. * -> errorStatus and tooltip override statusVisible, so $status may be visible event though statusVisible is set to false */ protected _computeStatusVisible(): boolean; protected _renderChildVisible($child: JQuery, visible: boolean): boolean; /** @see FormFieldModel.labelPosition */ setLabelPosition(labelPosition: FormFieldLabelPosition): void; protected _renderLabelPosition(): void; /** @see FormFieldModel.labelHtmlEnabled */ setLabelHtmlEnabled(labelHtmlEnabled: boolean): void; protected _renderLabelHtmlEnabled(): void; protected _renderEnabled(): void; protected _renderDisabledStyle(): void; /** @see FormFieldModel.font */ setFont(font: string): void; protected _renderFont(): void; /** @see FormFieldModel.foregroundColor */ setForegroundColor(foregroundColor: string): void; protected _renderForegroundColor(): void; /** @see FormFieldModel.backgroundColor */ setBackgroundColor(backgroundColor: string): void; protected _renderBackgroundColor(): void; /** @see FormFieldModel.labelFont */ setLabelFont(labelFont: string): void; protected _renderLabelFont(): void; /** @see FormFieldModel.labelForegroundColor */ setLabelForegroundColor(labelForegroundColor: string): void; protected _renderLabelForegroundColor(): void; /** @see FormFieldModel.labelBackgroundColor */ setLabelBackgroundColor(labelBackgroundColor: string): void; protected _renderLabelBackgroundColor(): void; /** @see FormFieldModel.gridDataHints */ setGridDataHints(gridData: ObjectOrModel<GridData>): void; protected _setGridDataHints(gridData: ObjectOrModel<GridData>): void; protected _renderGridDataHints(): void; /** @internal */ _setGridData(gridData: ObjectOrModel<GridData>): void; protected _renderGridData(): void; /** @see FormFieldModel.menus */ setMenus(menus: ObjectOrChildModel<Menu>[]): void; protected _setMenus(menus: Menu | Menu[]): void; insertMenu(menuToInsert: ObjectOrChildModel<Menu>): void; insertMenus(menusToInsert: ObjectOrChildModel<Menu>[]): void; deleteMenu(menuToDelete: Menu): void; deleteMenus(menusToDelete: Menu[]): void; protected _onMenuPropertyChange(event: PropertyChangeEvent<any, Menu>): void; getContextMenuItems(onlyVisible?: boolean): Menu[]; protected _getMenusForStatus(status: Status): Menu[]; protected _hasMenus(): boolean; /** @internal */ _updateMenus(): void; /** @internal */ _renderMenus(): void; protected _renderStatusMenuMappings(): void; setMenusVisible(menusVisible: boolean): void; protected _setMenusVisible(menusVisible: boolean): void; protected _renderMenusVisible(): void; getCurrentMenuTypes(): string[]; protected _getCurrentMenuTypes(): string[]; protected _setKeyStrokes(keyStrokes: Action[]): void; /** * May be overridden to explicitly provide a tooltip $parent * @internal */ _$tooltipParent(): JQuery; /** @internal */ _hideStatusMessage(): void; protected _renderPreventInitialFocus(): void; /** * Sets the focus on this field. If the field is not rendered, the focus will be set as soon as it is rendered. * @returns true if the element could be focused, false if not */ focus(): boolean; /** * This method returns the HtmlElement to be used as initial focus element or when {@link #focus()} is called. * It can be overridden, in case the FormField needs to return something other than this.$field[0]. */ getFocusableElement(): HTMLElement | JQuery; protected _onFieldFocus(event: JQuery.FocusEvent): void; protected _onFieldBlur(event: JQuery.BlurEvent): void; /** * When calling this function, the same should happen as when clicking into the field. It is used when the label is clicked.<br> * The most basic action is focusing the field but this may differ from field to field. */ activate(): void; get$Scrollable(): JQuery; getParentGroupBox(): GroupBox; getParentField(): FormField; /** * Appends a LABEL element to this.$container and sets the this.$label property. */ addLabel(): void; protected _onLabelClick(event: JQuery.ClickEvent): void; protected _removeLabel(): void; /** * Links the given element with the label by setting aria-labelledby.<br> * This allows screen readers to build a catalog of the elements on the screen and their relationships, for example, to read the label when the input is focused. */ protected _linkWithLabel($element: JQuery): void; protected _removeIcon(): void; /** * Appends the given field to the this.$container and sets the property this.$field. * The $field is used as $fieldContainer as long as you don't explicitly call addFieldContainer before calling addField. */ addField($field: JQuery): void; /** * Call this method before addField if you'd like to have a different field container than $field. */ addFieldContainer($fieldContainer: JQuery): void; /** * Removes this.$field and this.$fieldContainer and sets the properties to null. */ protected _removeField(): void; /** * Appends a span element for form-field status to this.$container and sets the this.$status property. */ addStatus(): void; protected _removeStatus(): void; /** * Appends a span element to this.$container and sets the this.$pseudoStatus property. * The purpose of a pseudo status is to consume the space an ordinary status would. * This makes it possible to make components without a status as width as components with a status. */ addPseudoStatus(): void; addMandatoryIndicator(): void; removeMandatoryIndicator(): void; /** * Adds a span element with class 'icon' the given optional $parent. * When $parent is not set, the element is added to this.$container. */ addIcon($parent?: JQuery): void; protected _onIconMouseDown(event: JQuery.MouseDownEvent): void; /** * Appends a DIV element as form-field container to $parent and sets the this.$container property. * Applies FormFieldLayout to this.$container (if container does not define another layout). * Sets this.htmlComp to the HtmlComponent created for this.$container. * * @param $parent to which container is appended * @param cssClass cssClass to add to the new container DIV * @param layout when layout is undefined, {@link _createLayout} is called * */ addContainer($parent: JQuery, cssClass?: string, layout?: AbstractLayout): void; /** * @returns the default layout FormFieldLayout. Override this function if your field needs another layout. */ protected _createLayout(): AbstractLayout; /** * Updates the "inner alignment" of a field. Usually, the GridData hints only have influence on the LogicalGridLayout. * However, the properties "horizontalAlignment" and "verticalAlignment" are sometimes used differently. * Instead of controlling the field alignment in case fillHorizontal/fillVertical is false, the developer expects the _contents_ of the field to be aligned correspondingly inside the field. * Technically, this is not correct, but is supported for legacy and convenience reasons for some Scout fields. * Those who support the behavior may override _renderGridData() and call this method. * Some CSS classes are then added to the field. */ updateInnerAlignment(opts?: FormFieldAlignmentUpdateOptions): void; protected _updateElementInnerAlignment(opts: FormFieldAlignmentUpdateOptions, $field: JQuery): void; addCellEditorFieldCssClasses($field: JQuery, opts: AddCellEditorFieldCssClassesOptions): void; /** * Called by the {@link CellEditorPopup} after having rendered this field. */ prepareForCellEdit(opts?: AddCellEditorFieldCssClassesOptions): void; /** * Adjusts the field for use as a cell editor field. This operation is irreversible. * The {@link #mode} property is set to {@link FormField.Mode.CELLEDITOR}. * * Unlike {@link #prepareForCellEdit}, this method does not depend on the "rendered" state. * It is called by an editable column just before the cell editor popup is created, see * {@link Column#startCellEdit}. * * @param options * When called by an editable column, this object holds information about the * column and row being edited. */ activateCellEditorMode(options?: FormFieldActivateCellEditorModeOptions): void; /** @see FormFieldModel.dropType */ setDropType(dropType: DropType): void; protected _renderDropType(): void; /** @see FormFieldModel.dropMaximumSize */ setDropMaximumSize(dropMaximumSize: number): void; protected _installOrUninstallDragAndDropHandler(): void; protected _getDragAndDropHandlerOptions(): DragAndDropOptions; /** * Visits this field and all child {@link FormField}s in pre-order (top-down). */ visitFields(visitor: TreeVisitor<FormField>, options?: VisitFieldsOptions): TreeVisitResult; visitFirstChildFields(visitor: TreeVisitor<FormField>): void; /** * Visits all parent form fields. * To stop the visiting if the parent field is no form field anymore (e.g. a form or the desktop), you can set {@link VisitParentFieldsOptions.limitToSameFieldTree} to true. */ visitParentFields(visitor: (parent: FormField) => void, options?: VisitParentFieldsOptions): void; /** * Sets {@link saveNeeded} and {@link touched} to false on this field and every child field. **/ markAsSaved(): void; protected _markAsSaved(): void; /** * Marks the field as {@link touched} which means {@link saveNeeded} will return true even if the value has not been changed. **/ touch(): void; /** * Updates {@link saveNeeded} depending on whether the field was {@link touched} using {@link touch} or {@link computeSaveNeeded} returns true. * * @param child the child updating its save needed state and informing its parent about it. If passed and `child.saveNeeded` is true, {@link computeSaveNeeded} will be skipped. */ updateSaveNeeded(child?: FormField): void; protected _setSaveNeeded(saveNeeded: boolean): void; setCheckSaveNeeded(checkSaveNeeded: boolean): void; /** * Used by {@link updateSaveNeeded} to update the {@link saveNeeded} property. * * By default, all first level child fields are checked. The method returns true, if one of these fields needs to be saved. */ computeSaveNeeded(): boolean; getValidationResult(): ValidationResult; protected _createValidationResultProvider(): FormFieldValidationResultProvider; /** @see FormFieldModel.validationResultProvider */ setValidationResultProvider(provider: ObjectOrType<FormFieldValidationResultProvider>): void; protected _setValidationResultProvider(provider: ObjectOrType<FormFieldValidationResultProvider>): void; protected _updateEmpty(): void; /** * @returns true if the field is considered empty, false if not. * Mandatory fields that are empty will return a {@link ValidationResult} with {@link ValidationResult.valid} and {@link ValidationResult.validByMandatory} set to false. * * @see getValidationResult */ protected _computeEmpty(): boolean; requestInput(): void; clone(model: FormFieldModel, options?: CloneOptions): this; exportToClipboard(): void; protected _exportToClipboard(text: string): void; /** * Updates save needed state on parent field if the hierarchy changed, e.g. if the field was moved into another composite field. * Also handles the case where a field is not directly connected to a form field parent, but has a non-form-field in between * (e.g. FormFieldMenu has a Menu as parent -> if the menu is moved the state needs to be recomputed as well). */ protected _watchFieldHierarchy(parent?: Widget): void; protected _unwatchFieldHierarchy(oldParent?: Widget): void; protected _onHierarchyChange(event: HierarchyChangeEvent): void; protected _visitParentsUntilField(parent: Widget, visitor: (parent: Widget) => void): FormField; } export type FormFieldStyle = EnumObject<typeof FormField.FieldStyle>; export type FormFieldSuppressStatus = EnumObject<typeof FormField.SuppressStatus>; export type FormFieldStatusPosition = EnumObject<typeof FormField.StatusPosition>; export type FormFieldLabelPosition = EnumObject<typeof FormField.LabelPosition>; export type FormFieldTooltipAnchor = EnumObject<typeof FormField.TooltipAnchor>; export type FormFieldLabelWidth = EnumObject<typeof FormField.LabelWidth>; export type FormFieldMode = EnumObject<typeof FormField.Mode>; export type FormFieldAlignmentUpdateOptions = { /** * When this option is true, "halign-" classes are added according to gridData.horizontalAlignment. Default is true. */ useHorizontalAlignment?: boolean; /** * When this option is true, "valign-" classes are added according to gridData.verticalAlignment. Default is true. */ useVerticalAlignment?: boolean; /** * Specifies the div where the classes should be added. If omitted, this.$fieldContainer is used. */ $fieldContainer?: JQuery; }; /** * Contains information about the validity of a form field and how to reveal it if it is invalid. */ export type ValidationResult = { valid: boolean; validByMandatory: boolean; errorStatus?: Status; field: FormField; label: string; reveal: () => void; visitResult?: TreeVisitResult; }; export type AddCellEditorFieldCssClassesOptions = { cssClass?: string; }; export type FormFieldActivateCellEditorModeOptions = { column?: Column<any>; row?: TableRow; }; export interface VisitParentFieldsOptions { /** * If set to true, visiting stops if a parent is not a form field. * * For example: if a group box has a {@link FormFieldMenu}, which is a menu containing a form field, the group box containing the menu won't be visited when the visiting starts at the form field. * * Default is false. */ limitToSameFieldTree?: boolean; } export interface VisitFieldsOptions { /** * If set to true, visiting the subtree of a child is skipped if the child is a form field. This means only the form fields are considered that are nearest to the field where the visiting started. * * For example: if a group box has a form field and a menu with a form field, both fields would be visited but the children of these fields would not. * * Default is false. */ firstLevelFieldsOnly?: boolean; /** * If set to true, visiting of a child and its subtree is skipped if that child is not a form field, even if it would contain form fields itself. * * For example: if a group box has a {@link FormFieldMenu}, which is a menu containing a form field, the form field inside the menu won't be visited after visiting the group box. * * Default is false. */ limitToSameFieldTree?: boolean; /** * If set to true, the field that started the visiting will be visited as well, otherwise only the children will be visited. * * Default is true. */ visitSelf?: boolean; } //# sourceMappingURL=FormField.d.ts.map