Skip to content

4. Los componentes

El capítulo anterior presentó los componentes de [Material 3] y el estado. Este capítulo muestra cómo escribir SUS PROPIOS componentes: sus parámetros, cómo notifican a su padre, la composición, su ciclo de vida, los datos que se les proporcionan a distancia y los comportamientos reutilizables. Con [Compose], un componente es una simple función [@Composable]: el equivalente de los widgets de [Flutter].

4.1. Ejemplo 10: componentes y sus parámetros

Una tarjeta que muestra a un médico, usada varias veces en una pantalla. El tipo de datos, compartido por el padre y el hijo:

// el tipo de dato compartido por el padre (DoctorsPage) y el hijo (DoctorCard)
package fr.stahe.examples.ex10

data class Doctor(
    val id: Int,
    val title: String,
    val firstName: String,
    val lastName: String,
    val specialty: String,
    val available: Boolean,
)

El HIJO, la tarjeta:

// =========================================================================
// ex10/DoctorCard.kt - un componente HIJO
// -------------------------------------------------------------------------
// Recibe sus datos de su padre a través de sus PARÁMETROS. Su tipo se
// verifica en tiempo de compilación: DoctorCard(doctor = 42, ...) sería rechazado.
//   - un parámetro sin valor predeterminado: el padre DEBE proporcionarlo;
//   - compact: Boolean = false: un parámetro opcional, con su valor
//     predeterminado;
//   - modifier: Modifier = Modifier: la convención de Compose, el padre
//     puede ajustar el tamaño, los márgenes... del hijo.
//
// Regla de oro: un componente NUNCA MODIFICA sus parámetros (son
// val). Los datos fluyen hacia abajo, del padre al hijo; para solicitar un
// cambio, el hijo llama a una función que el padre le ha pasado
// (cf. ejemplo 11). Cuando el padre cambia sus datos, Compose REEJECUTA
// al hijo con nuevos parámetros.
// =========================================================================
package fr.stahe.examples.ex10

import androidx.compose.foundation.BorderStroke
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp

// el "estilo" de la tarjeta: constantes PRIVADAS de este archivo. Ningún otro
// componente puede verlas, ni verse afectado por ellas
private val initialsColor = Color(0xFF087EA4)

@Composable
fun DoctorCard(doctor: Doctor, rank: Int, modifier: Modifier = Modifier, compact: Boolean = false) {
    // un valor calculado a partir de los parámetros
    val initials = "${doctor.firstName.first()}${doctor.lastName.first()}"
    Card(
        modifier = modifier.padding(vertical = 4.dp),
        shape = RoundedCornerShape(12.dp),
        // un borde verde para un médico disponible (null: sin borde)
        border = if (doctor.available) BorderStroke(2.dp, Color(0xFF4CAF50)) else null,
    ) {
        Row(Modifier.padding(12.dp), verticalAlignment = Alignment.CenterVertically) {
            // un círculo de color, con las iniciales en el centro
            Box(
                contentAlignment = Alignment.Center,
                modifier = Modifier.size(40.dp).background(initialsColor, CircleShape),
            ) {
                Text(initials, color = Color.White, fontWeight = FontWeight.Bold)
            }
            Spacer(Modifier.width(12.dp))
            // weight(1f): el texto ocupa todo el ancho restante
            Column(Modifier.weight(1f)) {
                Text("$rank. ${doctor.title} ${doctor.firstName} ${doctor.lastName}", style = MaterialTheme.typography.titleMedium)
                if (!compact) {
                    Text(doctor.specialty, color = Color.Gray)
                }
            }
        }
    }
}
  • Línea 43: una constante [private]: visible solo en este archivo;
  • línea 46: los parámetros de la tarjeta. Su tipo se verifica en tiempo de compilación; [doctor] y [rank] son obligatorios; [compact] es opcional; [modifier: Modifier = Modifier] es la CONVENCIÓN de [Compose]: el padre puede ajustar el tamaño, los márgenes, etc., del hijo, que aplica este [modifier] a su componente más externo;
  • Línea 48: un valor calculado a partir de los parámetros;
  • líneas 49–53: [Card], una tarjeta de [Material], con un borde verde para un médico disponible ([null]: sin borde);
  • líneas 57–61: un círculo de color ([CircleShape]) con las iniciales;
  • líneas 67–68: la especialidad se muestra solo en modo normal.

La regla de oro: un componente NUNCA MODIFICA sus parámetros (son [val]; de hecho, el compilador lo prohíbe). Los datos fluyen del padre al hijo; cuando el padre cambia sus datos, [Compose] VUELVE A EJECUTAR al hijo con sus nuevos parámetros. El PADRE:

// =========================================================================
// ex10/Ex10Activity.kt - el componente PADRE
// -------------------------------------------------------------------------
// Usa el componente DoctorCard tantas veces como sea necesario, como
// cualquier componente de Compose: una función @Composable es una
// pieza de interfaz REUTILIZABLE, con sus propios parámetros y su
// estilo. Escribir los propios componentes es el corazón del trabajo con
// Compose: una pantalla bien escrita se compone de pequeños componentes.
// =========================================================================
package fr.stahe.examples.ex10

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.width
import androidx.compose.material3.ListItem
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Switch
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.key
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme

class Ex10Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { DoctorsPage() } }
    }
}

@Composable
fun DoctorsPage() {
    var doctors by remember {
        mutableStateOf(
            listOf(
                Doctor(1, "Mme", "Marie", "PELISSIER", "general practitioner", true),
                Doctor(2, "Mr", "Paul", "TATOU", "pediatrician", false),
                Doctor(3, "Melle", "Sophie", "DUPONT", "general practitioner", true),
            ),
        )
    }
    var compact by remember { mutableStateOf(false) }

    ExamplePage("Example 10 - components and their parameters") {
        ListItem(
            headlineContent = { Text("compact display") },
            trailingContent = { Switch(checked = compact, onCheckedChange = { compact = it }) },
        )
        // el padre cambia SUS datos: Compose reejecuta esta función, que
        // vuelve a llamar a los hijos con sus nuevos parámetros
        OutlinedButton(onClick = { doctors = doctors.map { it.copy(available = !it.available) } }) {
            Text("Toggle availabilities")
        }
        Spacer(Modifier.height(8.dp))
        doctors.forEachIndexed { i, d ->
            // cada tarjeta recibe SUS parámetros; key: su identidad (cf. ejemplo 04)
            key(d.id) {
                DoctorCard(doctor = d, rank = i + 1, compact = compact)
            }
        }
        Spacer(Modifier.height(16.dp))
        Text("The same card, in compact version, by setting the parameter:", color = Color.Gray)
        // el padre también fija el ANCHO del hijo, mediante el parámetro modifier
        DoctorCard(doctor = doctors[0], rank = 1, compact = true, modifier = Modifier.width(260.dp))
    }
}
  • línea 63: el padre cambia SUS datos: una lista nueva, en la que cada médico se reemplaza por una copia;
  • líneas 67–70: un registro por médico, cada uno con SUS parámetros; [key(d.id)]: la identidad del médico (véase el ejemplo 04);
  • línea 76: el padre también fija el ANCHO del hijo mediante el parámetro [modifier].

Image

Image

4.2. Ejemplo 11: el hijo notifica a su padre

Los datos se pasan hacia abajo mediante parámetros; la información SUBE mediante funciones que el padre pasa al hijo (por convención, sus nombres comienzan con [on]). Un primer hijo, un contador, que tiene su propio estado y notifica a su padre:

