blockly 8.0.4 → 8.0.5-beta.0

package/core/field_checkbox.ts

@@ -0,0 +1,243 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Checkbox field.  Checked or not checked.
+ */
+
+/**
+ * Checkbox field.  Checked or not checked.
+ * @class
+ */
+import * as goog from '../closure/goog/goog.js';
+goog.declareModuleId('Blockly.FieldCheckbox');
+
+// Unused import preserved for side-effects. Remove if unneeded.
+import './events/events_block_change.js';
+
+import {FieldConfig, Field} from './field.js';
+import * as fieldRegistry from './field_registry.js';
+import * as dom from './utils/dom.js';
+import type {Sentinel} from './utils/sentinel.js';
+
+
+/**
+ * Class for a checkbox field.
+ * @alias Blockly.FieldCheckbox
+ */
+export class FieldCheckbox extends Field {
+  /** Default character for the checkmark. */
+  static readonly CHECK_CHAR = '\u2713';
+  private checkChar_: string;
+
+  /**
+   * Serializable fields are saved by the serializer, non-serializable fields
+   * are not. Editable fields should also be serializable.
+   */
+  override SERIALIZABLE = true;
+
+  /**
+   * Mouse cursor style when over the hotspot that initiates editability.
+   */
+  override CURSOR = 'default';
+  override value_: AnyDuringMigration;
+
+  /**
+   * @param opt_value The initial value of the field. Should either be 'TRUE',
+   *     'FALSE' or a boolean. Defaults to 'FALSE'. 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 opt_validator  A function that is called to validate changes to the
+   *     field's value. Takes in a value ('TRUE' or 'FALSE') & returns a
+   *     validated value ('TRUE' or 'FALSE'), or null to abort the change.
+   * @param opt_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/checkbox#creation}
+   * for a list of properties this parameter supports.
+   */
+  constructor(
+      opt_value?: string|boolean|Sentinel, opt_validator?: Function,
+      opt_config?: FieldCheckboxConfig) {
+    super(Field.SKIP_SETUP);
+
+    /**
+     * Character for the check mark. Used to apply a different check mark
+     * character to individual fields.
+     */
+    this.checkChar_ = FieldCheckbox.CHECK_CHAR;
+
+    if (opt_value === Field.SKIP_SETUP) {
+      return;
+    }
+    if (opt_config) {
+      this.configure_(opt_config);
+    }
+    this.setValue(opt_value);
+    if (opt_validator) {
+      this.setValidator(opt_validator);
+    }
+  }
+
+  /**
+   * Configure the field based on the given map of options.
+   * @param config A map of options to configure the field based on.
+   */
+  protected override configure_(config: FieldCheckboxConfig) {
+    super.configure_(config);
+    if (config.checkCharacter) this.checkChar_ = config.checkCharacter;
+  }
+
+  /**
+   * Saves this field's value.
+   * @return The boolean value held by this field.
+   * @internal
+   */
+  override saveState(): AnyDuringMigration {
+    const legacyState = this.saveLegacyState(FieldCheckbox);
+    if (legacyState !== null) {
+      return legacyState;
+    }
+    return this.getValueBoolean();
+  }
+
+  /**
+   * Create the block UI for this checkbox.
+   * @internal
+   */
+  override initView() {
+    super.initView();
+
+    dom.addClass((this.textElement_), 'blocklyCheckbox');
+    this.textElement_.style.display = this.value_ ? 'block' : 'none';
+  }
+
+  override render_() {
+    if (this.textContent_) {
+      this.textContent_.nodeValue = this.getDisplayText_();
+    }
+    this.updateSize_(this.getConstants()!.FIELD_CHECKBOX_X_OFFSET);
+  }
+
+  override getDisplayText_() {
+    return this.checkChar_;
+  }
+
+  /**
+   * Set the character used for the check mark.
+   * @param character The character to use for the check mark, or null to use
+   *     the default.
+   */
+  setCheckCharacter(character: string|null) {
+    this.checkChar_ = character || FieldCheckbox.CHECK_CHAR;
+    this.forceRerender();
+  }
+
+  /** Toggle the state of the checkbox on click. */
+  protected override showEditor_() {
+    this.setValue(!this.value_);
+  }
+
+  /**
+   * Ensure that the input value is valid ('TRUE' or 'FALSE').
+   * @param opt_newValue The input value.
+   * @return A valid value ('TRUE' or 'FALSE), or null if invalid.
+   */
+  protected override doClassValidation_(opt_newValue?: AnyDuringMigration):
+      string|null {
+    if (opt_newValue === true || opt_newValue === 'TRUE') {
+      return 'TRUE';
+    }
+    if (opt_newValue === false || opt_newValue === 'FALSE') {
+      return 'FALSE';
+    }
+    return null;
+  }
+
+  /**
+   * Update the value of the field, and update the checkElement.
+   * @param newValue The value to be saved. The default validator guarantees
+   *     that this is a either 'TRUE' or 'FALSE'.
+   */
+  protected override doValueUpdate_(newValue: AnyDuringMigration) {
+    this.value_ = this.convertValueToBool_(newValue);
+    // Update visual.
+    if (this.textElement_) {
+      this.textElement_.style.display = this.value_ ? 'block' : 'none';
+    }
+  }
+
+  /**
+   * Get the value of this field, either 'TRUE' or 'FALSE'.
+   * @return The value of this field.
+   */
+  override getValue(): string {
+    return this.value_ ? 'TRUE' : 'FALSE';
+  }
+
+  /**
+   * Get the boolean value of this field.
+   * @return The boolean value of this field.
+   */
+  getValueBoolean(): boolean {
+    return this.value_ as boolean;
+  }
+
+  /**
+   * Get the text of this field. Used when the block is collapsed.
+   * @return Text representing the value of this field ('true' or 'false').
+   */
+  override getText(): string {
+    return String(this.convertValueToBool_(this.value_));
+  }
+
+  /**
+   * Convert a value into a pure boolean.
+   *
+   * Converts 'TRUE' to true and 'FALSE' to false correctly, everything else
+   * is cast to a boolean.
+   * @param value The value to convert.
+   * @return The converted value.
+   */
+  private convertValueToBool_(value: AnyDuringMigration): boolean {
+    if (typeof value === 'string') {
+      return value === 'TRUE';
+    } else {
+      return !!value;
+    }
+  }
+
+  /**
+   * Construct a FieldCheckbox from a JSON arg object.
+   * @param options A JSON object with options (checked).
+   * @return The new field instance.
+   * @nocollapse
+   * @internal
+   */
+  static fromJson(options: FieldCheckboxFromJsonConfig): FieldCheckbox {
+    // `this` might be a subclass of FieldCheckbox if that class doesn't
+    // 'override' the static fromJson method.
+    return new this(options.checked, undefined, options);
+  }
+}
+
+fieldRegistry.register('field_checkbox', FieldCheckbox);
+
+(FieldCheckbox.prototype as AnyDuringMigration).DEFAULT_VALUE = false;
+
+/**
+ * Config options for the checkbox field.
+ */
+export interface FieldCheckboxConfig extends FieldConfig {
+  checkCharacter?: string;
+}
+
+/**
+ * fromJson config options for the checkbox field.
+ */
+export interface FieldCheckboxFromJsonConfig extends FieldCheckboxConfig {
+  checked?: boolean;
+}

