A Blockly plugin that adds advanced scroll options such as scroll-on-drag and scroll while holding a block.
npm install @blockly/plugin-scroll-optionsA Blockly plugin that adds additional
scroll features.
This plugin adds two features related to scrolling:
- Users can scroll the workspace with the mousewheel while dragging a block
or workspace comment ("wheel scroll").
- The workspace will automatically scroll when a block or workspace comment
is dragged near the edge of the workspace ("edge scroll").
Each of these options can be enabled or disabled independently, if you only want
one of these behaviors. The edge scrolling behavior can also be configured with
options such as fast and slow scroll speeds and the distance from the edge of
the workspace that the block should be before autoscrolling is activated. See
the Usage and API sections for more details on how to configure these behaviors.
```
yarn add @blockly/plugin-scroll-options
``
npm install @blockly/plugin-scroll-options --save
Basic usage. If you don't pass any options to init, then you will get the
default behavior, which enables both scroll options and uses the default
parameters for edge scrolling.
`js
import * as Blockly from 'blockly';
import {
ScrollOptions,
ScrollBlockDragger,
ScrollMetricsManager,
} from '@blockly/plugin-scroll-options';
// Inject Blockly.
const workspace = Blockly.inject('blocklyDiv', {
toolbox: toolboxCategories,
plugins: {
// These are both required.
// Note that the ScrollBlockDragger drags things besides blocks.
// Block is included in the name for backwards compatibility.
blockDragger: ScrollBlockDragger,
metricsManager: ScrollMetricsManager,
},
move: {
wheel: true, // Required for wheel scroll to work.
},
});
// Initialize plugin.
const plugin = new ScrollOptions(workspace);
plugin.init();
`
If you want to disable one (or both) behaviors from the start, you can pass
options to init.
`js`
plugin.init({enableWheelScroll: false, enableEdgeScroll: false});
If you want to supply custom configuration to the edge scrolling behavior, you
can also pass in that option to init.
`js`
plugin.init({edgeScrollOptions: {slowBlockSpeed: 0.1}});
This can be combined with the previous example to disable wheel scroll at the
same time. For more details on the edge scroll options, see the next section.
The plugin is configured during initialization for convenience. It can also be
configured, or reconfigured, at any time afterwards using the following methods
on ScrollOptions:
- enableWheelScroll/disableWheelScrollenableEdgeScroll
- /disableEdgeScrollupdateEdgeScrollOptions
-
IMPORTANT: Currently, the options to configure the edge scroll behavior are
provided statically due to the way a BlockDragger is initialized. Thus, each
instance of the plugin will share the same settings, even if you call
updateEdgeScrollOptions on different instances of the plugin (i.e., on
different workspaces). You can have some workspaces using the plugin and some
not, but any that are using the plugin will share the settings. If this is a
blocking issue for you, please file an issue on blockly-samples.
The edge scroll options are provided in an object with the following properties
(default values in parentheses):
- slowBlockSpeed (0.28), fastBlockSpeed (1.4): Pixels per ms to scrollslowBlockStartDistance
based on how far the block is from the edge of the viewport.
- (0): Distance in workspace units that the edge offastBlockStartDistance
the block is from the edge of the viewport before the corresponding scroll
speed will be used. Can be negative to start scrolling before the block
extends over the edge.
- (50): Same as above, for fast speed. Must be largerslowBlockStartDistance
than .oversizeBlockThreshold
- (0.85): If a block takes up this percentage of theoversizeBlockMargin
viewport or more, it will be considered oversized. Rather than using the
block edge, we use the mouse cursor plus the given margin size to activate
block-based scrolling.
- (15): Cursor margin to use for oversized blocks. AslowMouseSpeed
bigger value will cause the workspace to scroll sooner, i.e., the mouse can
be further inward from the edge when scrolling begins.
- (0.5), fastMouseSpeed (1.6): Pixels per ms to scrollslowMouseStartDistance
based on how far the mouse is from the edge of the viewport.
- (0): Distance in workspace units that the mouse isfastMouseStartDistance
from the edge of the viewport before the corresponding scroll speed will be
used. Can be negative to start scrolling before the mouse extends over the
edge.
- (35): Same as above, for fast speed. Must be largerslowMouseStartDistance
than .
Each of these options is configured with the default value shown, which is
specified in ScrollBlockDragger.js. When you call updateEdgeScrollOptions,options
only the properties actually included in the parameter will be set.undefined
Any unspecified options will use the previously set value (where the initial
value is from the default options). Therefore, do not pass in any options with
explicit or null values. The plugin will break. Just leave them
out of the object if you don't want to change the default value.
This method is safe to call multiple times. Subsequent calls will add onto
previous calls, not completely overwrite them. That is, if you call this with:
`js`
updateEdgeScrollOptions({fastMouseSpeed: 5});
updateEdgeScrollOptions({slowMouseSpeed: 2});
Then the final options used will include both fastMouseSpeed: 5 andslowMouseSpeed: 2 with all other options being the default values.
You can call ScrollBlockDragger.resetOptions() to restore all default options.
This plugin ships with its own MetricsManager implementation. Other pluginsMetricsManager
may ship with their own implementations as well. If you wishMetricsManager
to use multiple of these plugins together, you will need to create your own
implementation of that combines the necessary features ofisCacheable
both. This plugin simply requires that content metrics be cacheable so that
it can see content metrics from before a drag was started, even in the middle
of a drag. Your implementation must satisfy the type guard inScrollMetricsManager.ts.
Blockly supports adding custom objects that implement the Blockly.IDraggableAutoScrollable` interface on your
interface. Custom draggables are compatible with this plugin, but they will
not support the autoscrolling features by default. You can enable autoscrolling
features on them by also implementing the
draggable objects.
Apache 2.0