WorkspaceHelper

public class WorkspaceHelper extends Object

Provides helper methods for view traversal and coordinate conversions.

There are two primary coordinate systems, workspace coordinates and virtual view coordinates.

Workspace coordinates represent Block model positions in an infinite xy plane with no pre-defined offset.

Virtual view coordinates are workspace coordinates scaled to adjust for device display density (ERROR(/#mDensity)) and expressed relative to an offset that facilitates workspace scrolling. In right-to-left (RTL) mode (ERROR(/#mRtl)), the virtual view coordinates also flip the x coordinates (x *= -1) relative to workspace coordinates.

The conversion from workspace to virtual view coordinates is as follows:

virtualViewX = workspaceX * density * rtl - virtualViewOffsetX

virtualViewY = workspaceY * density - virtualViewOffsetY

where

```
density
```
is display density,

rtl is -1 in RTL mode or +1 in LTR mode,

```
virtualViewOffsetX,Y
```
is the offset of the workspace view expressed in virtual view coordinates.

The virtual view offset is updated during workspace panning as:

virtualViewOffsetNewX,Y = virtualViewOffsetOldX,Y + (1  / viewScale) * dragVectorX,Y

Public Constructor Summary

WorkspaceHelper(Context context)

Create a helper for creating and doing calculations for views in the workspace.

Public Method Summary

BlockViewFactory	getBlockViewFactory()
BlockView	getClosestAncestorBlockView(View descendantView) Finds the closest BlockView that contains the `descendantView` as a child or further descendant.
int	getMaxSnapDistance()
BlockView	getNearestActiveView(BlockView startingView) Gets the first block up the hierarchy that can be dragged by the user.
BlockGroup	getParentBlockGroup(Block block) Find the closest `BlockGroup` in the hierarchy that this `Block` descends from.
BlockGroup	getRootBlockGroup(Block block) Find the highest `BlockGroup` in the hierarchy that this `Block` descends from.
BlockGroup	getRootBlockGroup(BlockView blockView) Find the highest `BlockGroup` in the hierarchy that contains this `BlockView`.
BlockView	getView(Block block) Convenience method for `getView(Block)`.
RectF	getViewableWorkspaceBounds(RectF outRect) Gets the visible bounds of the workspace, in workspace units.
void	getVirtualViewCoordinates(View view, ViewPoint viewPosition) Get virtual view coordinates of a given `View`.
void	getWorkspaceCoordinates(View view, WorkspacePoint outCoordinate) Get workspace coordinates of a given `View`, relative to the nearest WorkspaceView or RecyclerView.
WorkspaceView	getWorkspaceView()
float	getWorkspaceViewScale()
float	getWorkspaceZoomScale()
ZoomBehavior	getZoomBehavior()
static boolean	isBlockDrag(Context viewContext, DragEvent dragEvent) Determine if `dragEvent` is a block drag.
boolean	isInWorkspaceView(BlockView view) Returns true if the view is a child or deeper descendant of the `WorkspaceView` associated with this WorkspaceHelper.
void	screenToVirtualViewCoordinates(int[] screenPositionIn, ViewPoint viewPositionOut) Converts a point in screen coordinates to virtual view coordinates.
void	screenToWorkspaceCoordinates(int[] screenPositionIn, WorkspacePoint workspacePositionOut) Convenience method for direct mapping of screen to workspace coordinates.
void	setPointMaybeFlip(ViewPoint viewPoint, int x, int y) Set a `ViewPoint` and flip x coordinate in RTL mode.
void	setRtlAwareBounds(Rect rect, int parentWidth, int ltrStart, int top, int ltrEnd, int bottom) Assigns `rect` the given bounds, possibly flipping horizontal bounds in RTL mode.
void	setVirtualWorkspaceViewOffset(int x, int y) Set the offset of the virtual workspace view.
void	setWorkspaceView(WorkspaceView workspaceView) Sets the workspace view to use when converting between coordinate systems.
boolean	useRtl()
void	virtualViewToScreenCoordinates(ViewPoint viewPositionIn, Point screenPositionOut) Converts a point in virtual view coordinates to screen coordinates.
void	virtualViewToWorkspaceCoordinates(ViewPoint viewPosition, WorkspacePoint outCoordinate) Converts a point in virtual view coordinates to workspace coordinates, storing the result in the second parameter.
void	virtualViewToWorkspaceDelta(ViewPoint viewPointIn, WorkspacePoint workspacePointOut) Function that converts x and y components of a delta vector from virtual view to workspace coordinates.
int	virtualViewToWorkspaceUnits(float viewValue) Scales a value in virtual view units to workspace units.
void	workspaceToVirtualViewCoordinates(WorkspacePoint workspacePosition, ViewPoint viewPosition) Converts a point in workspace coordinates to virtual view coordinates, storing the result in the second parameter.
void	workspaceToVirtualViewDelta(WorkspacePoint workspacePointIn, ViewPoint viewPointOut) Function that converts x and y components of a delta vector from workspace to virtual view units.
int	workspaceToVirtualViewUnits(float workspaceValue) Scales a value in workspace coordinate units to virtual view pixel units.

Inherited Method Summary

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Public Constructors

public WorkspaceHelper (Context context)

Create a helper for creating and doing calculations for views in the workspace.

Parameters

context	The `Context` of the fragment or activity this lives in.

Public Methods

public BlockViewFactory getBlockViewFactory ()

Returns

The BlockViewFactory for this application.

public BlockView getClosestAncestorBlockView (View descendantView)

Finds the closest BlockView that contains the descendantView as a child or further descendant.

Parameters

descendantView	The contained `view`.

Returns

The closest BlockView that contains the descendantView.

public int getMaxSnapDistance ()

Returns

The maximum distance a block can snap to match a connection, in workspace units.

public BlockView getNearestActiveView (BlockView startingView)

Gets the first block up the hierarchy that can be dragged by the user. If the starting block can be manipulated it will be returned.

Parameters

startingView	The original view that was touched.

Returns

The nearest parent block that the user can manipulate.

public BlockGroup getParentBlockGroup (Block block)

Find the closest BlockGroup in the hierarchy that this Block descends from.

Parameters

block	The block to start searching from.

Returns

The BlockGroup parent of the block's view, otherwise null.

Throws

IllegalStateException	when a BlockView is found without a parent BlockGroup.

public BlockGroup getRootBlockGroup (Block block)

Find the highest BlockGroup in the hierarchy that this Block descends from.

Parameters

block	The block to start searching from.

Returns

The highest BlockGroup found.

public BlockGroup getRootBlockGroup (BlockView blockView)

Find the highest BlockGroup in the hierarchy that contains this BlockView.

Parameters

blockView	The BlockView to start searching from.

Returns

The highest BlockGroup found.

public BlockView getView (Block block)

Convenience method for getView(Block).

Parameters

block	The Block to view.

Returns

The view that was constructed for a given Block object, if any.

public RectF getViewableWorkspaceBounds (RectF outRect)

Gets the visible bounds of the workspace, in workspace units.

Parameters

outRect	The `RectF` in which to store the bounds values.

Returns

outRect

public void getVirtualViewCoordinates (View view, ViewPoint viewPosition)

Get virtual view coordinates of a given View.

This function always returns the coordinate of the top-left corner of the given view, regardless of left-to-right (LTR) vs. right-to-left (RTL) mode. Note that in RTL mode, this is not the corner that corresponds to the block's workspace coordinates. Use getWorkspaceCoordinates(View, WorkspacePoint) to obtain the workspace coordinates of a block from its view, adjusted for RTL mode if necessary.

Parameters

view	The view to find the position of.
viewPosition	The Point to store the results in.

public void getWorkspaceCoordinates (View view, WorkspacePoint outCoordinate)

Get workspace coordinates of a given View, relative to the nearest WorkspaceView or RecyclerView.

This function always returns the coordinate of the corner of the view that corresponds to the block coordinate in workspace coordinates. In left-to-right (LTR) mode, this is the top-left corner of the view, in right-to-left (RTL) mode, it is the top-right corner of the view.

Parameters

view	The view to find the position of.
outCoordinate	The Point to store the results in.

public WorkspaceView getWorkspaceView ()

Returns

The WorkspaceView for which this is a helper.

public float getWorkspaceViewScale ()

public float getWorkspaceZoomScale ()

Returns

The zoom scale of the workspace, where > 1.0 is enlarged ("zoomed in").

public ZoomBehavior getZoomBehavior ()

Returns

The ZoomBehavior for workspaces in this context.

public static boolean isBlockDrag (Context viewContext, DragEvent dragEvent)

Determine if dragEvent is a block drag.

Parameters

viewContext	The context of the view receiving the drag event.
dragEvent	The drag event in question.

Returns

True if the drag represents a block drag. Otherwise false.

public boolean isInWorkspaceView (BlockView view)

Returns true if the view is a child or deeper descendant of the WorkspaceView associated with this WorkspaceHelper.

Parameters

view	The potential child view in question.

Returns

True if touchedView is a descendant.

public void screenToVirtualViewCoordinates (int[] screenPositionIn, ViewPoint viewPositionOut)

Converts a point in screen coordinates to virtual view coordinates.

Parameters

screenPositionIn	Input coordinates of a location in absolute coordinates on the screen.
viewPositionOut	Output coordinates of the same location in `WorkspaceView`, expressed with respect to the virtual view coordinate system.

public void screenToWorkspaceCoordinates (int[] screenPositionIn, WorkspacePoint workspacePositionOut)

Convenience method for direct mapping of screen to workspace coordinates.

This method applies screenToVirtualViewCoordinates(int[], ViewPoint) followed by virtualViewToWorkspaceCoordinates(ViewPoint, WorkspacePoint) using an existing temporary ViewPoint instance as intermediate.

Parameters

screenPositionIn	Input coordinates of a location in absolute coordinates on the screen.
workspacePositionOut	Output coordinates of the same location in workspace coordinates.

public void setPointMaybeFlip (ViewPoint viewPoint, int x, int y)

Set a ViewPoint and flip x coordinate in RTL mode.

Parameters

viewPoint	The point in view coordinates to set.
x	The new x coordinate in LTR mode.
y	The new y coordinate.

public void setRtlAwareBounds (Rect rect, int parentWidth, int ltrStart, int top, int ltrEnd, int bottom)

Assigns rect the given bounds, possibly flipping horizontal bounds in RTL mode.

Parameters

rect
parentWidth
ltrStart	The left coordinate in LTR mode.
top	The top coordinate.
ltrEnd	The right coordinate in LTR mode.
bottom	The bottom coordinate.

public void setVirtualWorkspaceViewOffset (int x, int y)

Set the offset of the virtual workspace view.

This is the coordinate of the top-left corner of the area of the workspace shown by a WorkspaceView inside a VirtualWorkspaceView. The coordinate is represented in virtual workspace view coordinates, i.e., workspace coordinates adjusted for display density and reversed in RTL mode (this implies, that the coordinate provides here refers to the top-left corner of the view area, even in RTL mode).

Parameters

x
y

public void setWorkspaceView (WorkspaceView workspaceView)

Sets the workspace view to use when converting between coordinate systems.

Parameters

workspaceView

public boolean useRtl ()

Returns

True if using Right to Left layout, false otherwise.

public void virtualViewToScreenCoordinates (ViewPoint viewPositionIn, Point screenPositionOut)

Converts a point in virtual view coordinates to screen coordinates.

Parameters

viewPositionIn	Input coordinates of a location in `WorkspaceView`, expressed with respect to the virtual view coordinate system.
screenPositionOut	Output coordinates of the same location in absolute coordinates on the screen.

public void virtualViewToWorkspaceCoordinates (ViewPoint viewPosition, WorkspacePoint outCoordinate)

Converts a point in virtual view coordinates to workspace coordinates, storing the result in the second parameter. The view position should be in the WorkspaceView coordinates in pixels.

Parameters

viewPosition	The position to convert to workspace coordinates.
outCoordinate	The Point to store the results in.

public void virtualViewToWorkspaceDelta (ViewPoint viewPointIn, WorkspacePoint workspacePointOut)

Function that converts x and y components of a delta vector from virtual view to workspace coordinates.

This function respects right-to-left mode by reversing the direction of the x coordinate, but does not apply the workspace offset.

Parameters

viewPointIn
workspacePointOut

public int virtualViewToWorkspaceUnits (float viewValue)

Scales a value in virtual view units to workspace units.

This does not account for offsets into the view's space, nor any scale applied by VirtualWorkspaceView, but only uses screen density to calculate the result.

Parameters

viewValue	The value in virtual view units.

Returns

The value in workspace units.

public void workspaceToVirtualViewCoordinates (WorkspacePoint workspacePosition, ViewPoint viewPosition)

Converts a point in workspace coordinates to virtual view coordinates, storing the result in the second parameter. The resulting coordinates will be in the WorkspaceView's coordinates, relative to the current workspace view offset.

Parameters

workspacePosition	The position to convert to view coordinates.
viewPosition	The Point to store the results in.

public void workspaceToVirtualViewDelta (WorkspacePoint workspacePointIn, ViewPoint viewPointOut)

Function that converts x and y components of a delta vector from workspace to virtual view units.

This function respects right-to-left mode by reversing the direction of the x coordinate, but does not apply the workspace offset.

Parameters

workspacePointIn
viewPointOut

public int workspaceToVirtualViewUnits (float workspaceValue)

Scales a value in workspace coordinate units to virtual view pixel units.

This does not account for offsets into the view's space, nor any scale applied by VirtualWorkspaceView, but only uses screen density to calculate the result.

Parameters

workspaceValue	The value in workspace units.

Returns

The value in virtual view units.