blockly/core/interfaces/i_grid.ts at 52f9d2a56289ae9e73dd77e86e9d80f6ca245f21 · RaspberryPiFoundation/blockly · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
import {BlocklyOptions} from '../blockly_options.js';
import {GridOptions} from '../options.js';
import {Coordinate} from '../utils';
import type {IRegistrable} from './i_registrable.js';

export interface IGrid {
  /**
   * Sets the spacing between the centers of the grid lines.
   *
   * This does not trigger snapping to the newly spaced grid. If you want to
   * snap blocks to the grid programmatically that needs to be triggered
   * on individual top-level blocks. The next time a block is dragged and
   * dropped it will snap to the grid if snapping to the grid is enabled.
   */
  setSpacing(spacing: number): void;

  /**
   * Get the spacing of the grid points (in px).
   *
   * @returns The spacing of the grid points.
   */
  getSpacing(): number;

  /** Sets the length of the grid lines. */
  setLength(length: number): void;

  /** Get the length of the grid lines (in px). */
  getLength(): number;

  /**
   * Sets whether blocks should snap to the grid or not.
   *
   * Setting this to true does not trigger snapping. If you want to snap blocks
   * to the grid programmatically that needs to be triggered on individual
   * top-level blocks. The next time a block is dragged and dropped it will
   * snap to the grid.
   */
  setSnapToGrid(snap: boolean): void;

  /**
   * Whether blocks should snap to the grid.
   *
   * @returns True if blocks should snap, false otherwise.
   */
  shouldSnap(): boolean;

  /**
   * Get the ID of the pattern element, which should be randomized to avoid
   * conflicts with other Blockly instances on the page.
   *
   * @returns The pattern ID.
   * @internal
   */
  getPatternId(): string;

  /**
   * Update the grid with a new scale.
   *
   * @param scale The new workspace scale.
   * @internal
   */
  update(scale: number): void;

  /**
   * Move the grid to a new x and y position, and make sure that change is
   * visible.
   *
   * @param x The new x position of the grid (in px).
   * @param y The new y position of the grid (in px).
   * @internal
   */
  moveTo(x: number, y: number): void;

  /**
   * Given a coordinate, return the nearest coordinate aligned to the grid.
   *
   * @param xy A workspace coordinate.
   * @returns Workspace coordinate of nearest grid point.
   *   If there's no change, return the same coordinate object.
   */
  alignXY(xy: Coordinate): Coordinate;
}

export interface IGridProvider extends IRegistrable {
  /**
   * Create the DOM for the grid described by options.
   *
   * @param rnd A random ID to append to the pattern's ID.
   * @param gridOptions The object containing grid configuration.
   * @param defs The root SVG element for this workspace's defs.
   * @returns The SVG element for the grid pattern.
   */
  createDom(
    rnd: string,
    gridOptions: GridOptions,
    defs: SVGElement,
  ): SVGElement;

  /**
   * Parse the user-specified grid options, using reasonable defaults where
   * behaviour is unspecified. See grid documentation:
   *   https://developers.google.com/blockly/guides/configure/web/grid
   *
   * @param options Dictionary of options.
   * @returns Normalized grid options.
   */
  parseGridOptions(options: BlocklyOptions): GridOptions;

  /**
   * @param pattern The grid's SVG pattern, created during injection.
   * @param options A dictionary of normalized options for the grid.
   *     See grid documentation:
   *     https://developers.google.com/blockly/guides/configure/web/grid
   */
  createGrid(pattern: SVGElement, options: GridOptions): IGrid;
}