blockly
Version:
Blockly is a library for building visual programming editors.
295 lines • 10.8 kB
TypeScript
/**
* @license
* Copyright 2012 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import { Field, FieldConfig, FieldValidator } from './field.js';
import { Menu } from './menu.js';
import { MenuItem } from './menuitem.js';
/**
* Class for an editable dropdown field.
*/
export declare class FieldDropdown extends Field<string> {
/**
* Magic constant used to represent a separator in a list of dropdown items.
*/
static readonly SEPARATOR = "separator";
static ARROW_CHAR: string;
/** A reference to the currently selected menu item. */
private selectedMenuItem;
/** The dropdown menu. */
protected menu_: Menu | null;
/**
* SVG image element if currently selected option is an image, or null.
*/
private imageElement;
/** Tspan based arrow element. */
private arrow;
/** SVG based arrow element. */
private svgArrow;
/**
* Serializable fields are saved by the serializer, non-serializable fields
* are not. Editable fields should also be serializable.
*/
SERIALIZABLE: boolean;
protected menuGenerator_?: MenuGenerator;
/** A cache of the most recently generated options. */
private generatedOptions;
/**
* The prefix field label, of common words set after options are trimmed.
*
* @internal
*/
prefixField: string | null;
/**
* The suffix field label, of common words set after options are trimmed.
*
* @internal
*/
suffixField: string | null;
private selectedOption;
clickTarget_: SVGElement | null;
/**
* The y offset from the top of the field to the top of the image, if an image
* is selected.
*/
protected static IMAGE_Y_OFFSET: number;
/** The total vertical padding above and below an image. */
protected static IMAGE_Y_PADDING: number;
/**
* @param menuGenerator A non-empty array of options for a dropdown list, or a
* function which generates these options. Also accepts Field.SKIP_SETUP
* if you wish to skip setup (only used by subclasses that want to handle
* configuration and setting the field value after their own constructors
* have run).
* @param validator A function that is called to validate changes to the
* field's value. Takes in a language-neutral dropdown option & returns a
* validated language-neutral dropdown option, or null to abort the
* change.
* @param config A map of options used to configure the field.
* See the [field creation documentation]{@link
* https://developers.google.com/blockly/guides/create-custom-blocks/fields/built-in-fields/dropdown#creation}
* for a list of properties this parameter supports.
* @throws {TypeError} If `menuGenerator` options are incorrectly structured.
*/
constructor(menuGenerator: MenuGenerator, validator?: FieldDropdownValidator, config?: FieldDropdownConfig);
constructor(menuGenerator: typeof Field.SKIP_SETUP);
/**
* Sets the field's value based on the given XML element. Should only be
* called by Blockly.Xml.
*
* @param fieldElement The element containing info about the field's state.
* @internal
*/
fromXml(fieldElement: Element): void;
/**
* Sets the field's value based on the given state.
*
* @param state The state to apply to the dropdown field.
* @internal
*/
loadState(state: any): void;
/**
* Create the block UI for this dropdown.
*/
initView(): void;
/**
* Whether or not the dropdown should add a border rect.
*
* @returns True if the dropdown field should add a border rect.
*/
protected shouldAddBorderRect_(): boolean;
/** Create a tspan based arrow. */
protected createTextArrow_(): void;
/** Create an SVG based arrow. */
protected createSVGArrow_(): void;
/**
* Create a dropdown menu under the text.
*
* @param e Optional mouse event that triggered the field to open, or
* undefined if triggered programmatically.
*/
protected showEditor_(e?: MouseEvent): void;
/** Create the dropdown editor. */
private dropdownCreate;
/**
* Disposes of events and DOM-references belonging to the dropdown editor.
*/
protected dropdownDispose_(): void;
/**
* Handle an action in the dropdown menu.
*
* @param menuItem The MenuItem selected within menu.
*/
private handleMenuActionEvent;
/**
* Handle the selection of an item in the dropdown menu.
*
* @param menu The Menu component clicked.
* @param menuItem The MenuItem selected within menu.
*/
protected onItemSelected_(menu: Menu, menuItem: MenuItem): void;
/**
* @returns True if the option list is generated by a function.
* Otherwise false.
*/
isOptionListDynamic(): boolean;
/**
* Return a list of the options for this dropdown.
*
* @param useCache For dynamic options, whether or not to use the cached
* options or to re-generate them.
* @returns A non-empty array of option tuples:
* (human-readable text or image, language-neutral name).
* @throws {TypeError} If generated options are incorrectly structured.
*/
getOptions(useCache?: boolean): MenuOption[];
/**
* Update the options on this dropdown. This will reset the selected item to
* the first item in the list.
*
* @param menuGenerator The array of options or a generator function.
*/
setOptions(menuGenerator: MenuGenerator): void;
/**
* Ensure that the input value is a valid language-neutral option.
*
* @param newValue The input value.
* @returns A valid language-neutral option, or null if invalid.
*/
protected doClassValidation_(newValue: string): string | null | undefined;
protected doClassValidation_(newValue?: string): string | null;
/**
* Update the value of this dropdown field.
*
* @param newValue The value to be saved. The default validator guarantees
* that this is one of the valid dropdown options.
*/
protected doValueUpdate_(newValue: string): void;
/**
* Updates the dropdown arrow to match the colour/style of the block.
*/
applyColour(): void;
/** Draws the border with the correct width. */
protected render_(): void;
/**
* Renders the selected option, which must be an image.
*
* @param imageJson Selected option that must be an image.
*/
private renderSelectedImage;
/** Renders the selected option, which must be text. */
private renderSelectedText;
/**
* Position a drop-down arrow at the appropriate location at render-time.
*
* @param x X position the arrow is being rendered at, in px.
* @param y Y position the arrow is being rendered at, in px.
* @returns Amount of space the arrow is taking up, in px.
*/
private positionSVGArrow;
/**
* Use the `getText_` developer hook to override the field's text
* representation. Get the selected option text. If the selected option is
* an image we return the image alt text. If the selected option is
* an HTMLElement, return the title, ariaLabel, or innerText of the
* element.
*
* If you use HTMLElement options in Node.js and call this function,
* ensure that you are supplying an implementation of HTMLElement,
* such as through jsdom-global.
*
* @returns Selected option text.
*/
protected getText_(): string | null;
/**
* Construct a FieldDropdown from a JSON arg object.
*
* @param options A JSON object with options (options).
* @returns The new field instance.
* @nocollapse
* @internal
*/
static fromJson(options: FieldDropdownFromJsonConfig): FieldDropdown;
/**
* Factor out common words in statically defined options.
* Create prefix and/or suffix labels.
*/
protected trimOptions(options: MenuOption[]): {
options: MenuOption[];
prefix?: string;
suffix?: string;
};
/**
* Use the calculated prefix and suffix lengths to trim all of the options in
* the given array.
*
* @param options Array of option tuples:
* (human-readable text or image, language-neutral name).
* @param prefixLength The length of the common prefix.
* @param suffixLength The length of the common suffix
* @returns A new array with all of the option text trimmed.
*/
private applyTrim;
/**
* Validates the data structure to be processed as an options list.
*
* @param options The proposed dropdown options.
* @throws {TypeError} If proposed options are incorrectly structured.
*/
protected validateOptions(options: MenuOption[]): void;
}
/**
* Definition of a human-readable image dropdown option.
*/
export interface ImageProperties {
src: string;
alt: string;
width: number;
height: number;
}
/**
* An individual option in the dropdown menu. Can be either the string literal
* `separator` for a menu separator item, or an array for normal action menu
* items. In the latter case, the first element is the human-readable value
* (text, ImageProperties object, or HTML element), and the second element is
* the language-neutral value.
*/
export type MenuOption = [string | ImageProperties | HTMLElement, string] | 'separator';
/**
* A function that generates an array of menu options for FieldDropdown
* or its descendants.
*/
export type MenuGeneratorFunction = (this: FieldDropdown) => MenuOption[];
/**
* Either an array of menu options or a function that generates an array of
* menu options for FieldDropdown or its descendants.
*/
export type MenuGenerator = MenuOption[] | MenuGeneratorFunction;
/**
* Config options for the dropdown field.
*/
export type FieldDropdownConfig = FieldConfig;
/**
* fromJson config for the dropdown field.
*/
export interface FieldDropdownFromJsonConfig extends FieldDropdownConfig {
options?: MenuOption[];
}
/**
* A function that is called to validate changes to the field's value before
* they are set.
*
* @see {@link https://developers.google.com/blockly/guides/create-custom-blocks/fields/validators#return_values}
* @param newValue The value to be validated.
* @returns One of three instructions for setting the new value: `T`, `null`,
* or `undefined`.
*
* - `T` to set this function's returned value instead of `newValue`.
*
* - `null` to invoke `doValueInvalid_` and not set a value.
*
* - `undefined` to set `newValue` as is.
*/
export type FieldDropdownValidator = FieldValidator<string>;
//# sourceMappingURL=field_dropdown.d.ts.map