// =========================================================================
// ex11/Counter.kt - un hijo que NOTIFICA a su padre
// -------------------------------------------------------------------------
// El padre le pasa FUNCIONES como parámetros (por convención, su
// nombre empieza con "on"), y el hijo las llama cuando algo
// ocurre:
//     Counter(label = "Coffees", max = 3, onIncrement = { ... }, onLimit = { ... })
// El tipo de una función se escribe (parámetros) -> resultado:
//   - (Int) -> Unit : una función que recibe un Int y no devuelve nada;
//   - () -> Unit    : una función sin parámetros, que no devuelve nada.
// =========================================================================
package fr.stahe.examples.ex11

import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.width
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.SuggestionChip
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

@Composable
fun Counter(label: String, max: Int, onIncrement: (Int) -> Unit, onLimit: () -> Unit) {
    // el estado ESPECÍFICO de este contador: cada Counter tiene el suyo
    var value by remember { mutableIntStateOf(0) }

    fun plus() {
        if (value >= max) {
            onLimit()
            return
        }
        value++
        // NOTIFICAMOS al padre, pasándole el nuevo valor
        onIncrement(value)
    }

    Row(verticalAlignment = Alignment.CenterVertically) {
        Text(label, Modifier.width(110.dp))
        OutlinedButton(onClick = { plus() }) { Text("+1") }
        Spacer(Modifier.width(12.dp))
        SuggestionChip(onClick = {}, label = { Text("$value / $max") })
    }
}
  • línea 30: el tipo de una función se escribe como [(parameters) -> result]: [(Int) -> Unit] recibe un [Int] y no devuelve nada; [() -> Unit] no tiene parámetros;
  • línea 32: el estado PROPIO del contador: cada [Counter] tiene el suyo;
  • líneas 34–41: cuando llega al máximo, el contador notifica al padre ([onLimit()]); en caso contrario, se incrementa y transmite su nuevo valor ([onIncrement(value)]).

Un segundo hijo, un componente CONTROLADO, que se usa como los campos de [Compose]: el valor pertenece al padre, que se lo pasa al hijo ([value]) y a quien el hijo notifica cada pulsación de tecla ([onChange]). El componente no tiene estado:

// =========================================================================
// ex11/TextField.kt - un componente CONTROLADO
// -------------------------------------------------------------------------
// Un campo de formulario "casero" (etiqueta + campo + ayuda + contador de
// caracteres) que se usa como los campos de Compose:
//     TextField(value = firstName, onChange = { firstName = it }, ...)
// El valor pertenece al PADRE, que lo pasa (value) y a quien
// notifica cada pulsación de tecla (onChange). Es el padre quien decide.
// El componente no tiene estado: muestra lo que se le da. Si el
// padre mismo cambia el valor (botón "Clear"), el campo lo sigue, sin
// nada más que escribir.
// =========================================================================
package fr.stahe.examples.ex11

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier

@Composable
fun TextField(value: String, onChange: (String) -> Unit, label: String, max: Int, help: String = "") {
    val full = value.length == max
    OutlinedTextField(
        value = value,
        // el campo rechaza los caracteres sobrantes: la pulsación de tecla solo se pasa
        // al padre si el texto no excede max caracteres
        onValueChange = { text -> if (text.length <= max) onChange(text) },
        label = { Text(label) },
        singleLine = true,
        // el borde se vuelve rojo cuando el campo está lleno
        isError = full,
        supportingText = { Text(if (full) "Maximum length reached - ${value.length}/$max" else "$help - ${value.length}/$max") },
        modifier = Modifier.fillMaxWidth(),
    )
}
  • línea 28: la pulsación de tecla se envía al padre solo si el texto no supera [max] caracteres: el campo “rechaza” los caracteres sobrantes;
  • líneas 32–33: el borde se vuelve rojo cuando el campo está lleno, y el texto de ayuda lo indica.

El padre:

// =========================================================================
// ex11/Ex11Activity.kt - el padre escucha a sus hijos
// -------------------------------------------------------------------------
// Los datos fluyen hacia abajo (parámetros); la información sube mediante
// funciones pasadas como parámetros:
//   1. "eventos" del hijo: onIncrement, onLimit;
//   2. un componente controlado: value + onChange, como un TextField.
//      El estado sigue siendo propiedad del padre, que puede modificarlo él mismo
//      (Clear).
// =========================================================================
package fr.stahe.examples.ex11

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.font.FontStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme

class Ex11Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { ParentPage() } }
    }
}

@Composable
fun ParentPage() {
    var total by remember { mutableIntStateOf(0) }
    var message by remember { mutableStateOf("") }
    var firstName by remember { mutableStateOf("Marie") }
    var lastName by remember { mutableStateOf("PELISSIER") }

    // la función llamada por un contador: recibe el valor que el contador transmite
    fun onIncrement(label: String, value: Int) {
        total++
        message = "$label is now $value"
    }

    val titleStyle = MaterialTheme.typography.titleSmall
    ExamplePage("Example 11 - the child notifies its parent") {
        Card {
            Column(Modifier.padding(12.dp)) {
                Text("1. Functions called by the children", style = titleStyle)
                Counter(
                    label = "Coffees",
                    max = 3,
                    onIncrement = { v -> onIncrement("Coffees", v) },
                    onLimit = { message = "No more than 3 coffees!" },
                )
                Counter(
                    label = "Glasses of water",
                    max = 8,
                    onIncrement = { v -> onIncrement("Glasses of water", v) },
                    onLimit = { message = "Enough drinking." },
                )
                Spacer(Modifier.height(8.dp))
                Text("Total of clicks: $total - $message", fontStyle = FontStyle.Italic)
            }
        }
        Card {
            Column(Modifier.padding(12.dp)) {
                Text("2. Controlled components", style = titleStyle)
                TextField(value = firstName, onChange = { firstName = it }, label = "First name", max = 20, help = "Required")
                TextField(value = lastName, onChange = { lastName = it }, label = "Last name", max = 20, help = "Displayed in upper case")
                Spacer(Modifier.height(8.dp))
                Text(
                    buildAnnotatedString {
                        append("Data of the parent: ")
                        withStyle(SpanStyle(fontWeight = FontWeight.Bold)) { append("$firstName ${lastName.uppercase()}") }
                    },
                )
                Spacer(Modifier.height(8.dp))
                OutlinedButton(onClick = {
                    firstName = ""
                    lastName = ""
                }) { Text("Clear (from the parent)") }
            }
        }
    }
}
  • líneas 57–59: la función a la que llaman los contadores;
  • líneas 68–71: cada contador recibe dos expresiones lambda; la primera recibe el valor pasado ([v]) y le agrega la etiqueta del contador;
  • líneas 86–87: los campos controlados: el valor y qué hacer con cada pulsación de tecla;
  • líneas 97–99: el padre modifica sus propios datos: los campos lo siguen, sin nada más que escribir.

Image

Image

A la izquierda, se alcanzó el número máximo de cafés y el nombre tiene 20 caracteres; a la derecha, después de “Clear (from the parent)”.

4.3. Ejemplo 12: composición

Los parámetros de un componente pasan DATOS... pero también CONTENIDO: un parámetro puede ser una función [@Composable], que el componente llama donde quiera. Esto es lo que [Compose] hace en todas partes ([Card], [Scaffold], el [label] de un campo...). Una primera plantilla, una tarjeta con tres ranuras:

