Hi everyone, my name is Abby Schmiedt and I'm a software developer on the Blockly team.
In this presentation we're going to be doing a deep dive into our workspace metrics method.
So to get started we're going to go over what I mean by workspace metrics,
and then I'm going to talk about some possible use cases which will hopefully
help you understand when you might need to use or override workspace metrics.
Next I'm going to go into the metrics that we have, what they mean ,and how they have
changed recently. And finally I'm just going to talk about how you can get and override metrics.
So what are workspace metrics? When I talk about workspace metrics I'm primarily talking about
the object that has historically been returned from the getMetrics method on the workspace.
As of the March 2021 release of Blockly, we now have a metrics manager that lives
on the workspace and is in charge of all the metrics. In both cases the metrics are
a set of measurements for different parts of the workspace. Some examples of where
we use metrics internally are for figuring out where to position the scroll bar handle,
where to position the flyout and the toolbox, and for bumping blocks back into the workspace.
Next up I'm going to go through some examples of how we have used or overridden the metrics
method in some plugins we created in Blockly Samples. So the first plugin I'm going to be
talking about is the continuous toolbox plugin. The continuous toolbox is a customized toolbox
where the flyout is always open so one of the problems with having the flyout always open
is that blocks are able to move underneath the flyout. In order to fix this we overrode
the metrics manager. This allows us to return a different location for the start of the workspace.
This resulted in the behavior on the right where the block can no longer go under the flyout.
Next up is workspace search. So, workspace search is a plugin that allows users to pull
up a search bar and search the text of blocks on the workspace. We use metrics in workspace
search to tell when a block is off the screen and to then help us calculate where we should
scroll the workspace so the block we are focusing on is on the screen. In this example we are using
the default metrics instead of overriding metrics like we did in the previous example.
Hopefully that gave you some idea on why the metrics method might be useful to you.
Next we're going to go into all the different sets of metrics.
So, first a little background information: Blockly uses two different coordinate systems.
We use workspace coordinates which are the pixel coordinates divided by the workspace scale,
and pixel coordinates which are of course the workspace coordinate multiplied by the
workspace scale. By default all the metrics are returned in pixel coordinates however certain
sets of metrics can be returned in workspace coordinates. Some other important notes are
that the coordinates increase to the bottom right and the workspace origin moves around as the user
moves the workspace. So the origin is not always in the upper left-hand corner of the workspace.
The first of the metrics we'll be talking about is content metrics. This set of metrics
contains the left, top, width, and height of the rectangle surrounding the top level elements on
the workspace. Top level elements on the workspace are currently the blocks and workspace comments.
The content metrics change every time someone adds a block or workspace comment
the left and top of the rectangle are measured from the workspace origin.
So, the second set of metrics is scroll metrics. This set of metrics contains the left, top,
width, and height of the scrollable area. In a workspace with both scroll bars,
Blockly effectively has an infinite workspace. The way this is achieved is by adding padding
around the content area. In the case of a workspace with single direction scroll enabled,
the workspace expands in the direction that is not fixed.
Next up is view metrics. View metrics contain the left, top, width, and height of the visible
workspace, so this does not include the toolbox. The width and height of the viewport are updated
when the workspace is resized, and the top and left are updated when the user drags the workspace
around. The SVG metrics contain the width and height of the workspace's parent SVG element.
For the main workspace this is the SVG element with the class ‘blocklySvg’.
Unlike the view metrics, this contains the toolbox and the flyout.
The absolute metrics contain the top and left location of where the viewport starts in relation
to the SVG. So depending on where the toolbox is this is usually the width or height of the toolbox.
The toolbox metrics contain the width, height, and position of the toolbox on the workspace.
The position of the toolbox is either top, bottom, left, or right.
If there is no toolbox then the width and height are zero but the position will report the default
value of left if it is vertical layout, and a default value of top if it has a horizontal layout.
Next is the flyout metrics. The flyout metrics are very similar to toolbox metrics. They contain the
width, heigh,t and position of the flyout in the workspace. However these metrics are only reported
for a flyout toolbox and not for a flyout that is attached to a category toolbox. So I believe the
reason behind this is that the category toolbox and the flyout toolbox sit to the left of the
workspace and so information on their size is needed to compute the size of the workspace.
However a flyout that is attached to the category toolbox simply lays on top of the workspace.
So now that we know what the metrics are we are going to get into what has changed
in the most recent release. If you are using content metrics prior to the March 2021 release,
it is important to note that the meaning of content metrics has changed.
In the case of a fixed workspace content metrics used to be the bounding box of the content.
In the case of a movable workspace the content metrics used to be the scrollable area.
For clarity we added a new set of metrics to measure the scrollable area of the workspace
and made content metrics always return the bounding box of the content on the workspace.
Finally we added a metrics manager so that we could have more control over what metrics we get
and also so we could easily override the metrics method which wasn't possible before this release.
And finally we will talk about how you can use these new features.
If you want to get all the metrics for the workspace you can simply
call workspace.getmetrics or you can call workspace.getmetricsmanager.getmetrics both
are the same and return the same object however if you do not need all the metrics we recommend
you use the metrics manager and call the method to get the exact metrics that you need. Some metrics
take longer to calculate and so this ensures that you are not doing any unnecessary calculations.
If you want to override the metrics to do something like change what padding is added to the
scroll metrics you can do so by creating a new class that extends Blockly.MetricsManager
or that implements Blockly.IMetricsManager and then pass it into the plugins object.
I hope that helps to get a better understanding of your workspace metrics and thanks for your time!