package/core/field_colour.d.ts

@@ -0,0 +1,200 @@
+/**
+ * @license
+ * Copyright 2012 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import './events/events_block_change.js';
+import { FieldConfig, Field } from './field.js';
+import type { Sentinel } from './utils/sentinel.js';
+/**
+ * Class for a colour input field.
+ * @alias Blockly.FieldColour
+ */
+export declare class FieldColour extends Field {
+    /**
+     * An array of colour strings for the palette.
+     * Copied from goog.ui.ColorPicker.SIMPLE_GRID_COLORS
+     * All colour pickers use this unless overridden with setColours.
+     */
+    static COLOURS: string[];
+    /**
+     * An array of tooltip strings for the palette.  If not the same length as
+     * COLOURS, the colour's hex code will be used for any missing titles.
+     * All colour pickers use this unless overridden with setColours.
+     */
+    static TITLES: string[];
+    /**
+     * Number of columns in the palette.
+     * All colour pickers use this unless overridden with setColumns.
+     */
+    static COLUMNS: number;
+    /** The field's colour picker element. */
+    private picker_;
+    /** Index of the currently highlighted element. */
+    private highlightedIndex_;
+    /** Mouse click event data. */
+    private onClickWrapper_;
+    /** Mouse move event data. */
+    private onMouseMoveWrapper_;
+    /** Mouse enter event data. */
+    private onMouseEnterWrapper_;
+    /** Mouse leave event data. */
+    private onMouseLeaveWrapper_;
+    /** Key down event data. */
+    private onKeyDownWrapper_;
+    /**
+     * Serializable fields are saved by the serializer, non-serializable fields
+     * are not. Editable fields should also be serializable.
+     */
+    SERIALIZABLE: boolean;
+    /** Mouse cursor style when over the hotspot that initiates the editor. */
+    CURSOR: string;
+    /**
+     * Used to tell if the field needs to be rendered the next time the block is
+     * rendered. Colour fields are statically sized, and only need to be
+     * rendered at initialization.
+     */
+    protected isDirty_: boolean;
+    /** Array of colours used by this field.  If null, use the global list. */
+    private colours_;
+    /**
+     * Array of colour tooltips used by this field.  If null, use the global
+     * list.
+     */
+    private titles_;
+    /**
+     * Number of colour columns used by this field.  If 0, use the global
+     * setting. By default use the global constants for columns.
+     */
+    private columns_;
+    size_: any;
+    clickTarget_: any;
+    value_: any;
+    /**
+     * @param opt_value The initial value of the field. Should be in '#rrggbb'
+     *     format. Defaults to the first value in the default colour array. 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 opt_validator A function that is called to validate changes to the
+     *     field's value. Takes in a colour string & returns a validated colour
+     *     string ('#rrggbb' format), or null to abort the change.Blockly.
+     * @param opt_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/colour}
+     * for a list of properties this parameter supports.
+     */
+    constructor(opt_value?: string | Sentinel, opt_validator?: Function, opt_config?: FieldColourConfig);
+    /**
+     * Configure the field based on the given map of options.
+     * @param config A map of options to configure the field based on.
+     */
+    protected configure_(config: FieldColourConfig): void;
+    /**
+     * Create the block UI for this colour field.
+     * @internal
+     */
+    initView(): void;
+    applyColour(): void;
+    /**
+     * Ensure that the input value is a valid colour.
+     * @param opt_newValue The input value.
+     * @return A valid colour, or null if invalid.
+     */
+    protected doClassValidation_(opt_newValue?: any): string | null;
+    /**
+     * Update the value of this colour field, and update the displayed colour.
+     * @param newValue The value to be saved. The default validator guarantees
+     *     that this is a colour in '#rrggbb' format.
+     */
+    protected doValueUpdate_(newValue: any): void;
+    /**
+     * Get the text for this field.  Used when the block is collapsed.
+     * @return Text representing the value of this field.
+     */
+    getText(): string;
+    /**
+     * Set a custom colour grid for this field.
+     * @param colours Array of colours for this block, or null to use default
+     *     (FieldColour.COLOURS).
+     * @param opt_titles Optional array of colour tooltips, or null to use default
+     *     (FieldColour.TITLES).
+     * @return Returns itself (for method chaining).
+     */
+    setColours(colours: string[], opt_titles?: string[]): FieldColour;
+    /**
+     * Set a custom grid size for this field.
+     * @param columns Number of columns for this block, or 0 to use default
+     *     (FieldColour.COLUMNS).
+     * @return Returns itself (for method chaining).
+     */
+    setColumns(columns: number): FieldColour;
+    /** Create and show the colour field's editor. */
+    protected showEditor_(): void;
+    /**
+     * Handle a click on a colour cell.
+     * @param e Mouse event.
+     */
+    private onClick_;
+    /**
+     * Handle a key down event. Navigate around the grid with the
+     * arrow keys. Enter selects the highlighted colour.
+     * @param e Keyboard event.
+     */
+    private onKeyDown_;
+    /**
+     * Move the currently highlighted position by dx and dy.
+     * @param dx Change of x
+     * @param dy Change of y
+     */
+    private moveHighlightBy_;
+    /**
+     * Handle a mouse move event. Highlight the hovered colour.
+     * @param e Mouse event.
+     */
+    private onMouseMove_;
+    /** Handle a mouse enter event. Focus the picker. */
+    private onMouseEnter_;
+    /**
+     * Handle a mouse leave event. Blur the picker and unhighlight
+     * the currently highlighted colour.
+     */
+    private onMouseLeave_;
+    /**
+     * Returns the currently highlighted item (if any).
+     * @return Highlighted item (null if none).
+     */
+    private getHighlighted_;
+    /**
+     * Update the currently highlighted cell.
+     * @param cell the new cell to highlight
+     * @param index the index of the new cell
+     */
+    private setHighlightedCell_;
+    /** Create a colour picker dropdown editor. */
+    private dropdownCreate_;
+    /** Disposes of events and DOM-references belonging to the colour editor. */
+    private dropdownDispose_;
+    /**
+     * Construct a FieldColour from a JSON arg object.
+     * @param options A JSON object with options (colour).
+     * @return The new field instance.
+     * @nocollapse
+     * @internal
+     */
+    static fromJson(options: FieldColourFromJsonConfig): FieldColour;
+}
+/**
+ * Config options for the colour field.
+ */
+export interface FieldColourConfig extends FieldConfig {
+    colourOptions?: string[];
+    colourTitles?: string[];
+    columns?: number;
+}
+/**
+ * fromJson config options for the colour field.
+ */
+export interface FieldColourFromJsonConfig extends FieldColourConfig {
+    colour?: string;
+}