// =========================================================================
// ex12/Card.kt - una PLANTILLA reutilizable
// -------------------------------------------------------------------------
// Los parámetros de un componente pasan DATOS... pero también
// CONTENIDO: un parámetro puede ser una función @Composable, que el
// componente llama donde quiera. Compose usa esto en todas partes: el contenido
// de una Card, la topBar de un Scaffold, la etiqueta de un campo...
//   - content: por convención, el ÚLTIMO parámetro, el contenido
//     "principal". Se escribe después de los paréntesis de la llamada:
//         Card(color = ...) { Text("the content") }
//   - header, footer: otros lugares ("slots"), proporcionados por el
//     padre; el header tiene un contenido predeterminado, el footer es opcional.
// La tarjeta fija el marco (borde, header, footer), el padre proporciona lo que
// va dentro.
// =========================================================================
package fr.stahe.examples.ex12

import androidx.compose.foundation.BorderStroke
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Card
import androidx.compose.material3.ProvideTextStyle
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

@Composable
fun Card(
    color: Color? = null, // "?": opcional (null por defecto)
    header: @Composable () -> Unit = { Text("Untitled") },
    footer: (@Composable () -> Unit)? = null,
    content: @Composable () -> Unit,
) {
    val fill = color ?: Color(0xFFE0E0E0) // "?:": el color, o si no este gris
    Card(
        modifier = Modifier.padding(vertical = 4.dp),
        shape = RoundedCornerShape(8.dp),
        border = BorderStroke(1.dp, fill),
    ) {
        Column {
            Box(Modifier.fillMaxWidth().background(fill).padding(10.dp)) {
                // ProvideTextStyle: el estilo de TODOS los textos del header,
                // sea cual sea el contenido proporcionado por el padre
                ProvideTextStyle(TextStyle(color = if (color == null) Color.Black else Color.White, fontWeight = FontWeight.Bold)) {
                    header()
                }
            }
            Box(Modifier.padding(10.dp)) { content() }
            // sin footer proporcionado: ningún footer en absoluto
            if (footer != null) {
                Box(Modifier.fillMaxWidth().background(Color(0xFFF5F5F5)).padding(8.dp)) {
                    ProvideTextStyle(TextStyle(color = Color.Gray, fontSize = 12.sp)) { footer() }
                }
            }
        }
    }
}
  • líneas 38–41: tres parámetros de contenido: [header], con contenido predeterminado; [footer], OPCIONAL ([(@Composable () -> Unit)?]: una función, o [null]); [content], el último, que se escribe después de los paréntesis en la llamada;
  • líneas 53–54: [ProvideTextStyle] fija el estilo de TODOS los textos del encabezado, sea cual sea el contenido proporcionado por el padre;
  • líneas 59–61: si no se proporciona un pie de página, no hay ningún pie de página.

Una segunda plantilla, una tabla GENÉRICA: puede recorrer las filas, pero no sabe mostrar UNA celda; el padre le indica qué hacer describiendo las columnas:

// =========================================================================
// ex12/DataTable.kt - una tabla GENÉRICA
// -------------------------------------------------------------------------
// DataTable<T> es un componente genérico: muestra filas de
// cualquier tipo T. Sabe recorrer las filas, pero no cómo
// mostrar UNA celda: es el padre quien se lo dice, describiendo sus
// columnas. Cada TableColumn<T> tiene un título, un ancho relativo (weight) y
// una FUNCIÓN @Composable, cell(row, index), que muestra su celda.
// El contenido proporcionado por el padre usa datos que pertenecen al
// hijo (la fila, su posición): es el principio de las listas de Compose
// (LazyColumn y su función items { ... }).
// =========================================================================
package fr.stahe.examples.ex12

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.ProvideTextStyle
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp

// una columna de una tabla de T
class TableColumn<T>(val title: String, val weight: Float = 1f, val cell: @Composable (row: T, index: Int) -> Unit)

@Composable
fun <T> DataTable(
    rows: List<T>,
    columns: List<TableColumn<T>>,
    // se muestra cuando no hay filas
    empty: @Composable () -> Unit = { Text("No data.") },
) {
    Column {
        // la fila de los títulos
        Row {
            for (c in columns) {
                Text(c.title, Modifier.weight(c.weight).padding(6.dp), fontWeight = FontWeight.Bold)
            }
        }
        HorizontalDivider()
        if (rows.isEmpty()) {
            Box(Modifier.padding(6.dp)) { ProvideTextStyle(TextStyle(color = Color.Gray)) { empty() } }
        }
        rows.forEachIndexed { i, row ->
            if (i > 0) HorizontalDivider(color = Color(0xFFE0E0E0))
            Row(verticalAlignment = Alignment.CenterVertically) {
                // las celdas de ESTA fila, mostradas por las funciones del padre
                for (c in columns) {
                    Box(Modifier.weight(c.weight).padding(6.dp)) { c.cell(row, i) }
                }
            }
        }
    }
}
  • línea 31: una columna de una tabla de [T]: un título, un ancho relativo y una función [@Composable] que muestra la celda de una fila;
  • Líneas 55–56: las celdas de cada fila, mostradas por las funciones del padre. El contenido proporcionado por el padre usa datos que pertenecen al hijo (la fila, su índice): este es el principio de las listas de [Compose] ([LazyColumn], véase el caso de estudio).

La pantalla que usa ambas plantillas:

// =========================================================================
// ex12/Ex12Activity.kt - usar las plantillas Card y DataTable
// =========================================================================
package fr.stahe.examples.ex12

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.width
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material3.Icon
import androidx.compose.material3.SuggestionChip
import androidx.compose.material3.SuggestionChipDefaults
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme

// un slot; patient: null si el horario está libre
data class Slot(val id: Int, val timeRange: String, val patient: String?)

val slots = listOf(
    Slot(1, "8:00 - 8:20", null),
    Slot(2, "8:20 - 8:40", "Mme Alice DURAND"),
    Slot(3, "8:40 - 9:00", null),
)

data class Person(val id: Int, val name: String)

class Ex12Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { CompositionPage() } }
    }
}

@Composable
fun CompositionPage() {
    val free = slots.count { it.patient == null }
    ExamplePage("Example 12 - composition") {
        // header y footer: funciones @Composable pasadas como parámetros;
        // el contenido: la lambda escrita DESPUÉS de los paréntesis
        Card(
            color = Color(0xFF3F51B5),
            header = {
                Row(verticalAlignment = Alignment.CenterVertically) {
                    Icon(Icons.Default.DateRange, contentDescription = null, tint = Color.White)
                    Spacer(Modifier.width(8.dp))
                    Text("Schedule of Mme PELISSIER")
                }
            },
            footer = { Text("$free free slot(s)") },
        ) {
            // DataTable<Slot>: T se deduce del tipo de rows
            DataTable(
                rows = slots,
                columns = listOf(
                    // s recibe la fila, i su posición
                    TableColumn("#", 0.4f) { _, i -> Text("${i + 1}") },
                    TableColumn("Slot", 1.2f) { s, _ -> Text(s.timeRange) },
                    TableColumn("Status", 1.6f) { s, _ ->
                        if (s.patient != null) {
                            SuggestionChip(onClick = {}, label = { Text(s.patient) })
                        } else {
                            SuggestionChip(
                                onClick = {},
                                label = { Text("Free") },
                                colors = SuggestionChipDefaults.suggestionChipColors(containerColor = Color(0xFFC8E6C9)),
                            )
                        }
                    },
                ),
            )
        }
        Card(color = Color(0xFF4CAF50), header = { Text("A card without a footer") }) {
            Text("The footer is not provided: the card does not display it.")
        }
        // sin header proporcionado: el contenido predeterminado, "Untitled"
        Card {
            DataTable(
                rows = emptyList<Person>(),
                columns = listOf(TableColumn("Name") { p, _ -> Text(p.name) }),
                empty = { Text("Nobody for now.") },
            )
        }
    }
}
  • líneas 52–61: el encabezado y el pie de página, funciones lambda pasadas por nombre; el contenido, la función lambda escrita DESPUÉS de los paréntesis;
  • líneas 64–70: [DataTable<Slot>]: [T] se DEDUCE, lo que define el tipo de la línea. Cada columna recibe la línea y su índice; [_]: un parámetro no utilizado;
  • Líneas 88–92: una tarjeta sin encabezado (el contenido predeterminado, “Untitled”) y una tabla vacía.

