Preservação de estado e armazenamento permanente

A preservação de estado e o armazenamento permanente são aspectos não triviais dos apps de tinta digital, especialmente no Compose. Os objetos de dados principais, como propriedades de pincel e os pontos que formam um traço, são complexos e não são mantidos automaticamente. Isso exige uma estratégia deliberada para salvar o estado durante cenários como mudanças de configuração e salvar permanentemente os desenhos de um usuário em um banco de dados.

State preservation

In Jetpack Compose, UI state is typically managed using remember and rememberSaveable. While rememberSaveable offers automatic state preservation across configuration changes, its built-in capabilities are limited to primitive data types and objects that implement Parcelable or Serializable.

For custom objects that contain complex properties, such as Brush, you must define explicit serialization and deserialization mechanisms using a custom state saver. By defining a custom Saver for the Brush object, you can preserve the brush's essential attributes when configuration changes occur, as shown in the following brushStateSaver example.

fun brushStateSaver(converters: Converters): Saver<MutableState<Brush>, SerializedBrush> = Saver(
    save = { converters.serializeBrush(it.value) },
    restore = { mutableStateOf(converters.deserializeBrush(it)) },
)

You can then use the custom Saver to preserve the selected brush state:

val currentBrush = rememberSaveable(saver = brushStateSaver(Converters())) { mutableStateOf(defaultBrush) }

Armazenamento permanente

Para ativar recursos como salvar, carregar documentos e possível colaboração em tempo real, armazene traços e dados associados em um formato serializado. Para a API Ink, é necessário fazer a serialização e a desserialização manualmente.

Para restaurar um traço com precisão, salve o Brush e o StrokeInputBatch dele.

• Brush: inclui campos numéricos (tamanho, epsilon), cor e BrushFamily.
• StrokeInputBatch: uma lista de pontos de entrada com campos numéricos.

O módulo Storage simplifica a serialização compacta da parte mais complexa: o StrokeInputBatch.

Observação: consulte objetos de transferência de dados, como SerializedBrush e SerializedStroke, além da classe auxiliar Converters na seção Auxiliares de objetos e conversores de dados.

Para salvar um traço:

• Serialize o StrokeInputBatch usando a função de codificação do módulo de armazenamento. Armazene os dados binários resultantes.
• Salve separadamente as propriedades essenciais do pincel do traço:
  • A enumeração que representa a família de pincéis. Embora a instância possa ser serializada, isso não é eficiente para apps que usam uma seleção limitada de famílias de pincéis.
  • colorLong
  • size
  • epsilon

fun serializeStroke(stroke: Stroke): SerializedStroke {
  val serializedBrush = serializeBrush(stroke.brush)
  val encodedSerializedInputs = ByteArrayOutputStream().use
    {
      stroke.inputs.encode(it)
      it.toByteArray()
    }

  return SerializedStroke(
    inputs = encodedSerializedInputs,
    brush = serializedBrush
  )
}

Para carregar um objeto de traço:

• Recupere os dados binários salvos para o StrokeInputBatch e desserialize-os usando a função decode() do módulo de armazenamento.
• Recupere as propriedades Brush salvas e crie o pincel.

• Crie o traço final usando o pincel recriado e o StrokeInputBatch desserializado.

  fun deserializeStroke(serializedStroke: SerializedStroke): Stroke {
    val inputs = ByteArrayInputStream(serializedStroke.inputs).use {
      StrokeInputBatch.decode(it)
    }
    val brush = deserializeBrush(serializedStroke.brush)
    return Stroke(brush = brush, inputs = inputs)
  }
  

Fazer zoom, movimentar e girar

Se o app tiver suporte a zoom, movimento panorâmico ou rotação, você precisará fornecer a transformação atual para InProgressStrokes. Isso ajuda os traços recém-desenhados a corresponder à posição e à escala dos traços atuais.

Para isso, transmita um Matrix ao parâmetro pointerEventToWorldTransform. A matriz precisa representar o inverso da transformação que você aplica à tela de traços finalizados.

@Composable
fun ZoomableDrawingScreen(...) {
    // 1. Manage your zoom/pan state (e.g., using detectTransformGestures).
    var zoom by remember { mutableStateOf(1f) }
    var pan by remember { mutableStateOf(Offset.Zero) }

    // 2. Create the Matrix.
    val pointerEventToWorldTransform = remember(zoom, pan) {
        android.graphics.Matrix().apply {
            // Apply the inverse of your rendering transforms
            postTranslate(-pan.x, -pan.y)
            postScale(1 / zoom, 1 / zoom)
        }
    }

    Box(modifier = Modifier.fillMaxSize()) {
        // ...Your finished strokes Canvas, with regular transform applied

        // 3. Pass the matrix to InProgressStrokes.
        InProgressStrokes(
            modifier = Modifier.fillMaxSize(),
            pointerEventToWorldTransform = pointerEventToWorldTransform,
            defaultBrush = currentBrush,
            nextBrush = onGetNextBrush,
            onStrokesFinished = onStrokesFinished
        )
    }
}

