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
BlockView
getClosestAncestorBlockView(View descendantView)
Finds the closest BlockView that contains the descendantView as a child or further descendant.
int
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
float
float
ZoomBehavior
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

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

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

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

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.