Image

4.4. Ejemplo 13: el ciclo de vida de un componente

Un componente ENTRA en la composición (su función se ejecuta por primera vez), se RECOMPONE tantas veces como sea necesario y luego SALE de la composición, definitivamente. [Compose] ofrece “efectos” que se activan en estos momentos:

  • [LaunchedEffect(key) [ ... ]]: lanza una CORRUTINA (código que puede esperar; véase el Ejemplo 19) al entrar, la vuelve a lanzar si [key] cambia y la CANCELA al salir;
  • [DisposableEffect(key) { ... ; onDispose [ ... ] }]: código al entrar y limpieza al salir.

Un reloj que inicia un temporizador... y debe detenerlo cuando desaparece:

// =========================================================================
// ex13/Clock.kt - un componente que se inicia y se detiene
// -------------------------------------------------------------------------
// La vida de un componente en la pantalla ("la composición"):
//   1. ENTRA en la composición: su función se ejecuta por
//      primera vez. Lo que debe iniciarse se inicia ahí;
//   2. se RECOMPONE tantas veces como sea necesario (su estado o sus
//      parámetros han cambiado);
//   3. SALE de la composición: desaparece de la pantalla, para siempre.
//      Lo que se inició se DETIENE ahí.
// Compose ofrece "efectos" para actuar en esos momentos, fuera de
// la visualización propiamente dicha:
//   - LaunchedEffect(key) { ... }: lanza una CORRUTINA (código que puede
//     esperar, cf. ejemplo 19) al entrar en la composición, la relanza
//     si key cambia, la CANCELA al salir;
//   - DisposableEffect(key) { ...; onDispose { ... } }: código al
//     entrar, y su limpieza (onDispose) al salir.
// Un reloj inicia un temporizador cuando aparece... y debe
// detenerlo sin falta cuando desaparece: con LaunchedEffect,
// es automático.
// =========================================================================
package fr.stahe.examples.ex13

import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberUpdatedState
import androidx.compose.runtime.setValue
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.unit.sp
import kotlinx.coroutines.delay
import java.time.LocalTime
import java.time.format.DateTimeFormatter

fun currentTime(): String = LocalTime.now().format(DateTimeFormatter.ofPattern("HH:mm:ss"))

@Composable
fun Clock(onLog: (String) -> Unit, color: Color = Color(0xFF3F51B5)) {
    var time by remember { mutableStateOf(currentTime()) }
    // la ÚLTIMA función onLog recibida (los efectos de abajo duran
    // más que una ejecución de la función)
    val log by rememberUpdatedState(onLog)

    // entrar en la composición y salir de ella
    DisposableEffect(Unit) {
        log("Clock: entering the composition - timer started")
        onDispose { log("Clock: leaving the composition - timer stopped") }
    }

    // el temporizador: una corrutina, CANCELADA automáticamente al salir
    LaunchedEffect(Unit) {
        while (true) {
            delay(1000) // esperar un segundo, sin bloquear el teléfono
            time = currentTime()
        }
    }

    // un parámetro que cambia: el efecto se relanza (excepto la primera vez)
    var firstColor by remember { mutableStateOf(true) }
    LaunchedEffect(color) {
        if (firstColor) firstColor = false else log("Clock: recomposed with a new color")
    }

    Text(time, fontSize = 40.sp, fontFamily = FontFamily.Monospace, color = color)
}
  • línea 47: [rememberUpdatedState]: los efectos duran más que una sola llamada de función; deben llamar a la ÚLTIMA función recibida ([onLog]), no a la primera;
  • líneas 50–52: entrada en la composición y salida ([onDispose]);
  • líneas 57–59: el temporizador, un bucle infinito... en una corrutina: [delay(1000)] espera un segundo SIN bloquear el teléfono; la corrutina se cancela al salir de la composición, y el bucle con ella;
  • línea 65: un efecto cuya clave es un parámetro: se activa de nuevo cuando cambia el color.

La pantalla:

// =========================================================================
// ex13/Ex13Activity.kt - el ciclo de vida
// -------------------------------------------------------------------------
//   - if (withClock) Clock(...): marcar / desmarcar la casilla hace que
//     el reloj entre en / salga de la composición (cf. Clock.kt);
//     cambiar su color lo recompone;
//   - un campo que toma el foco en cuanto aparece (se abre el teclado
//     del teléfono);
//   - el título de la aplicación sigue a la entrada (TaskTitle);
//   - la vida de la ACTIVIDAD misma (su "Lifecycle"): en un teléfono,
//     pasa a segundo plano (se abre otra aplicación, la pantalla
//     se apaga), luego vuelve: podemos reaccionar a ello (guardar, detener
//     un temporizador...).
// =========================================================================
package fr.stahe.examples.ex13

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.selection.toggleable
import androidx.compose.material3.Card
import androidx.compose.material3.Checkbox
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import androidx.lifecycle.LifecycleEventObserver
import androidx.lifecycle.compose.LocalLifecycleOwner
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import fr.stahe.examples.common.TaskTitle

class Ex13Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { LifecyclePage() } }
    }
}

@Composable
fun LifecyclePage() {
    var withClock by remember { mutableStateOf(true) }
    var red by remember { mutableStateOf(false) }
    val log = remember { mutableStateListOf<String>() }
    var search by remember { mutableStateOf("") }
    var showSearch by remember { mutableStateOf(false) }

    fun trace(message: String) {
        log.add("${currentTime()} $message")
    }

    // la vida de la actividad: nos SUSCRIBIMOS a sus cambios de estado al entrar
    // en la composición, nos DESUSCRIBIMOS al salir (onDispose)
    val lifecycle = LocalLifecycleOwner.current.lifecycle
    DisposableEffect(lifecycle) {
        val observer = LifecycleEventObserver { _, event -> trace("Activity: ${event.name}") }
        lifecycle.addObserver(observer)
        onDispose { lifecycle.removeObserver(observer) }
    }

    TaskTitle(if (search.isEmpty()) "Example 13" else "Search: $search")

    ExamplePage("Example 13 - the lifecycle") {
        Card {
            Column(Modifier.padding(12.dp)) {
                CheckboxRow("show the clock", withClock) { withClock = it }
                CheckboxRow("in red", red) { red = it }
                if (withClock) {
                    Clock(onLog = { trace(it) }, color = if (red) Color.Red else Color(0xFF3F51B5))
                }
            }
        }
        Card {
            Column(Modifier.padding(12.dp)) {
                if (!showSearch) {
                    OutlinedButton(onClick = { showSearch = true }) { Text("Search...") }
                } else {
                    // un campo que toma el foco en cuanto aparece
                    val focus = remember { FocusRequester() }
                    OutlinedTextField(
                        value = search,
                        onValueChange = { search = it },
                        placeholder = { Text("the title follows the input") },
                        modifier = Modifier.fillMaxWidth().focusRequester(focus),
                    )
                    LaunchedEffect(Unit) { focus.requestFocus() }
                }
            }
        }
        Text("Log", style = MaterialTheme.typography.titleSmall)
        log.forEachIndexed { i, line -> Text("${i + 1}. $line", fontSize = 12.sp) }
    }
}