Observação: para detalhes sobre a implementação dos gestos, consulte a documentação do Jetpack Compose para detectTransformGestures.

Exportar traços

Talvez seja necessário exportar a cena de traço como um arquivo de imagem estática. Isso é útil para compartilhar o desenho com outros aplicativos, gerar miniaturas ou salvar uma versão final e não editável do conteúdo.

Para exportar uma cena, renderize os traços em um bitmap fora da tela em vez de diretamente na tela. Use o Android's Picture API, que permite gravar desenhos em uma tela sem precisar de um componente de interface visível.

O processo envolve criar uma instância Picture, chamar beginRecording() para receber um Canvas e usar o CanvasStrokeRenderer atual para desenhar cada traço nesse Canvas. Depois de gravar todos os comandos de desenho, você pode usar o Picture para criar um Bitmap, que pode ser compactado e salvo em um arquivo.

fun exportDocumentAsImage() {
  val picture = Picture()
  val canvas = picture.beginRecording(bitmapWidth, bitmapHeight)

  // The following is similar logic that you'd use in your custom View.onDraw or Compose Canvas.
  for (item in myDocument) {
    when (item) {
      is Stroke -> {
        canvasStrokeRenderer.draw(canvas, stroke, worldToScreenTransform)
      }
      // Draw your other types of items to the canvas.
    }
  }

  // Create a Bitmap from the Picture and write it to a file.
  val bitmap = Bitmap.createBitmap(picture)
  val outstream = FileOutputStream(filename)
  bitmap.compress(Bitmap.CompressFormat.PNG, 100, outstream)
}

Objetos de dados e conversores auxiliares

Defina uma estrutura de objeto de serialização que espelhe os objetos necessários da API Ink.

Use o módulo de armazenamento da API Ink para codificar e decodificar StrokeInputBatch.

Objetos de transferência de dados

@Parcelize
@Serializable
data class SerializedStroke(
  val inputs: ByteArray,
  val brush: SerializedBrush
) : Parcelable {
  override fun equals(other: Any?): Boolean {
    if (this === other) return true
    if (other !is SerializedStroke) return false
    if (!inputs.contentEquals(other.inputs)) return false
    if (brush != other.brush) return false
    return true
  }

  override fun hashCode(): Int {
    var result = inputs.contentHashCode()
    result = 31 * result + brush.hashCode()
    return result
  }
}

@Parcelize
@Serializable
data class SerializedBrush(
  val size: Float,
  val color: Long,
  val epsilon: Float,
  val stockBrush: SerializedStockBrush,
  val clientBrushFamilyId: String? = null
) : Parcelable

enum class SerializedStockBrush {
  Marker,
  PressurePen,
  Highlighter,
  DashedLine,
}

Converters

object Converters {
  private val stockBrushToEnumValues = mapOf(
    StockBrushes.marker() to SerializedStockBrush.Marker,
    StockBrushes.pressurePen() to SerializedStockBrush.PressurePen,
    StockBrushes.highlighter() to SerializedStockBrush.Highlighter,
    StockBrushes.dashedLine() to SerializedStockBrush.DashedLine,
  )

  private val enumToStockBrush =
    stockBrushToEnumValues.entries.associate { (key, value) -> value to key
  }

  private fun serializeBrush(brush: Brush): SerializedBrush {
    return SerializedBrush(
      size = brush.size,
      color = brush.colorLong,
      epsilon = brush.epsilon,
      stockBrush = stockBrushToEnumValues[brush.family] ?: SerializedStockBrush.Marker,
    )
  }

  fun serializeStroke(stroke: Stroke): SerializedStroke {
    val serializedBrush = serializeBrush(stroke.brush)
    val encodedSerializedInputs = ByteArrayOutputStream().use { outputStream ->
      stroke.inputs.encode(outputStream)
      outputStream.toByteArray()
    }

    return SerializedStroke(
      inputs = encodedSerializedInputs,
      brush = serializedBrush
    )
  }

  private fun deserializeStroke(
    serializedStroke: SerializedStroke,
  ): Stroke? {
    val inputs = ByteArrayInputStream(serializedStroke.inputs).use { inputStream ->
        StrokeInputBatch.decode(inputStream)
    }
    val brush = deserializeBrush(serializedStroke.brush, customBrushes)
    return Stroke(brush = brush, inputs = inputs)
  }

  private fun deserializeBrush(
    serializedBrush: SerializedBrush,
  ): Brush {
    val stockBrushFamily = enumToStockBrush[serializedBrush.stockBrush]
    val brushFamily = customBrush?.brushFamily ?: stockBrushFamily ?: StockBrushes.marker()

    return Brush.createWithColorLong(
      family = brushFamily,
      colorLong = serializedBrush.color,
      size = serializedBrush.size,
      epsilon = serializedBrush.epsilon,
    )
  }
}