androidx.ink.authoring.compose

A ShapeWorkflow to be used as an alternative to the standard Ink behavior provided by InProgressStrokesView.

Specification for the shape being started. If this is null, nothing will be drawn, but the internal rendering resources will be preserved to avoid paying the cost for reinitialization when drawing is needed again. If different ShapeSpecT values are needed for different simultaneous shapes, use nextShapeSpec to return a different ShapeSpecT each time.

A way to override defaultShapeSpec, which will be called at the start of each pointer.

The matrix that transforms androidx.compose.ui.input.pointer.PointerEvent coordinates into the caller's "world" coordinates, which typically is defined by how the caller's document is panned/zoomed/rotated. This defaults to the identity matrix, in which case the world coordinate space is the same as the input event coordinates, but the caller should pass in their own value reflecting a coordinate system that is independent of the device's pixel density (e.g. scaled by 1 / android.util.DisplayMetrics.density) and any pan/zoom/rotate gestures that have been applied to the "camera" which portrays the "world" on the device screen. This matrix must be invertible.

Allows an object-specific (shape-specific) coordinate space to be defined in relation to the caller's "world" coordinate space. This defaults to the identity matrix, which is typical for many use cases at the time of shape construction. In typical use cases, shape coordinates and world coordinates may start to differ from one another only after shape authoring as a finished shape is manipulated within the world, e.g. it may be moved, scaled, or rotated relative to other content within an app's document. This matrix must be invertible.

An area of this composable where no ink will be visible. A value of null indicates that shapes will be visible anywhere they are drawn. This is useful for UI elements that float on top of (in Z order) the drawing surface - without this, a user would be able to draw in-progress ("wet") shapes on top of those UI elements, but then when the shape is finished, it will appear as a dry shape underneath of the UI element. If this mask is set to the shape and position of the floating UI element, then the ink will never be rendered in that area, making it appear as if it's being drawn underneath the UI element. This technique is most convincing when the UI element is opaque. Often there are parts of the UI element that are translucent, such as drop shadows, or anti-aliasing along the edges. The result will look a little different between wet and dry shapes for those cases, but it can be a worthwhile tradeoff compared to the alternative of drawing wet shapes on top of that UI element. Note that this parameter does not affect the contents of the shapes at all, nor how they appear when drawn in a separate composable after onShapesCompleted is called - just how the shapes appear when they are still in progress in this composable.

Called when there are no longer any in-progress shapes for a short period. All shapes that were in progress simultaneously will be delivered in the same callback, running on the UI thread. The callback should pass the shapes to another Composable, triggering its recomposition within the same UI thread run loop as the callback being received, for that other Composable to render the shapes without any brief rendering errors (flickers). These flickers may come from a gap where a shape is drawn in neither this Composable nor the app's Composable during a frame, or a double draw where the shape is drawn twice and translucent shapes appear more opaque than they should. Be careful about passing shapes to asynchronous frameworks during this callback, as they may switch threads during the handoff from producer to consumer, and even if the final consumer is on the UI thread, it may not be in the same UI thread run loop and lead to a flicker.

Brush specification for the stroke being started. If this is null, nothing will be drawn, but the internal rendering resources will be preserved to avoid paying the cost for reinitialization when drawing is needed again. If different Brush values are needed for different simultaneous strokes, use nextBrush to return a different Brush each time. Note that the overall scaling factor of pointerEventToWorldTransform and strokeToWorldTransform combined should be related to the value of Brush.epsilon - in general, the larger the combined pointerEventToStrokeTransform scaling factor is, the smaller on screen the stroke units are, so Brush.epsilon should be a larger quantity of stroke units to maintain a similar screen size.

A way to override defaultBrush, which will be called at the start of each pointer.

The matrix that transforms androidx.compose.ui.input.pointer.PointerEvent coordinates into the caller's "world" coordinates, which typically is defined by how the caller's document is panned/zoomed/rotated. This defaults to the identity matrix, in which case the world coordinate space is the same as the input event coordinates, but the caller should pass in their own value reflecting a coordinate system that is independent of the device's pixel density (e.g. scaled by 1 / android.util.DisplayMetrics.density) and any pan/zoom/rotate gestures that have been applied to the "camera" which portrays the "world" on the device screen. This matrix must be invertible.

Allows an object-specific (stroke-specific) coordinate space to be defined in relation to the caller's "world" coordinate space. This defaults to the identity matrix, which is typical for many use cases at the time of stroke construction. In typical use cases, stroke coordinates and world coordinates may start to differ from one another only after stroke authoring as a finished stroke is manipulated within the world, e.g. it may be moved, scaled, or rotated relative to other content within an app's document. This matrix must be invertible.

An area of this composable where no ink will be visible. A value of null indicates that strokes will be visible anywhere they are drawn. This is useful for UI elements that float on top of (in Z order) the drawing surface - without this, a user would be able to draw in-progress ("wet") strokes on top of those UI elements, but then when the stroke is finished, it will appear as a dry stroke underneath of the UI element. If this mask is set to the shape and position of the floating UI element, then the ink will never be rendered in that area, making it appear as if it's being drawn underneath the UI element. This technique is most convincing when the UI element is opaque. Often there are parts of the UI element that are translucent, such as drop shadows, or anti-aliasing along the edges. The result will look a little different between wet and dry strokes for those cases, but it can be a worthwhile tradeoff compared to the alternative of drawing wet strokes on top of that UI element. Note that this parameter does not affect the contents of the strokes at all, nor how they appear when drawn in a separate composable after onStrokesFinished is called - just how the strokes appear when they are still in progress in this composable.

Allows texture asset images to be loaded, corresponding to texture layers that may be specified by defaultBrush or nextBrush.

Called when there are no longer any in-progress strokes for a short period. All strokes that were in progress simultaneously will be delivered in the same callback, running on the UI thread. The callback should pass the strokes to another Composable, triggering its recomposition within the same UI thread run loop as the callback being received, for that other Composable to render the strokes without any brief rendering errors (flickers). These flickers may come from a gap where a stroke is drawn in neither this Composable nor the app's Composable during a frame, or a double draw where the stroke is drawn twice and translucent strokes appear more opaque than they should. Be careful about passing strokes to asynchronous frameworks during this callback, as they may switch threads during the handoff from producer to consumer, and even if the final consumer is on the UI thread, it may not be in the same UI thread run loop and lead to a flicker.