// una casilla y su etiqueta; toda la línea reacciona a la pulsación.
// onChange es el ÚLTIMO parámetro: se puede escribir después de los paréntesis
@Composable
fun CheckboxRow(label: String, checked: Boolean, onChange: (Boolean) -> Unit) {
    ListItem(
        modifier = Modifier.toggleable(value = checked, onValueChange = onChange),
        leadingContent = { Checkbox(checked = checked, onCheckedChange = null) },
        headlineContent = { Text(label) },
    )
}
  • líneas 74–78: el ciclo de vida de la propia ACTIVIDAD: en un teléfono, pasa a segundo plano (otra aplicación, se apaga la pantalla) y luego regresa. Nos suscribimos a sus cambios ([addObserver]) al entrar en la composición y cancelamos la suscripción al salir;
  • líneas 4–89: [if (withClock) Clock(...)]: al desmarcar la casilla, el reloj SALE de la composición; al marcarla de nuevo, se crea uno NUEVO;
  • líneas 99–106: un campo que obtiene el foco apenas aparece: [LaunchedEffect] se ejecuta DESPUÉS de la visualización, cuando el campo ya existe.

Image

El registro muestra la secuencia: la actividad se crea, se inicia y se reanuda ([ON_CREATE], [ON_START], [ON_RESUME]); el reloj se agrega al diseño; cambia su color; luego se desmarca y se vuelve a marcar.

4.5. Ejemplo 14: los datos proporcionados

¿Cómo se pueden compartir datos entre componentes distantes sin pasarlos de parámetro en parámetro por todos los intermediarios? Con un [CompositionLocal], un dato “local a la composición”: se DECLARA una vez; un componente lo pasa a todos sus descendientes ([CompositionLocalProvider]); cualquier descendiente lo LEE. [Compose] lo usa él mismo: [MaterialTheme.colorScheme], [LocalContext.current], [LocalDensity.current]... Es el equivalente de [InheritedWidget] y del paquete [provider] de [Flutter].

Un registro, mostrado a pantalla completa:

// =========================================================================
// ex14/providers/Log.kt - un dato para TODA la aplicación
// -------------------------------------------------------------------------
// ¿Cómo compartir datos y funciones entre componentes distantes,
// sin pasarlos de parámetro en parámetro a través de todos los
// intermediarios? Con un CompositionLocal, un dato "local a la
// composición":
//   1. se DECLARA una vez: val LocalLog = staticCompositionLocalOf<Log> { ... };
//   2. un componente situado en lo alto del árbol lo PROPORCIONA a todos sus
//      descendientes: CompositionLocalProvider(LocalLog provides log) { ... };
//   3. cualquier descendiente, a cualquier profundidad, lo LEE:
//      LocalLog.current.
// Es el mecanismo que usa el propio Compose: MaterialTheme.colorScheme,
// LocalContext.current, LocalDensity.current... son lecturas de
// CompositionLocal.
//
// El log en sí es un objeto ordinario, cuyo estado (sus líneas) es
// OBSERVADO por Compose (mutableStateListOf): un componente que lee sus
// líneas se recompone cuando estas cambian.
// =========================================================================
package fr.stahe.examples.ex14.providers

import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.staticCompositionLocalOf
import java.time.LocalTime
import java.time.format.DateTimeFormatter

class Log {
    // la lista observada; hacia afuera, solo se ve como una List NO MODIFICABLE
    private val _lines = mutableStateListOf<String>()
    val lines: List<String> get() = _lines

    fun trace(message: String) {
        _lines.add(0, "${LocalTime.now().format(DateTimeFormatter.ofPattern("HH:mm:ss"))} $message")
        if (_lines.size > 6) _lines.removeAt(_lines.lastIndex)
    }
}

// la declaración: el tipo del dato, y lo que ocurre si nadie
// lo proporciona (aquí, un error explícito).
// static: el log proporcionado nunca cambia (lo que cambia es su CONTENIDO)
val LocalLog = staticCompositionLocalOf<Log> { error("LocalLog: no log provided above this component") }
  • líneas 30–31: el estado del registro, una lista observada, que se expone hacia el exterior solo como una [List] NO modificable;
  • línea 8: la declaración: el tipo de dato y qué ocurre si nadie lo proporciona (un error explícito). [static]: el dato proporcionado nunca cambia (lo que cambia es su CONTENIDO).

Un carrito de compras, proporcionado a una parte de la pantalla por un componente proveedor, que lo crea:

// =========================================================================
// ex14/providers/Cart.kt - un dato proporcionado por UN componente
// -------------------------------------------------------------------------
// El carrito solo se proporciona a una parte del árbol: los componentes
// que CartProvider envuelve (cf. Ex14Activity.kt). Dos providers
// colocados en dos lugares de la pantalla darían dos carritos independientes.
// Es el provider quien CREA el carrito (remember); él
// mismo usa el log.
// =========================================================================
package fr.stahe.examples.ex14.providers

import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.staticCompositionLocalOf

data class Item(val label: String, val price: Double)

class Cart(private val log: Log) {
    private val _items = mutableStateListOf<Item>()
    val items: List<Item> get() = _items

    // un valor calculado: sumOf suma un valor de cada artículo
    val total: Double get() = _items.sumOf { it.price }

    fun add(item: Item) {
        _items.add(item)
        log.trace("cart: + ${item.label}")
    }

    fun remove(index: Int) {
        log.trace("cart: - ${_items[index].label}")
        _items.removeAt(index)
    }
}

val LocalCart = staticCompositionLocalOf<Cart> { error("LocalCart: no cart provided above this component") }

// el provider: crea el carrito UNA SOLA VEZ y lo proporciona a su contenido
@Composable
fun CartProvider(content: @Composable () -> Unit) {
    val log = LocalLog.current
    val cart = remember { Cart(log) }
    CompositionLocalProvider(LocalCart provides cart, content = content)
}
  • línea 25: [total], una propiedad calculada; [sumOf] suma el valor de cada artículo;
  • líneas 42–45: el proveedor crea el carrito de compras UNA SOLA VEZ ([remember]) y lo llena con su contenido; él mismo lee el registro, proporcionado más arriba.

Un reloj, proporcionado con un período configurable:

// =========================================================================
// ex14/providers/Clock.kt - un provider PARAMETRIZADO
// -------------------------------------------------------------------------
// Un reloj, cuyo período de actualización es un parámetro del
// provider: ClockProvider(periodMs = 5000) { ... }.
// Dos providers anidados: un componente lee el que está MÁS
// CERCA por encima de él.
// Esta vez, el dato proporcionado CAMBIA (la hora, en cada tic):
// compositionLocalOf (y no staticCompositionLocalOf). Compose entonces solo
// recompone los componentes que LEEN la hora.
// El reloj se detiene cuando su provider desaparece (LaunchedEffect).
// =========================================================================
package fr.stahe.examples.ex14.providers

import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.compositionLocalOf
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import kotlinx.coroutines.delay
import java.time.LocalDateTime

// el valor predeterminado: una fecha congelada, leída por un componente sin provider
val LocalClock = compositionLocalOf { LocalDateTime.of(2026, 1, 1, 0, 0) }

@Composable
fun ClockProvider(periodMs: Long = 1000, content: @Composable () -> Unit) {
    var now by remember { mutableStateOf(LocalDateTime.now()) }
    // si el período cambia, la corrutina se cancela y se relanza
    LaunchedEffect(periodMs) {
        while (true) {
            delay(periodMs)
            now = LocalDateTime.now()
        }
    }
    CompositionLocalProvider(LocalClock provides now, content = content)
}
  • línea 27: esta vez, el dato proporcionado CAMBIA (la hora, en cada tic): [compositionLocalOf], no [staticCompositionLocalOf]. [Compose] reconstruye entonces solo los componentes que LEEN la hora;
  • líneas 33–36: si el período cambia, la corrutina se cancela y se reinicia.

Dos descendientes que usan el carrito:

// ex14/Catalog.kt - un descendiente que AGREGA al carrito
package fr.stahe.examples.ex14

import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.ShoppingCart
import androidx.compose.material3.Card
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import fr.stahe.examples.ex14.providers.Item
import fr.stahe.examples.ex14.providers.LocalCart

val catalog = listOf(Item("Consultation", 30.0), Item("Vaccine", 12.5), Item("Certificate", 5.0))

@Composable
fun Catalog() {
    // el carrito proporcionado por ShopPage (un error si nadie lo proporciona)
    val cart = LocalCart.current
    Card {
        Column {
            for (item in catalog) {
                ListItem(
                    headlineContent = { Text("${item.label} (€${item.price})") },
                    trailingContent = {
                        IconButton(onClick = { cart.add(item) }) {
                            Icon(Icons.Default.ShoppingCart, contentDescription = "add ${item.label}")
                        }
                    },
                )
            }
        }
    }
}
// =========================================================================
// ex14/CartSummary.kt
// -------------------------------------------------------------------------
// Otro descendiente: el MISMO carrito que Catalog, pero SU PROPIO
// reloj, actualizado cada 5 segundos. Un componente solo lee los
// providers colocados POR ENCIMA de él: CartSummary coloca entonces un segundo
// ClockProvider alrededor de su contenido, que entrega a un pequeño
// componente, Content, que lee el reloj MÁS CERCANO: el de 5 s.
// =========================================================================
package fr.stahe.examples.ex14

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import fr.stahe.examples.ex14.providers.ClockProvider
import fr.stahe.examples.ex14.providers.LocalClock
import fr.stahe.examples.ex14.providers.LocalCart

@Composable
fun CartSummary() {
    ClockProvider(periodMs = 5000) { Content() }
}

@Composable
private fun Content() {
    val cart = LocalCart.current
    val now = LocalClock.current // el más cercano: el de 5 s
    Card {
        Column(Modifier.padding(12.dp)) {
            Text(
                "Cart (${cart.items.size} item(s)) - ${now.toLocalTime().withNano(0)}",
                style = MaterialTheme.typography.titleSmall,
            )
            cart.items.forEachIndexed { i, item ->
                Row(verticalAlignment = Alignment.CenterVertically) {
                    Text(item.label)
                    TextButton(onClick = { cart.remove(i) }) { Text("remove") }
                }
            }
            Text("Total: €${cart.total}", fontWeight = FontWeight.Bold)
        }
    }
}
  • líneas 29–30: [CartSummary] coloca un SEGUNDO proveedor de reloj (5 segundos) alrededor de su contenido: un componente lee el proveedor de reloj MÁS CERCANO por encima de él.

La pantalla:

// =========================================================================
// ex14/Ex14Activity.kt - tres niveles de datos proporcionados
// -------------------------------------------------------------------------
//   - el log: proporcionado en lo más alto, por la actividad, a toda la pantalla;
//   - el carrito, proporcionado por ShopPage: compartido por Catalog y
//     CartSummary, que ven el MISMO carrito;
//   - el reloj, proporcionado por ShopPage (período predeterminado, 1 s) Y por
//     CartSummary (5 s): cada uno el suyo.
// =========================================================================
package fr.stahe.examples.ex14

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import fr.stahe.examples.ex14.providers.ClockProvider
import fr.stahe.examples.ex14.providers.CartProvider
import fr.stahe.examples.ex14.providers.Log
import fr.stahe.examples.ex14.providers.LocalClock
import fr.stahe.examples.ex14.providers.LocalLog

class Ex14Activity : ComponentActivity() {
    // el log: un objeto creado con la actividad
    private val log = Log()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            // el log, proporcionado a TODA la pantalla
            CompositionLocalProvider(LocalLog provides log) {
                ExamplesTheme { ShopPage() }
            }
        }
    }
}

// la hora del reloj de la página: un pequeño componente, colocado DEBAJO del provider
@Composable
private fun PageTime() {
    Text("Clock of the page: ${LocalClock.current.toLocalTime().withNano(0)}", color = Color.Gray)
}

@Composable
fun ShopPage() {
    // la página lee el log: se recompondrá con cada nueva línea
    val log = LocalLog.current
    ClockProvider {
        CartProvider {
            ExamplePage("Example 14 - provided data") {
                PageTime()
                Catalog()
                CartSummary()
                Spacer(Modifier.height(12.dp))
                Text("Log (provided to the whole screen)", style = MaterialTheme.typography.titleSmall)
                for (line in log.lines) {
                    Text(line, fontSize = 12.sp)
                }
            }
        }
    }
}
  • líneas 43–44: el registro, un objeto de la actividad, mostrado en la pantalla;
  • líneas 60–65: el reloj (1 s) y el carrito de compras, proporcionados a la página; [Catalog] y [CartSummary] ven el MISMO carrito de compras.

Image

4.6. Ejemplo 15: reutilizar comportamientos

Reutilizar una VISUALIZACIÓN implica escribir un componente. Para reutilizar un COMPORTAMIENTO (y su estado), [Compose] ofrece dos herramientas: un componente “envoltorio” o una función [remember...]. Un envoltorio que resalta su contenido cuando se lo toca:

// =========================================================================
// ex15/Highlighter.kt - un comportamiento en un componente "envoltorio"
// -------------------------------------------------------------------------
// La primera forma de reutilizar un COMPORTAMIENTO (con su estado): un
// componente que envuelve cualquier contenido y le agrega este
// comportamiento:
//     Highlighter(color = ...) { ListItem(...) }
// Este resalta su contenido mientras se lo TOCA (el dedo sobre
// la pantalla) y, con un mouse (tableta, ChromeOS), mientras se pasa el
// cursor por encima. Cada Highlighter tiene su propio estado: dos líneas no interfieren.
// =========================================================================
package fr.stahe.examples.ex15

import androidx.compose.animation.animateColorAsState
import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.gestures.awaitEachGesture
import androidx.compose.foundation.gestures.awaitFirstDown
import androidx.compose.foundation.gestures.waitForUpOrCancellation
import androidx.compose.foundation.hoverable
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.interaction.collectIsHoveredAsState
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.pointer.pointerInput

@Composable
fun Highlighter(color: Color = Color(0xFFFFF3CD), content: @Composable () -> Unit) {
    var touched by remember { mutableStateOf(false) }
    // pasar el cursor con un mouse: una "interaction source", cuyo
    // estado "hovered" es observado
    val interactions = remember { MutableInteractionSource() }
    val hovered by interactions.collectIsHoveredAsState()
    // un cambio de color ANIMADO (200 ms)
    val fill by animateColorAsState(if (touched || hovered) color else Color.Transparent, tween(200), label = "fill")
    Box(
        Modifier
            .background(fill)
            .hoverable(interactions)
            // los contactos del dedo, al nivel más bajo: el dedo toca la pantalla,
            // luego se levanta (o se cancela el gesto). requireUnconsumed = false:
            // incluso si el contenido (un botón) ya ha manejado la pulsación
            .pointerInput(Unit) {
                awaitEachGesture {
                    awaitFirstDown(requireUnconsumed = false)
                    touched = true
                    waitForUpOrCancellation()
                    touched = false
                }
            },
    ) {
        content()
    }
}
  • líneas 38–39: el cursor del mouse sobre el elemento (tableta, [ChromeOS]): una “fuente de interacción”, cuyo estado “hovered” se observa;
  • línea 41: [animateColorAsState]: un cambio de color ANIMADO;
  • líneas 49–54: toques del dedo en el nivel más bajo: para cada gesto ([awaitEachGesture]), se espera a que el dedo toque la pantalla y luego a que se levante. [requireUnconsumed = false]: incluso si el contenido (un botón) ya procesó la pulsación.

Un componente con una animación: un botón que debe mantenerse presionado durante un segundo mientras se llena un anillo:

// =========================================================================
// ex15/LongPressButton.kt - un botón de pulsación larga
// -------------------------------------------------------------------------
//     LongPressButton(durationMs = 1000, onAction = { remove() }) { Text(...) }
// La acción solo se ejecuta si el botón se mantiene presionado durante
// toda la duración: una protección contra pulsaciones accidentales. Un anillo
// se llena durante la pulsación.
// El llenado es una ANIMACIÓN: un Animatable es un valor (de 0 a 1)
// que una corrutina hace variar, fotograma tras fotograma (animateTo). Cancelar la
// corrutina (el dedo se levanta demasiado pronto) detiene la animación.
// =========================================================================
package fr.stahe.examples.ex15

import androidx.compose.animation.core.Animatable
import androidx.compose.animation.core.LinearEasing
import androidx.compose.animation.core.tween
import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.rememberUpdatedState
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.unit.dp
import kotlinx.coroutines.launch

@Composable
fun LongPressButton(durationMs: Int = 1000, onAction: () -> Unit, content: @Composable () -> Unit) {
    val progress = remember { Animatable(0f) }
    // el scope de las corrutinas del componente: se cancelan si este desaparece
    val scope = rememberCoroutineScope()
    val action by rememberUpdatedState(onAction)

    Row(
        verticalAlignment = Alignment.CenterVertically,
        modifier = Modifier.pointerInput(Unit) {
            detectTapGestures(
                // onPress: el dedo toca la pantalla; tryAwaitRelease ESPERA a que se levante
                onPress = {
                    val filling = scope.launch {
                        progress.animateTo(1f, tween(durationMs, easing = LinearEasing))
                        // la animación ha llegado hasta el final: la pulsación duró lo suficiente
                        progress.snapTo(0f)
                        action()
                    }
                    tryAwaitRelease()
                    // el dedo se levanta demasiado pronto: el llenado se detiene, el anillo se vacía
                    if (filling.isActive) {
                        filling.cancel()
                        scope.launch { progress.animateTo(0f, tween(200)) }
                    }
                },
            )
        },
    ) {
        CircularProgressIndicator(
            progress = { progress.value },
            modifier = Modifier.size(22.dp),
            color = Color.Red,
            strokeWidth = 3.dp,
            trackColor = Color(0xFFFFEBEE),
        )
        Spacer(Modifier.width(8.dp))
        content()
    }
}
  • líneas 37–39: un [Animatable], un valor (de 0 a 1) que una corrutina incrementa fotograma a fotograma; [rememberCoroutineScope]: un ámbito para lanzar corrutinas desde un evento;
  • líneas 47–58: se apoya el dedo: se lanza el llenado ([animateTo(1f)], en [durationMs]); si llega al final, se ejecuta la acción. [tryAwaitRelease()] ESPERA a que se levante el dedo: si el llenado aún está en curso, se cancela y el anillo se vacía.

Una función [remember...], que DEVUELVE un objeto después de configurar su estado y sus efectos (esta es la convención de [Compose]: [rememberScrollState()], [rememberCoroutineScope()]...), es la siguiente:

// =========================================================================
// ex15/FocusOnStart.kt - un comportamiento en una función "remember..."
// -------------------------------------------------------------------------
// La segunda forma de reutilizar un comportamiento: una
// función @Composable que DEVUELVE un objeto, después de haber configurado su estado y
// sus efectos. Es la convención de Compose (rememberScrollState(),
// rememberCoroutineScope()...): su nombre empieza con "remember".
//     val focus = rememberFocusOnStart()
//     OutlinedTextField(..., modifier = Modifier.focusRequester(focus))
// El campo que usa este FocusRequester recibe el foco en cuanto se
// muestra la pantalla.
// =========================================================================
package fr.stahe.examples.ex15

import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember
import androidx.compose.ui.focus.FocusRequester

@Composable
fun rememberFocusOnStart(): FocusRequester {
    val focus = remember { FocusRequester() }
    // después de la primera visualización: el campo existe, se le da el foco
    LaunchedEffect(Unit) { focus.requestFocus() }
    return focus
}

La pantalla:

// =========================================================================
// ex15/Ex15Activity.kt - reutilizar comportamientos
// -------------------------------------------------------------------------
// Tres herramientas de Compose para reutilizar un COMPORTAMIENTO (y su estado),
// y no una mera visualización:
//   - un componente "envoltorio" (Highlighter);
//   - un componente que lleva una animación (LongPressButton);
//   - una función "remember..." (rememberFocusOnStart).
// =========================================================================
package fr.stahe.examples.ex15

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.material3.ListItem
import androidx.compose.material3.ListItemDefaults
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.key
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme

class Ex15Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { BehavioursPage() } }
    }
}

@Composable
fun BehavioursPage() {
    val doctors = remember { mutableStateListOf("Mme Marie PELISSIER", "Mr Paul TATOU", "Melle Sophie DUPONT") }
    var message by remember { mutableStateOf("") }
    // el FocusRequester preparado por rememberFocusOnStart
    val focus = rememberFocusOnStart()
    var input by remember { mutableStateOf("") }

    ExamplePage("Example 15 - reusing behaviours") {
        OutlinedTextField(
            value = input,
            onValueChange = { input = it },
            placeholder = { Text("this field received the focus on its own") },
            modifier = Modifier.fillMaxWidth().focusRequester(focus),
        )
        Spacer(Modifier.height(12.dp))
        Text("Touch the lines; hold a button down for one second to delete.", color = Color.Gray)
        doctors.forEachIndexed { i, d ->
            key(d) {
                // una línea de cada dos: el color predeterminado; las otras, verdes
                Highlighter(color = if (i % 2 == 0) Color(0xFFFFF3CD) else Color(0xFFD1E7DD)) {
                    ListItem(
                        // un fondo transparente: se transparenta el del Highlighter
                        colors = ListItemDefaults.colors(containerColor = Color.Transparent),
                        headlineContent = { Text(d) },
                        trailingContent = {
                            LongPressButton(onAction = {
                                doctors.remove(d)
                                message = "$d has been deleted."
                            }) {
                                Text("Delete", color = Color.Red)
                            }
                        },
                    )
                }
            }
        }
        Spacer(Modifier.height(12.dp))
        if (message.isNotEmpty()) {
            Text(message, color = Color(0xFF3F51B5))
        }
    }
}

Image

Image

A la izquierda, el dedo descansa sobre la primera línea: está resaltada; a la derecha, el botón “Delete” se mantuvo presionado durante un segundo.

4.7. Ejemplo 16: una ventana de confirmación reutilizable

Con [Compose], una ventana ([AlertDialog]) es un componente como cualquier otro: se muestra mientras un estado lo solicite. Para hacer una pregunta y obtener la respuesta, escribimos una pequeña clase cuya función [confirm] es una función SUSPEND (véase el Ejemplo 19):

// =========================================================================
// ex16/Confirmation.kt - "Are you sure?"
// -------------------------------------------------------------------------
// Con Compose, un diálogo (AlertDialog) es un componente como cualquier otro:
// se muestra mientras un estado lo pida. Para hacer una pregunta
// y ESPERAR la respuesta, escribimos una pequeña clase, Confirmation, cuya
// función confirm es una función SUSPEND (suspend, cf. ejemplo
// 19): abre el diálogo y luego espera, sin bloquear el teléfono, a que
// el usuario responda. El código que la llama se escribe entonces de forma muy simple,
// en una corrutina:
//
//     if (confirmation.confirm("Delete this doctor?")) { ... }
//
// Cerrar el diálogo SIN responder (pulsar fuera, el botón Atrás del
// teléfono) se trata como un "no".
// El diálogo en sí lo muestra ConfirmDialog(confirmation),
// colocado una sola vez en la pantalla.
// =========================================================================
package fr.stahe.examples.ex16

import androidx.compose.material3.AlertDialog
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.graphics.Color
import kotlinx.coroutines.CompletableDeferred

class Confirmation {
    // la pregunta formulada (null: sin diálogo)
    var question by mutableStateOf<String?>(null)
        private set

    // la respuesta esperada: un valor que llegará MÁS TARDE
    private var answer: CompletableDeferred<Boolean>? = null

    suspend fun confirm(message: String): Boolean {
        val waiting = CompletableDeferred<Boolean>()
        answer = waiting
        question = message // se muestra el diálogo
        try {
            return waiting.await() // la corrutina queda suspendida hasta la respuesta
        } finally {
            question = null // el diálogo desaparece
        }
    }

    fun respond(yes: Boolean) {
        answer?.complete(yes)
    }
}

// remember: la Confirmation sobrevive a las recomposiciones de la pantalla
@Composable
fun rememberConfirmation(): Confirmation = remember { Confirmation() }

@Composable
fun ConfirmDialog(confirmation: Confirmation) {
    // ?: return: sin pregunta, nada que mostrar
    val question = confirmation.question ?: return
    // AlertDialog: un diálogo Material, con título, contenido y botones
    AlertDialog(
        onDismissRequest = { confirmation.respond(false) }, // cerrado sin respuesta: "no"
        title = { Text("Confirmation") },
        text = { Text(question) },
        dismissButton = { TextButton(onClick = { confirmation.respond(false) }) { Text("No, go back") } },
        confirmButton = {
            Button(
                onClick = { confirmation.respond(true) },
                colors = ButtonDefaults.buttonColors(containerColor = Color(0xFFD32F2F)),
            ) { Text("Yes, confirm") }
        },
    )
}
  • líneas 36–37: la pregunta formulada ([null]: sin ventana), un estado observado;
  • líneas 42–49: [CompletableDeferred]: un valor que llegará MÁS TARDE. [confirm] muestra la ventana y luego ESPERA la respuesta ([await()]), sin congelar el teléfono; [finally]: en cualquier caso, la ventana desaparece;
  • líneas 53–54: un botón de la ventana PROPORCIONA la respuesta: la corrutina en espera se reanuda;
  • líneas 63–68: la ventana: nada si no hay pregunta ([?: return]); cerrarla sin responder (tocando fuera de la ventana o presionando el botón Atrás del teléfono) se trata como “no”.

La pantalla: una lista de contactos y, después de cada eliminación, un mensaje emergente ([Snackbar]) con un botón “Undo”: otro método, muy común en los dispositivos móviles, para proteger al usuario de un error:

// =========================================================================
// ex16/Ex16Activity.kt - usar el diálogo de confirmación
// -------------------------------------------------------------------------
// Una eliminación, luego un mensaje efímero en la parte inferior de la pantalla (Snackbar),
// con un botón "Undo": la otra forma, muy común en móviles, de
// proteger al usuario de un error.
// Las dos esperas (la respuesta a la pregunta, el botón "Undo" del
// mensaje) se hacen en una CORRUTINA, lanzada por rememberCoroutineScope.
// =========================================================================
package fr.stahe.examples.ex16

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Person
import androidx.compose.material.icons.outlined.Delete
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.SnackbarDuration
import androidx.compose.material3.SnackbarHostState
import androidx.compose.material3.SnackbarResult
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.coroutines.launch

data class Contact(val id: Int, val name: String)

class Ex16Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { ContactsPage() } }
    }
}

@Composable
fun ContactsPage() {
    val contacts = remember { mutableStateListOf(Contact(1, "Jean MARTIN"), Contact(2, "Alice DURAND"), Contact(3, "Luc GERMAN")) }
    var message by remember { mutableStateOf("") }
    val confirmation = rememberConfirmation()
    // el área de los mensajes efímeros y un scope para lanzar corrutinas
    val messages = remember { SnackbarHostState() }
    val scope = rememberCoroutineScope()

    // una función suspend: "espera" la respuesta del usuario
    suspend fun remove(c: Contact) {
        if (!confirmation.confirm("Delete the contact ${c.name}?")) {
            message = "Deletion abandoned."
            return
        }
        val position = contacts.indexOf(c)
        contacts.remove(c)
        message = "${c.name} has been deleted."
        // un mensaje efímero en la parte inferior de la pantalla; showSnackbar espera a que
        // desaparezca e indica si se ha tocado su botón
        val result = messages.showSnackbar("${c.name} deleted", actionLabel = "Undo", duration = SnackbarDuration.Short)
        if (result == SnackbarResult.ActionPerformed) {
            contacts.add(position, c)
            message = "${c.name} is back."
        }
    }

    suspend fun removeAll() {
        if (confirmation.confirm("Delete the ${contacts.size} contacts?")) {
            contacts.clear()
            message = "All the contacts have been deleted."
        }
    }

    ExamplePage("Example 16 - a confirmation dialog", messages = messages) {
        for (c in contacts) {
            ListItem(
                leadingContent = { Icon(Icons.Default.Person, contentDescription = null) },
                headlineContent = { Text(c.name) },
                trailingContent = {
                    // launch: una corrutina, para poder llamar a la función suspend
                    IconButton(onClick = { scope.launch { remove(c) } }) {
                        Icon(Icons.Outlined.Delete, contentDescription = "delete ${c.name}", tint = Color.Red)
                    }
                },
            )
        }
        if (contacts.isEmpty()) {
            ListItem(headlineContent = { Text("No contact.", color = Color.Gray) })
        }
        Spacer(Modifier.height(12.dp))
        Button(
            onClick = { scope.launch { removeAll() } },
            // el botón está deshabilitado cuando la lista está vacía
            enabled = contacts.isNotEmpty(),
            colors = ButtonDefaults.buttonColors(containerColor = Color(0xFFD32F2F)),
        ) { Text("Delete all") }
        Spacer(Modifier.height(12.dp))
        if (message.isNotEmpty()) {
            Text(message, color = Color(0xFF3F51B5))
        }
    }
    // el diálogo, cuando se formula una pregunta
    ConfirmDialog(confirmation)
}
  • líneas 60–61: el área para mensajes emergentes, pasada a [ExamplePage] (que la pasa a [Scaffold]), y un ámbito de corrutinas;
  • líneas 64–77: una función suspendida que se lee como código ordinario: hacer una solicitud, esperar la respuesta; eliminar; mostrar el mensaje, ESPERAR a que desaparezca ([showSnackbar] indica si se tocó su botón) y cancelar si es necesario;
  • línea 95: [scope.launch [ ... ]]: una corrutina, para poder llamar a una función suspendida desde un evento;
  • línea 117: la ventana, colocada una sola vez en la pantalla.

Image

Image