Skip to content

3. Primeiros passos com Kotlin e Jetpack Compose

3.1. Exemplo 01: a estrutura de um aplicativo Android

3.1.1. O projeto

O projeto de exemplo foi criado pelo [Android Studio] (template [Empty Activity], veja o capítulo anterior) e depois completado. Um projeto [Android] é um projeto [Gradle]: a ferramenta que baixa as bibliotecas, compila o código [Kotlin] e gera o arquivo [.apk] instalado no celular. Ele é descrito por alguns arquivos escritos em [Kotlin] (os arquivos [.kts], “Kotlin script”).

3.1.2. O arquivo settings.gradle.kts

// =========================================================================
// settings.gradle.kts - a configuração GLOBAL do projeto Gradle
// (gerado pelo Android Studio; apenas rootProject.name foi alterado)
// =========================================================================

// onde o Gradle procura seus PLUGINS (o plugin Android, o plugin Compose...)
pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
}
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}
// onde o Gradle procura as BIBLIOTECAS: google() para AndroidX e Compose,
// mavenCentral() para OkHttp, kotlinx.serialization, AndroidSVG
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "examples_kotlin"
// um único módulo: o aplicativo, na pasta app/
include(":app")
  • linhas 7–17: onde o [Gradle] procura seus PLUGINS (extensões do [Gradle]: o plugin [Android], o compilador [Compose]...): o repositório do Google e o repositório central de bibliotecas Java ([Maven Central]);
  • linhas 25–29: onde o [Gradle] procura as BIBLIOTECAS do aplicativo;
  • linhas 3–11: o nome do projeto e seu único módulo, o aplicativo, na pasta [app/].

3.1.3. O catálogo de versões: gradle/libs.versions.toml

Todas as versões de plugins e bibliotecas são reunidas em um único arquivo no formato TOML:

# =========================================================================
# gradle/libs.versions.toml - o "version catalog" do projeto
# -------------------------------------------------------------------------
# TODAS as versões dos plugins e das bibliotecas, em um único lugar.
# Os arquivos build.gradle.kts se referem a elas por nome
# (libs.okhttp, libs.plugins.kotlin.compose...). É o equivalente da seção
# dependencies do pubspec.yaml do Flutter.
# =========================================================================

[versions]
agp = "9.4.1"
kotlin = "2.2.10"
coreKtx = "1.17.0"
lifecycle = "2.9.4"
activityCompose = "1.11.0"
composeBom = "2026.02.01"
appcompat = "1.7.1"
navigation = "2.9.5"
datastore = "1.1.7"
okhttp = "4.12.0"
kotlinxSerializationJson = "1.9.0"
androidsvg = "1.4"
junit = "4.13.2"
junitVersion = "1.3.0"
espressoCore = "3.7.0"
testRunner = "1.7.0"

[libraries]
# — gerado pelo Android Studio (template "Empty Activity") —
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycle" }
androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
androidx-compose-ui = { group = "androidx.compose.ui", name = "ui" }
androidx-compose-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
androidx-compose-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
androidx-compose-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
androidx-compose-ui-test-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4" }
androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
junit = { group = "junit", name = "junit", version.ref = "junit" }
androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }
androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }
androidx-test-runner = { group = "androidx.test", name = "runner", version.ref = "testRunner" }
# — adicionado para os exemplos —
# os ícones básicos do Material (Add, Delete, Search...)
androidx-compose-material-icons-core = { group = "androidx.compose.material", name = "material-icons-core" }
# o ciclo de vida da activity visto pelo Compose (exemplos 13, 20)
androidx-lifecycle-runtime-compose = { group = "androidx.lifecycle", name = "lifecycle-runtime-compose", version.ref = "lifecycle" }
# viewModel() em uma função @Composable (exemplos 20, 24, 25)
androidx-lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }
# o idioma PRÓPRIO do aplicativo (exemplos 21, 25)
androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
# o roteador (exemplos 17, 18)
androidx-navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigation" }
# um pequeno dicionário chave -> valor, mantido no dispositivo (exemplo 20)
androidx-datastore-preferences = { group = "androidx.datastore", name = "datastore-preferences", version.ref = "datastore" }
# o cliente HTTP (exemplos 22 a 25)
okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
# (de)serialização JSON (exemplos 17, 18, 22 a 25)
kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "kotlinxSerializationJson" }
# desenho de uma imagem SVG (exemplo 03, captcha dos exemplos 22 a 25)
androidsvg = { group = "com.caverock", name = "androidsvg-aar", version.ref = "androidsvg" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
# gera o código de (de)serialização das classes @Serializable
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
  • seção [[versions]]: os números de versão, nomeados;
  • seção [[libraries]]: as bibliotecas, identificadas por seu grupo e nome ([Maven]) e sua versão. As bibliotecas do [Compose] não têm versão: é o “BOM” ([compose-bom], “Bill of Materials”) que define versões compatíveis para todas elas de uma só vez;
  • seção [[plugins]]: os plugins do [Gradle]. Os arquivos [build.gradle.kts] os referenciam pelo nome: [libs.okhttp], [libs.plugins.kotlin.compose] (os hifens são substituídos por pontos).

A finalidade de cada biblioteca é explicada nos comentários; cada uma será demonstrada no exemplo que a utiliza.

3.1.4. O arquivo app/build.gradle.kts

A configuração do próprio aplicativo:

// =========================================================================
// app/build.gradle.kts - a configuração do módulo "app": o aplicativo
// dos 25 exemplos. Gerado pelo Android Studio (template "Empty Activity"),
// depois completado (linhas marcadas "added").
// =========================================================================
plugins {
    // o plugin Android: compila o código Kotlin (o próprio plugin do Android 9
    // já inclui o suporte a Kotlin) e produz o arquivo .apk
    alias(libs.plugins.android.application)
    // o compilador do Compose: transforma as funções @Composable
    alias(libs.plugins.kotlin.compose)
    // added: o plugin kotlinx.serialization (classes @Serializable)
    alias(libs.plugins.kotlin.serialization)
}

android {
    // o "package" base do código (classe R, BuildConfig...)
    namespace = "fr.stahe.examples"
    // a versão da API do Android usada para COMPILAR
    compileSdk {
        version = release(37)
    }

    defaultConfig {
        // o identificador ÚNICO do aplicativo no celular
        applicationId = "fr.stahe.examples"
        // a versão mais antiga do Android aceita: Android 8.0 (API 26)
        minSdk = 26
        // a versão do Android para a qual o aplicativo foi testado
        targetSdk = 37
        versionCode = 1
        versionName = "1.0"
        // added: o endereço do servidor JSON (exemplos 22 a 25), pode ser alterado na
        // compilação: gradlew installDebug -Pserver=http://192.168.1.20:8080
        val server = providers.gradleProperty("server").getOrElse("http://localhost:8080")
        buildConfigField("String", "SERVER_URL", "\"$server\"")

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            optimization {
                enable = false
            }
        }
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    buildFeatures {
        compose = true
        // added: a classe BuildConfig (BuildConfig.SERVER_URL)
        buildConfig = true
    }
}

dependencies {
    // o "BOM" do Compose: versões mutuamente compatíveis de todas as
    // bibliotecas do Compose, declaradas abaixo SEM número de versão
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.activity.compose)
    implementation(libs.androidx.compose.material3)
    implementation(libs.androidx.compose.ui)
    implementation(libs.androidx.compose.ui.graphics)
    implementation(libs.androidx.compose.ui.tooling.preview)
    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.lifecycle.runtime.ktx)
    // added: para os exemplos
    implementation(libs.androidx.compose.material.icons.core)
    implementation(libs.androidx.lifecycle.runtime.compose)
    implementation(libs.androidx.lifecycle.viewmodel.compose)
    implementation(libs.androidx.appcompat)
    implementation(libs.androidx.navigation.compose)
    implementation(libs.androidx.datastore.preferences)
    implementation(libs.okhttp)
    implementation(libs.kotlinx.serialization.json)
    implementation(libs.androidsvg)
    // os testes: aqui, a geração das capturas de tela do curso (pasta androidTest)
    testImplementation(libs.junit)
    androidTestImplementation(platform(libs.androidx.compose.bom))
    androidTestImplementation(libs.androidx.compose.ui.test.junit4)
    androidTestImplementation(libs.androidx.espresso.core)
    androidTestImplementation(libs.androidx.junit)
    androidTestImplementation(libs.androidx.test.runner)
    debugImplementation(libs.androidx.compose.ui.test.manifest)
    debugImplementation(libs.androidx.compose.ui.tooling)
}
  • linhas 6–13: os plugins aplicados ao módulo: o plugin [Android] (que também compila o [Kotlin]), o compilador [Compose] (que transforma as funções [@Composable]) e o plugin [kotlinx.serialization] (que escreve o código de conversão JSON das classes [@Serializable]; veja o Exemplo 05);
  • linhas 18–21: [namespace], o pacote base do código (o da classe de recursos [R]); [compileSdk], a versão da API e do [Android] usada na compilação;
  • linhas 24–32: [applicationId], o identificador único do aplicativo no celular; [minSdk = 26]: o aplicativo é instalado no [Android] 8.0 e posteriores; [targetSdk], a versão para a qual foi testado;
  • linhas 33–36: um campo da classe [BuildConfig], gerado em tempo de compilação: o endereço do servidor JSON (exemplos 22 a 25), que pode ser alterado na compilação ([-Pserver=...]);
  • linhas 52–55: [compose = true] ativa o [Compose]; [buildConfig = true], a classe [BuildConfig];
  • Linhas 59–88: as bibliotecas do aplicativo ([implementation]), dos testes instrumentados ([androidTestImplementation]) e da versão apenas de depuração ([debugImplementation]).

3.1.5. O arquivo AndroidManifest.xml

O manifesto é o “documento de identidade” do aplicativo para o sistema [Android]: suas permissões, sua classe [Application], suas ACTIVITIES, as telas que o [Android] pode iniciar:

<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     AndroidManifest.xml - a "carteira de identidade" do aplicativo
     ............................................................................
     Suas permissões, sua classe Application, suas activities (uma por
     exemplo, mais o menu).
     ===================================================================== -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- acesso à rede (exemplos 22 a 25): concedido automaticamente, sem
         perguntar ao usuário -->
    <uses-permission android:name="android.permission.INTERNET" />

    <!-- android:name: a classe Application (ExamplesApplication.kt).
         android:usesCleartextTraffic="true": permite HTTP "em texto claro"
         (http:// e não https://), bloqueado por padrão desde o Android 9: o
         servidor JSON deste curso escuta em HTTP simples.
         android:localeConfig: os idiomas do aplicativo (exemplo 21) -->
    <application
        android:name=".ExamplesApplication"
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:localeConfig="@xml/locales_config"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.Examples"
        android:usesCleartextTraffic="true"
        tools:targetApi="33">

        <!-- o menu: a activity iniciada pelo ícone do aplicativo
             (o filtro MAIN / LAUNCHER) -->
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <!-- os exemplos. exported="false": somente o aplicativo pode
             abri-los (o adb, no entanto, sempre pode).
             windowSoftInputMode="adjustResize": o teclado reduz a tela
             em vez de escondê-la -->
        <activity android:name=".ex01.Ex01Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex02.Ex02Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex03.Ex03Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex04.Ex04Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex05.Ex05Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex06.Ex06Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex07.Ex07Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex08.Ex08Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex09.Ex09Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex10.Ex10Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex11.Ex11Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex12.Ex12Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex13.Ex13Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex14.Ex14Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex15.Ex15Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex16.Ex16Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex19.Ex19Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex20.Ex20Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex21.Ex21Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex22.Ex22Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex23.Ex23Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex24.Ex24Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex25.Ex25Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />

        <!-- exemplos 17 e 18: endereços app://examples/... e
             app://examples18/... ("deep links"), que outro
             aplicativo (ou o adb) pode abrir: um intent filter VIEW -->
        <activity android:name=".ex17.Ex17Activity" android:exported="true" android:windowSoftInputMode="adjustResize">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:scheme="app" android:host="examples" />
            </intent-filter>
        </activity>
        <activity android:name=".ex18.Ex18Activity" android:exported="true" android:windowSoftInputMode="adjustResize">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:scheme="app" android:host="examples18" />
            </intent-filter>
        </activity>

        <!-- exemplo 21: antes do Android 13, é o AppCompat que armazena o
             idioma escolhido pelo aplicativo (autoStoreLocales) -->
        <service
            android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
            android:enabled="false"
            android:exported="false">
            <meta-data
                android:name="autoStoreLocales"
                android:value="true" />
        </service>
    </application>

</manifest>
  • linha 13: permissão para acessar a rede (exemplos 22 a 25);
  • linhas 20–32: o aplicativo: sua classe [Application] (exemplo 23), seu ícone, seu nome ([@string/app_name], um recurso, veja o exemplo 21), seu tema e o tráfego HTTP em “texto simples” (o servidor deste curso não usa HTTPS);
  • linhas 37–43: o menu, a activity de inicialização: o intent filter [MAIN] / [LAUNCHER] representa, de fato, a activity iniciada pelo ícone do aplicativo;
  • linhas 49–71: uma activity de exemplo; [exported="false"]: apenas o aplicativo pode abri-las.

3.1.6. A activity: Ex01Activity.kt

Código do Exemplo 01:

// =========================================================================
// ex01/Ex01Activity.kt - um primeiro aplicativo
// -------------------------------------------------------------------------
// Uma tela de um aplicativo Android é uma ACTIVITY: uma classe que
// herda de ComponentActivity, que o sistema cria quando o
// aplicativo é iniciado. Com o Jetpack Compose, a activity quase não faz nada:
// ela entrega sua tela a funções @Composable (setContent).
// Uma função @Composable DESCREVE um pedaço da tela (um texto, um
// botão, uma coluna...) chamando outras funções @Composable:
// elas formam uma ÁRVORE. O Compose executa essas funções para construir
// a tela; ele as EXECUTA DE NOVO quando um dado que elas leem (um "estado")
// muda: isso é a RECOMPOSIÇÃO. Nós nunca modificamos a tela diretamente.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex01

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.Button
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplesTheme
import java.time.LocalTime
import java.time.format.DateTimeFormatter

// dados "comuns", fora das funções @Composable: nunca mudam
const val TITLE = "Welcome to Kotlin"
val languages = listOf("Kotlin", "Jetpack Compose", "Material Design")

// "12:05:09": a hora atual
fun currentTime(): String = LocalTime.now().format(DateTimeFormatter.ofPattern("HH:mm:ss"))

// a activity: o ponto de entrada da tela (declarada em AndroidManifest.xml)
class Ex01Activity : ComponentActivity() {
    // onCreate: chamado pelo Android quando a activity é criada
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // o aplicativo também desenha sob a barra de status e a barra de navegação
        enableEdgeToEdge()
        // setContent: o Compose assume a tela e exibe nela a função
        // @Composable informada, envolvida pelo tema dos exemplos
        setContent {
            ExamplesTheme {
                HomePage()
            }
        }
    }
}

// uma função @Composable: seu nome começa com letra maiúscula, como
// uma classe (é um pedaço de interface), e ela não retorna nada (Unit)
@Composable
fun HomePage() {
    // o ESTADO: variáveis observadas pelo Compose. Modificá-las provoca
    // a reexecução (recomposição) das funções que as leem.
    // rememberSaveable: o valor é mantido de uma execução da função
    // para a seguinte... e até quando o Android recria a activity (rotação
    // da tela, mudança de idioma)
    var counter by rememberSaveable { mutableIntStateOf(0) }
    var time by rememberSaveable { mutableStateOf(currentTime()) }

    // Scaffold: a estrutura de uma tela Material (barra superior, conteúdo...)
    Scaffold(
        topBar = { TopAppBar(title = { Text("Example 01 - a first application") }) },
    ) { insets ->
        // Column: filhos dispostos um abaixo do outro; os insets
        // do Scaffold (o espaço da barra superior), mais 16 dp
        Column(modifier = Modifier.padding(insets).padding(16.dp)) {
            Text(TITLE, style = MaterialTheme.typography.headlineSmall)
            Spacer(Modifier.height(12.dp))
            Text(
                "This screen is built by Jetpack Compose, from the activity " +
                    "Ex01Activity and the function HomePage.",
            )
            Spacer(Modifier.height(8.dp))
            // ${expression} insere o valor de uma expressão em uma string
            Text("It is written in ${languages.joinToString(", ")} (${languages.size} technologies).")
            Spacer(Modifier.height(16.dp))
            // onClick: a função (aqui uma "lambda") chamada ao pressionar.
            // Modificamos o ESTADO; o Compose atualiza a tela
            Button(onClick = {
                counter++
                time = currentTime()
            }) {
                Text("Click me")
            }
            Spacer(Modifier.height(16.dp))
            Text(
                "You clicked $counter times (last click: $time).",
                fontWeight = FontWeight.Bold,
                color = Color(0xFF087EA4),
            )
        }
    }
}
  • linha 16: o pacote ([package]) do arquivo: cada exemplo tem o seu, o que permite que nomes idênticos (uma função [HomePage]) apareçam em dois exemplos;
  • linha 14: [@file:OptIn(...)]: algumas funções do [Material 3] ([TopAppBar]) ainda são marcadas como “experimentais”; declaramos que as usamos com pleno conhecimento dos riscos;
  • linhas 47–48: dados comuns, fora de qualquer função [@Composable]; [const val]: uma constante conhecida em tempo de compilação;
  • linha 54: a ACTIVITY, uma classe que herda de [ComponentActivity]. O [Android] a cria quando a tela é iniciada e depois chama sua função [onCreate];
  • linhas 59–64: [enableEdgeToEdge()]: o aplicativo também desenha sob a barra de status e sob a barra de navegação do celular (essa é a regra desde o [Android] 15); [setContent [ ... ]]: o [Compose] assume o controle da tela e exibe nela o conteúdo do bloco. [ExamplesTheme] (arquivo [common/Theme.kt]) aplica as cores do [Material 3] a tudo o que ele contém;
  • linhas 7–73: uma função [@Composable]: ela DESCREVE uma parte da tela chamando outras funções [@Composable]. Por convenção, seu nome começa com letra maiúscula, como uma classe; ela não retorna nada;
  • linhas 79–80: o ESTADO. [mutableIntStateOf(0)] cria um valor OBSERVADO pelo [Compose]: quando ele muda, o [Compose] reexecuta as funções que o leem (recomposição). [by] liga a variável [counter] a esse estado: [counter++] se escreve como para uma variável comum. [rememberSaveable]: o valor é preservado de uma execução da função para a seguinte (sem [remember], cada execução redefiniria o estado para 0)... e até quando o [Android] RECRIA a activity, o que ele faz toda vez que a tela gira;
  • linhas 83–85: [Scaffold], a estrutura de uma tela [Material]: uma barra superior ([topBar]) e o conteúdo. O conteúdo é uma lambda que recebe as MARGENS a respeitar (a posição da barra superior);
  • linha 88: [Column] coloca seus filhos um abaixo do outro. [Modifier]: o método do [Compose] para ajustar um componente (margens, tamanho, fundo, resposta a gestos etc.): os modificadores são encadeados na ordem em que são aplicados;
  • linhas 89–97: texto e espaçamento ([Spacer]); [MaterialTheme.typography.headlineSmall]: um dos estilos de texto do tema; ["$[...]"] insere uma expressão em uma string;
  • linhas 101–105: um botão. [onClick] recebe a função (uma lambda) a ser executada quando o botão é pressionado: ela altera o estado, e pronto. Nunca interagimos diretamente com a tela: o [Compose] reexecuta [HomePage], que exibe o novo contador; a última lambda, entre chaves após os parênteses, é o CONTEÚDO do botão (seu texto);
  • linhas 109–111: texto que lê o estado; ele será atualizado a cada clique.

O tema dos exemplos, [common/Theme.kt]:

// =========================================================================
// common/Theme.kt - o tema compartilhado por todos os exemplos
// -------------------------------------------------------------------------
// MaterialTheme: as cores, textos e formas do Material
// Design 3, que TODOS os componentes Material colocados dentro dele usam
// (botões, campos, cards...). Damos a ele um conjunto de cores (um
// ColorScheme), claro ou escuro, construído em torno de um azul índigo.
// ExamplesTheme(dark = true): o tema escuro (cf. exemplo 20).
// =========================================================================
package fr.stahe.examples.common

import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.material3.lightColorScheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.graphics.Color

// as cores do tema claro: as demais são os padrões do Material 3
private val lightColors = lightColorScheme(
    primary = Color(0xFF4355B9),
    onPrimary = Color.White,
    primaryContainer = Color(0xFFDEE0FF),
    onPrimaryContainer = Color(0xFF00105C),
    secondaryContainer = Color(0xFFE0E1F9),
    onSecondaryContainer = Color(0xFF181A2C),
    surface = Color(0xFFFBF8FF),
    surfaceContainer = Color(0xFFEFEDF4),
    surfaceContainerLow = Color(0xFFF5F2FA),
)

// as cores do tema escuro
private val darkColors = darkColorScheme(
    primary = Color(0xFFBAC3FF),
    onPrimary = Color(0xFF08218A),
    primaryContainer = Color(0xFF293CA0),
    onPrimaryContainer = Color(0xFFDEE0FF),
    secondaryContainer = Color(0xFF434659),
    onSecondaryContainer = Color(0xFFE0E1F9),
)

// uma função @Composable que "envolve" um conteúdo: o parâmetro
// content é, ele próprio, uma função @Composable (cf. exemplo 12)
@Composable
fun ExamplesTheme(dark: Boolean = false, content: @Composable () -> Unit) {
    MaterialTheme(
        colorScheme = if (dark) darkColors else lightColors,
        content = content,
    )
}
  • [lightColorScheme(...)], [darkColorScheme(...)]: as cores do [Material 3], claras e escuras; as cores não especificadas mantêm seus valores padrão;
  • [ExamplesTheme(dark, content)]: uma função [@Composable] que recebe... outra função [@Composable], seu conteúdo. Esse é o mecanismo central da composição (veja o Exemplo 12): [ExamplesTheme [ HomePage() ]] chama [MaterialTheme] com esse conteúdo.

3.1.7. Execução

No [Android Studio], o botão [Run] inicia o aplicativo: o menu de exemplos aparece; a primeira linha abre o Exemplo 01. Após dois cliques no botão:

Image

Image

Gire o celular (ou o emulador, pelo botão de rotação de sua barra de ferramentas): a activity é destruída e depois recriada pelo [Android], e mesmo assim o contador permanece o mesmo, graças ao [rememberSaveable]. Substitua [rememberSaveable] por [remember]: o contador volta a 0 a cada rotação. Esta é uma diferença fundamental em relação ao [Flutter], em que a tela persiste durante a rotação: com o [Android], quando as configurações do dispositivo (orientação, idioma, tamanho do texto etc.) mudam, a activity é recriada.

3.2. Exemplo 02: estado e valores calculados

Uma calculadora simples de preços com IVA, que distingue o estado (o que o usuário digitou) do cálculo resultante. Neste exemplo, a estrutura da tela (barra superior, conteúdo com rolagem) é definida de uma vez por todas em [common/ExamplePage.kt]:

// =========================================================================
// common/ExamplePage.kt - a estrutura comum das telas dos exemplos
// -------------------------------------------------------------------------
// Todos os exemplos (do 02 em diante) têm a mesma estrutura de tela: uma
// barra superior com um título, depois um conteúdo em uma coluna, que ROLA se
// ultrapassar a altura da tela. Em vez de reescrevê-la 25 vezes, nós a
// escrevemos uma só vez, em uma função @Composable que recebe o conteúdo como
// parâmetro (cf. exemplo 12):
//
//     ExamplePage("Example 02 - state") {
//         Text("...")          // o conteúdo: componentes, um abaixo do outro
//         Button(...) { ... }
//     }
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.common

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ColumnScope
import androidx.compose.foundation.layout.RowScope
import androidx.compose.foundation.layout.consumeWindowInsets
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.imePadding
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.SnackbarHost
import androidx.compose.material3.SnackbarHostState
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

@Composable
fun ExamplePage(
    title: String,
    // um ícone à esquerda do título (nenhum por padrão)
    icon: @Composable () -> Unit = {},
    // botões à direita da barra superior (nenhum por padrão)
    actions: @Composable RowScope.() -> Unit = {},
    // a área das mensagens temporárias (Snackbar, cf. exemplo 16), opcional
    messages: SnackbarHostState? = null,
    // o conteúdo: uma função @Composable, chamada DENTRO de uma Column
    content: @Composable ColumnScope.() -> Unit,
) {
    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(title, style = MaterialTheme.typography.titleMedium, maxLines = 2) },
                navigationIcon = icon,
                actions = actions,
            )
        },
        snackbarHost = { if (messages != null) SnackbarHost(messages) },
    ) { insets ->
        Column(
            modifier = Modifier
                // os insets do Scaffold: abaixo da barra superior, acima
                // da barra de navegação do celular
                .padding(insets)
                .consumeWindowInsets(insets)
                // o teclado do celular não esconde a parte de baixo da tela
                .imePadding()
                .fillMaxSize()
                // a coluna rola se for mais alta que a tela
                .verticalScroll(rememberScrollState())
                .padding(16.dp),
            verticalArrangement = Arrangement.spacedBy(4.dp),
            content = content,
        )
    }
}
  • [content: @Composable ColumnScope.() -> Unit]: o conteúdo é uma função [@Composable] chamada DENTRO de uma [Column] (ela pode, portanto, usar modificadores específicos de coluna, como [weight]);
  • [verticalScroll(rememberScrollState())]: a coluna rola se exceder a altura da tela; [imePadding()]: o teclado do celular não esconde a parte inferior da tela;
  • Ela é chamada com uma lambda final: [ExamplePage("title") [ Text(...) ; Button(...) ]].

O código do exemplo:

// =========================================================================
// ex02/Ex02Activity.kt - estado e valores calculados
// -------------------------------------------------------------------------
// Uma pequena calculadora de preços com IVA:
//   - o ESTADO: variáveis mutableStateOf; alterá-las reexecuta
//     (recompõe) a função que as lê, que constrói a tela com os
//     novos valores;
//   - um valor CALCULADO a partir do estado NÃO é um estado: é uma
//     simples variável local, recalculada a cada execução da função.
//     Está sempre atualizado, sem nada a sincronizar;
//   - um dado que depende dos valores SUCESSIVOS do estado (o histórico
//     dos totais) é atualizado onde o estado muda;
//   - o título do aplicativo na lista de aplicativos recentes
//     acompanha o estado, como o resto da tela (TaskTitle).
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex02

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.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Add
import androidx.compose.material.icons.filled.KeyboardArrowDown
import androidx.compose.material3.Card
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.SegmentedButton
import androidx.compose.material3.SegmentedButtonDefaults
import androidx.compose.material3.SingleChoiceSegmentedButtonRow
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableDoubleStateOf
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import fr.stahe.examples.common.TaskTitle
import java.text.NumberFormat
import java.util.Locale

// um formatador de valores em euros, no formato inglês (€1,234.50), cf. exemplo 09
val euros: NumberFormat = NumberFormat.getCurrencyInstance(Locale.US).apply { currency = java.util.Currency.getInstance("EUR") }

// as alíquotas de IVA propostas
val rates = listOf(5.5, 10.0, 20.0)

// "2,5" ou "2.5" -> 2.5; um texto que não é um número -> 0
fun price(text: String): Double = text.replace(',', '.').toDoubleOrNull() ?: 0.0

// o total com IVA: uma função PURA (seu resultado depende apenas dos parâmetros)
fun totalInclVat(priceExclVat: Double, quantity: Int, vatRate: Double): Double = quantity * priceExclVat * (1 + vatRate / 100)

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

@Composable
fun CalculatorPage() {
    // o estado: o que o usuário digitou ou escolheu
    var label by rememberSaveable { mutableStateOf("Pen") }
    var priceText by rememberSaveable { mutableStateOf("2.5") } // o texto do campo, como digitado
    var quantity by rememberSaveable { mutableIntStateOf(1) }
    var vatRate by rememberSaveable { mutableDoubleStateOf(20.0) }
    // o histórico das últimas 5 alterações do total com IVA: uma lista
    // NÃO MODIFICÁVEL, substituída por uma nova lista a cada alteração
    var history by rememberSaveable { mutableStateOf(listOf<String>()) }

    // valores CALCULADOS: simples variáveis locais, recalculadas a
    // cada execução da função
    val priceExclVat = price(priceText)
    val totalExclVat = quantity * priceExclVat
    val vatAmount = totalExclVat * vatRate / 100
    val inclVat = totalExclVat + vatAmount

    // TODAS as alterações do estado passam por esta função local: ela
    // anota o total com IVA antes da alteração, aplica a alteração e
    // completa o histórico se o total mudou
    fun change(update: () -> Unit) {
        val old = inclVat
        update()
        // as variáveis de estado JÁ têm seu novo valor
        val newTotal = totalInclVat(price(priceText), quantity, vatRate)
        if (newTotal != old) {
            history = (listOf("${euros.format(old)} -> ${euros.format(newTotal)}") + history).take(5)
        }
    }

    // o título do aplicativo ACOMPANHA o estado, como todo o resto
    TaskTitle("Incl. VAT: ${euros.format(inclVat)}")
    val totalStyle = MaterialTheme.typography.titleMedium.copy(fontWeight = FontWeight.Bold)

    ExamplePage("Example 02 - state") {
        Card {
            Column(Modifier.padding(16.dp)) {
                // um campo CONTROLADO: ele exibe value e chama onValueChange
                // a cada tecla digitada, com o novo texto
                OutlinedTextField(
                    value = label,
                    // trocar o item redefine a quantidade para 1: isso é feito onde
                    // sabemos POR QUE o estado muda
                    onValueChange = { newValue ->
                        change {
                            label = newValue
                            quantity = 1
                        }
                    },
                    label = { Text("Item") },
                    modifier = Modifier.fillMaxWidth(),
                )
                OutlinedTextField(
                    value = priceText,
                    onValueChange = { text -> change { priceText = text } },
                    label = { Text("Unit price excl. VAT") },
                    // o teclado numérico do celular
                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Decimal),
                    modifier = Modifier.fillMaxWidth(),
                )
                Spacer(Modifier.height(12.dp))
                Row(verticalAlignment = Alignment.CenterVertically) {
                    // weight(1f): o texto ocupa toda a largura restante
                    Text("Quantity (back to 1 if the item changes)", Modifier.weight(1f))
                    // enabled = false: o botão está desabilitado
                    IconButton(onClick = { change { quantity-- } }, enabled = quantity > 0) {
                        Icon(Icons.Default.KeyboardArrowDown, contentDescription = "minus")
                    }
                    Text("$quantity", style = totalStyle)
                    IconButton(onClick = { change { quantity++ } }) {
                        Icon(Icons.Default.Add, contentDescription = "plus")
                    }
                }
                Spacer(Modifier.height(8.dp))
                // botões dos quais apenas UM é selecionado: a alíquota de IVA
                SingleChoiceSegmentedButtonRow(Modifier.fillMaxWidth()) {
                    rates.forEachIndexed { i, t ->
                        SegmentedButton(
                            selected = t == vatRate,
                            onClick = { change { vatRate = t } },
                            shape = SegmentedButtonDefaults.itemShape(index = i, count = rates.size),
                        ) {
                            Text("${t.toString().removeSuffix(".0")} %")
                        }
                    }
                }
                Spacer(Modifier.height(12.dp))
                OutlinedButton(onClick = {
                    change {
                        label = "Pen"
                        priceText = "2.5"
                        quantity = 1
                        vatRate = 20.0
                    }
                }) {
                    Text("Reset")
                }
            }
        }
        Card {
            Column(Modifier.padding(16.dp)) {
                Text("$quantity x $label", style = MaterialTheme.typography.titleLarge)
                HorizontalDivider(Modifier.padding(vertical = 8.dp))
                Line("Total excl. VAT", euros.format(totalExclVat))
                Line("VAT ($vatRate %)", euros.format(vatAmount))
                Line("Total incl. VAT", euros.format(inclVat), totalStyle)
            }
        }
        Card {
            Column(Modifier.padding(16.dp).fillMaxWidth()) {
                Text("History of the total incl. VAT", style = MaterialTheme.typography.titleSmall)
                // uma linha de texto por elemento do histórico (cf. exemplo 03)
                for (line in history) {
                    Text("• $line")
                }
            }
        }
    }
}

// uma linha "rótulo ....... valor": uma função @Composable que constrói
// outras. style: um parâmetro opcional, com seu valor padrão
@Composable
fun Line(label: String, amount: String, style: TextStyle = MaterialTheme.typography.bodyLarge) {
    Row(Modifier.padding(vertical = 4.dp)) {
        Text(label, Modifier.weight(1f), style = style)
        Text(amount, style = style)
    }
}
  • linhas 72–75: funções PURAS, fora da tela: o preço digitado (["2,5"] ou ["2.5"]) convertido em número, o total com IVA;
  • linhas 88–94: o estado. [history] é uma lista NÃO MODIFICÁVEL ([listOf]): ela é substituída por uma nova lista a cada alteração, o que o [Compose] detecta (a atribuição do estado);
  • linhas 98–101: os valores CALCULADOS são simples variáveis locais. A função é reexecutada a cada mudança de estado: eles estão sempre atualizados, portanto não há nada a sincronizar;
  • linhas 106–112: uma função LOCAL, por onde passam todas as alterações: ela registra o total antes da alteração, aplica a alteração ([update()]: a função passada como parâmetro), calcula o novo total e atualiza o histórico. As variáveis de estado já têm seus novos valores logo após a atribuição; [take(5)] retém as cinco primeiras linhas;
  • linha 117: o título do aplicativo na lista de aplicativos recentes acompanha o estado (função [TaskTitle] de [common/TaskTitle.kt], que chama [setTaskDescription] da activity);
  • linhas 125–136: um campo CONTROLADO: ele exibe [value] e chama [onValueChange] a cada tecla digitada, com o novo texto. Com o [Compose], o texto de um campo é apenas mais um estado: não é preciso criar nem liberar nenhum controlador, e [Reset] só precisa alterar o estado;
  • linha 143: [KeyboardOptions(keyboardType = KeyboardType.Decimal)]: o teclado numérico do celular;
  • linhas 147–156: a quantidade: [enabled = quantity > 0] desativa o botão “menos” em 0; [Modifier.weight(1f)]: o texto ocupa toda a largura restante da linha;
  • linhas 44–168: botões “segmentados”, dos quais apenas UM é selecionado: a alíquota de IVA. [forEachIndexed] percorre a lista com o índice de cada elemento; [itemShape] arredonda os cantos do primeiro e do último elementos;
  • linhas 209–212: [Line], uma função [@Composable] com parâmetros, um dos quais é opcional ([style], com seu valor padrão).

Image

Image

À esquerda, depois de tocar em [+] duas vezes, selecionar 10% e digitar 3.2; à direita, o item mudou: a quantidade voltou a 1, e o histórico registrou cada alteração do total.

3.3. Exemplo 03: escrevendo uma árvore de componentes

O [Compose] não tem uma linguagem de template: para condições e laços, usamos as instruções do [Kotlin], diretamente dentro da função [@Composable]. Uma lista de médicos, filtrada por um campo de entrada:

// =========================================================================
// ex03/Ex03Activity.kt - escrevendo uma árvore de componentes
// -------------------------------------------------------------------------
// O Compose não tem linguagem de template (nem HTML, nem XML): as
// telas são escritas em Kotlin, com chamadas aninhadas de funções
// @Composable. E para condições e laços, usamos... as
// instruções comuns do Kotlin, DIRETAMENTE na função:
//   - if (condition) { Component() }     : um componente que só EXISTE
//                                          se a condição for verdadeira;
//   - if (c) { A() } else { B() }        : um OU o outro;
//   - for (x in list) { Component(x) }   : um componente por elemento;
//   - when (value) { case -> ... }       : um valor entre vários.
// Uma função @Composable é uma função como qualquer outra: toda a
// linguagem está disponível para descrever a tela.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class, ExperimentalLayoutApi::class)

package fr.stahe.examples.ex03

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.AddCircle
import androidx.compose.material.icons.filled.Face
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.filled.Search
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.SuggestionChip
import androidx.compose.material3.SuggestionChipDefaults
import androidx.compose.material3.Switch
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.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.alpha
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.vector.ImageVector
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.R
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme

// uma "enumeração": os únicos valores possíveis de uma especialidade
enum class Specialty { GENERAL_PRACTITIONER, PEDIATRICIAN, CARDIOLOGIST }

// uma classe DATA: suas propriedades são val, um objeto Doctor nunca
// muda. O Kotlin adiciona a ela equals, hashCode, toString e copy
data class Doctor(
    val id: Int,
    val title: String,
    val firstName: String,
    val lastName: String,
    val specialty: Specialty,
    val available: Boolean,
)

val doctors = listOf(
    Doctor(1, "Mme", "Marie", "PELISSIER", Specialty.GENERAL_PRACTITIONER, true),
    Doctor(2, "Mr", "Paul", "TATOU", Specialty.PEDIATRICIAN, false),
    Doctor(3, "Melle", "Sophie", "DUPONT", Specialty.CARDIOLOGIST, true),
)

// "um valor entre vários, dependendo de um valor": uma EXPRESSÃO when.
// O compilador verifica que todos os casos da enumeração são tratados
fun label(s: Specialty): String = when (s) {
    Specialty.GENERAL_PRACTITIONER -> "general practitioner"
    Specialty.PEDIATRICIAN -> "pediatrician"
    Specialty.CARDIOLOGIST -> "cardiologist"
}

// um ícone e sua cor: um "par" de valores (Pair), escrito com "to"
fun icon(s: Specialty): Pair<ImageVector, Color> = when (s) {
    Specialty.PEDIATRICIAN -> Icons.Default.Face to Color(0xFFFF9800)
    Specialty.CARDIOLOGIST -> Icons.Default.Favorite to Color.Red
    else -> Icons.Default.AddCircle to Color(0xFF009688) // else: todos os outros casos
}

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

@Composable
fun DoctorsPage() {
    var filter by rememberSaveable { mutableStateOf("") } // o texto pesquisado
    var onlyAvailable by rememberSaveable { mutableStateOf(false) }
    var showHelp by rememberSaveable { mutableStateOf(true) }

    // a lista exibida: uma variável comum, recalculada a cada execução
    val text = filter.trim().lowercase()
    val displayed = doctors.filter { d ->
        (!onlyAvailable || d.available) &&
            "${d.firstName} ${d.lastName} ${label(d.specialty)}".lowercase().contains(text)
    }

    ExamplePage(
        title = "Example 03 - components",
        // uma imagem vetorial distribuída com o aplicativo (res/drawable/doctor.xml)
        icon = {
            Image(
                painter = painterResource(R.drawable.doctor),
                contentDescription = null,
                modifier = Modifier.padding(12.dp).size(28.dp),
            )
        },
    ) {
        OutlinedTextField(
            value = filter,
            onValueChange = { filter = it }, // it: o único parâmetro de uma lambda
            placeholder = { Text("search...") },
            leadingIcon = { Icon(Icons.Default.Search, contentDescription = null) },
            modifier = Modifier.fillMaxWidth(),
        )
        // um switch, com seu rótulo
        ListItem(
            headlineContent = { Text("available only") },
            trailingContent = { Switch(checked = onlyAvailable, onCheckedChange = { onlyAvailable = it }) },
        )
        TextButton(onClick = { showHelp = !showHelp }) {
            Text(if (showHelp) "Hide help" else "Show help")
        }
        // um if: este componente só EXISTE se showHelp for true
        if (showHelp) {
            Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFE1F5FE))) {
                Text(
                    "Type a name or a specialty. Unavailable doctors are greyed out.",
                    Modifier.padding(12.dp),
                )
            }
        }
        // "um dos três blocos": um when sem argumento, como uma série de if
        when {
            doctors.isEmpty() -> Text("No doctor.")
            displayed.isEmpty() -> Text("No doctor matches \"$filter\".", color = Color(0xFFFF5722))
            else -> Column {
                // um componente por médico, com sua posição: withIndex()
                for ((i, d) in displayed.withIndex()) {
                    DoctorRow(i + 1, d)
                }
            }
        }
        Spacer(Modifier.height(12.dp))
        // um estilo CALCULADO: o tamanho do texto depende do número de médicos exibidos
        Text(
            "${displayed.size} doctor(s) displayed - the size of this text depends on it.",
            fontSize = (12 + displayed.size * 2).sp,
        )
    }
}

// uma linha da lista: uma função @Composable com parâmetros
@Composable
fun DoctorRow(rank: Int, d: Doctor) {
    val (image, color) = icon(d.specialty) // uma "desestruturação" do par
    ListItem(
        // alpha: os médicos indisponíveis ficam esmaecidos
        modifier = Modifier.alpha(if (d.available) 1f else 0.5f),
        leadingContent = { Text("$rank", style = MaterialTheme.typography.titleMedium) },
        headlineContent = { Text("${d.title} ${d.firstName} ${d.lastName}") },
        // FlowRow: como uma Row, mas que quebra para a linha seguinte se faltar espaço
        supportingContent = {
            FlowRow(horizontalArrangement = Arrangement.spacedBy(6.dp)) {
                Icon(image, contentDescription = null, tint = color, modifier = Modifier.size(18.dp))
                Text(label(d.specialty))
            }
        },
        trailingContent = {
            SuggestionChip(
                onClick = {},
                label = { Text(if (d.available) "available" else "unavailable") },
                // uma cor escolhida por uma expressão condicional
                colors = SuggestionChipDefaults.suggestionChipColors(
                    containerColor = if (d.available) Color(0xFFC8E6C9) else Color(0xFFE0E0E0),
                ),
            )
        },
    )
}
  • linhas 68–78: uma enumeração e uma data class ([data class]): o [Kotlin] escreve [equals], [hashCode], [toString] e [copy];
  • linhas 89–99: uma EXPRESSÃO [when]: um valor entre vários; o compilador verifica se todos os casos da enumeração são tratados ([else]: todos os demais). [to] cria um par ([Pair]);
  • linhas 117–120: a lista exibida, calculada a cada execução com base no estado ([filter]);
  • linhas 126–130: [icon]: um slot de [ExamplePage] para o ícone da barra superior. [painterResource(R.drawable.doctor)]: uma imagem do aplicativo (um arquivo VECTOR, o formato vetorial do [Android], convertido do arquivo SVG do exemplo Flutter com [New / Vector Asset] do [Android Studio]). [R]: a classe gerada que atribui um número a cada recurso;
  • linha 136: [it]: o nome do único parâmetro de uma lambda;
  • linha 150: um [if]: o componente só EXISTE se a condição for verdadeira;
  • linhas 159–165: um [when] sem argumentos (uma sequência de [if]): um dos três blocos; um laço [for], com o índice de cada elemento ([withIndex()] e uma desestruturação [(i, d)]);
  • linha 173: um estilo calculado: o tamanho do texto depende do número de médicos ([sp]: a unidade para texto, que segue a configuração de tamanho de texto do celular; [dp]: a unidade para distâncias);
  • linhas 180–199: uma linha de lista ([ListItem], com suas posições [leadingContent], [headlineContent]...), esmaecida por [Modifier.alpha] se o médico estiver indisponível; [FlowRow]: uma linha que quebra para a linha seguinte se não houver espaço suficiente; um marcador ([SuggestionChip]) cuja cor depende do médico.

Image

Image

Image

3.4. Exemplo 04: eventos

Uma lista de tarefas: é possível adicionar itens, marcá-los como concluídos e excluí-los (com um botão ou deslizando a linha, o gesto típico de um dispositivo móvel), além de uma área sensível ao toque. Um componente interativo recebe FUNÇÕES como parâmetros, para serem chamadas quando algo acontece: esses são os “eventos” do [Compose].

// =========================================================================
// ex04/Ex04Activity.kt - reagindo às ações do usuário
// -------------------------------------------------------------------------
// Um componente interativo recebe como parâmetros as FUNÇÕES a chamar
// quando algo acontece ("callbacks", lambdas do Kotlin):
//   - onClick = { ... }              : chamada ao pressionar (botões);
//   - onClick = { remove(t) }        : a lambda passa seus próprios argumentos;
//   - onValueChange, onCheckedChange : a função recebe um valor (o
//                                      texto, a caixa marcada...);
//   - Modifier.pointerInput          : adiciona gestos (toque, toque
//                                      duplo, toque longo...) a QUALQUER
//                                      componente;
//   - SwipeToDismissBox              : deslizar uma linha para
//                                      removê-la, o gesto típico do mobile.
// Para dar o foco a um campo a partir do código, associamos a ele um
// FocusRequester.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex04

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.text.KeyboardActions
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Delete
import androidx.compose.material.icons.outlined.Delete
import androidx.compose.material3.Button
import androidx.compose.material3.Checkbox
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.SwipeToDismissBox
import androidx.compose.material3.Text
import androidx.compose.material3.rememberSwipeToDismissBoxState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.key
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
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.input.key.Key
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onPreviewKeyEvent
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.input.ImeAction
import androidx.compose.ui.text.style.TextDecoration
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 java.time.LocalTime
import java.time.format.DateTimeFormatter
import kotlin.math.roundToInt

// uma tarefa: uma data class NÃO MODIFICÁVEL; para "marcá-la",
// fazemos uma cópia dela: task.copy(done = true)
data class Task(val id: Int, val label: String, val done: Boolean = false)

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

@Composable
fun TasksPage() {
    // listas OBSERVADAS pelo Compose: adicionar, remover ou substituir um
    // elemento provoca a recomposição. (remember, e não rememberSaveable:
    // elas são perdidas se a activity for recriada, cf. exemplo 20)
    val tasks = remember {
        mutableStateListOf(Task(1, "Install Android Studio", done = true), Task(2, "Read the chapter on events"))
    }
    val log = remember { mutableStateListOf<String>() }
    var input by remember { mutableStateOf("") }
    var nextId by remember { mutableIntStateOf(3) }
    // o FocusRequester: uma forma de dar o foco ao campo (o cursor e o teclado
    // do celular) a partir do código
    val focus = remember { FocusRequester() }

    fun trace(message: String) {
        val time = LocalTime.now().format(DateTimeFormatter.ofPattern("HH:mm"))
        log.add(0, "$time $message")
    }

    // chamada pelo botão E pela tecla "OK" do teclado (keyboardActions)
    fun add() {
        val label = input.trim()
        if (label.isEmpty()) {
            return
        }
        tasks.add(Task(nextId++, label))
        trace("added \"$label\"")
        input = ""
        // o foco volta ao campo: a próxima tarefa pode ser digitada
        focus.requestFocus()
    }

    fun toggle(task: Task, done: Boolean) {
        // SUBSTITUÍMOS a tarefa por uma cópia modificada
        tasks[tasks.indexOf(task)] = task.copy(done = done)
        trace("\"${task.label}\": ${if (done) "done" else "to do"}")
    }

    fun remove(task: Task, how: String) {
        tasks.remove(task)
        trace("removed \"${task.label}\" ($how)")
    }

    // a densidade da tela: para converter pixels em dp
    val density = LocalDensity.current.density

    ExamplePage("Example 04 - events") {
        Row(verticalAlignment = Alignment.CenterVertically) {
            OutlinedTextField(
                value = input,
                onValueChange = { input = it },
                placeholder = { Text("new task (Escape to clear)") },
                singleLine = true,
                // a tecla "OK" do teclado do celular adiciona a tarefa
                keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
                keyboardActions = KeyboardActions(onDone = { add() }),
                modifier = Modifier
                    .weight(1f)
                    .focusRequester(focus)
                    // um teclado físico (emulador, tablet): Escape limpa o campo
                    .onPreviewKeyEvent { event ->
                        if (event.key == Key.Escape) {
                            input = ""
                            true // o evento foi tratado
                        } else {
                            false // o evento segue seu caminho
                        }
                    },
            )
            Spacer(Modifier.width(8.dp))
            Button(onClick = { add() }) { Text("Add") }
        }
        Spacer(Modifier.height(12.dp))
        for (t in tasks) {
            // key(t.id): a IDENTIDADE da linha. O estado de cada linha (seu
            // deslize) acompanha SUA tarefa, mesmo que a lista mude (cf. o curso)
            key(t.id) {
                TaskRow(
                    task = t,
                    onToggle = { done -> toggle(t, done) },
                    onRemove = { how -> remove(t, how) },
                )
            }
        }
        Spacer(Modifier.height(12.dp))
        // pointerInput: qualquer componente passa a ser sensível a gestos
        Box(
            contentAlignment = Alignment.Center,
            modifier = Modifier
                .fillMaxWidth()
                .height(80.dp)
                .background(Color(0xFFE7F5FF), RoundedCornerShape(8.dp))
                .pointerInput(Unit) {
                    detectTapGestures(
                        // a posição do toque, relativa ao componente (em pixels)
                        onPress = { p -> trace("press at (${(p.x / density).roundToInt()}, ${(p.y / density).roundToInt()})") },
                        onDoubleTap = { trace("double tap") },
                        onLongPress = { trace("long press") },
                    )
                },
        ) {
            Text("Touch this area (tap, double tap, long press)")
        }
        Spacer(Modifier.height(16.dp))
        Text("Log", style = MaterialTheme.typography.titleSmall)
        for (line in log) {
            Text(line, fontSize = 12.sp)
        }
    }
}

// uma linha da lista: a tarefa e DUAS funções para notificar o chamador
@Composable
fun TaskRow(task: Task, onToggle: (Boolean) -> Unit, onRemove: (String) -> Unit) {
    // o estado de deslize da linha (onde ela está?)
    val swipe = rememberSwipeToDismissBoxState()
    // SwipeToDismissBox: deslizar a linha para a esquerda a remove
    SwipeToDismissBox(
        state = swipe,
        enableDismissFromStartToEnd = false,
        // onDismiss: chamada quando a linha foi deslizada até o fim
        onDismiss = { onRemove("swipe") },
        // o que aparece EMBAIXO da linha quando ela é deslizada
        backgroundContent = {
            Box(
                contentAlignment = Alignment.CenterEnd,
                modifier = Modifier.fillMaxSize().background(Color(0xFFFFCDD2)).padding(end = 16.dp),
            ) {
                Icon(Icons.Default.Delete, contentDescription = null)
            }
        },
    ) {
        ListItem(
            // a caixa fica À ESQUERDA, como em uma lista de tarefas; ela
            // repassa seu novo valor (um Boolean)
            leadingContent = { Checkbox(checked = task.done, onCheckedChange = onToggle) },
            headlineContent = {
                Text(
                    task.label,
                    style = if (task.done) {
                        TextStyle(textDecoration = TextDecoration.LineThrough, color = Color.Gray)
                    } else {
                        TextStyle.Default
                    },
                )
            },
            trailingContent = {
                IconButton(onClick = { onRemove("button") }) {
                    Icon(Icons.Outlined.Delete, contentDescription = "remove", tint = Color.Red)
                }
            },
        )
    }
}
  • linha 84: uma tarefa, um objeto NÃO MODIFICÁVEL; ao marcá-la, cria-se uma cópia ([copy(done = true)]) que a SUBSTITUI;
  • linhas 99–102: [mutableStateListOf]: uma lista OBSERVADA pelo [Compose]; adicionar, remover ou substituir um elemento dispara uma recomposição. Aqui, mantemos [remember] (e não [rememberSaveable]): essas listas são perdidas se a activity for recriada;
  • linha 107: um [FocusRequester], pelo qual o código dá o foco (o cursor e o teclado) ao campo após cada adição ([focus.requestFocus()]);
  • linhas 115–135: três funções locais que modificam o estado e mantêm o log;
  • linhas 149–150: [imeAction = ImeAction.Done]: a tecla de confirmação do teclado do celular passa a ser “OK”, e [keyboardActions] especifica o que fazer quando ela é pressionada: adicionar a tarefa;
  • linhas 68–160: [onPreviewKeyEvent] recebe as teclas de um teclado FÍSICO (o do PC no emulador, ou o teclado de um tablet): [Escape] limpa o campo. Retornar [true] interrompe o evento;
  • linhas 171–175: [key(t.id)] atribui uma IDENTIDADE a cada linha. Sem [key], o [Compose] associa o estado de uma linha (neste caso, sua posição de rolagem) à sua POSIÇÃO na lista: após uma exclusão, a linha seguinte herdaria o estado da linha excluída. As duas expressões lambda [onToggle] e [onRemove] “capturam” a tarefa [t] e repassam o que a linha lhes passa;
  • linhas 187–192: [Modifier.pointerInput] torna QUALQUER componente sensível a gestos: ele distingue um toque simples, um toque duplo e um toque longo. A posição é dada em pixels: ela é convertida em [dp] usando a densidade da tela ([LocalDensity]);
  • linha 208: [TaskRow] recebe a tarefa e DUAS funções para notificar quem a chamou: ela mesma não modifica a lista (veja o Exemplo 11);
  • linhas 212–218: [SwipeToDismissBox]: a linha se move para a esquerda ([enableDismissFromStartToEnd = false] impede o movimento no outro sentido), revelando [backgroundContent]; ao chegar ao fim, [onDismiss] é chamada;
  • linha 230: a caixa de seleção transmite seu novo valor ([Boolean]): [onToggle], que tem o tipo correto [(Boolean) -> Unit], é passada diretamente a ela.

Image

Image

Image

À esquerda, uma tarefa foi adicionada, outra foi marcada e a área foi tocada; no meio, a primeira linha desliza para a esquerda; à direita, ela foi excluída, e o log confirma isso.

3.5. Exemplo 05: todos os tipos de campo

Com o [Compose], TODOS os campos são CONTROLADOS: o campo exibe um valor do estado e notifica cada alteração por meio de uma função que atualiza o estado. O que essa função transmite depende do campo:

  • [OutlinedTextField]: o novo texto ([String]);
  • [Checkbox], [Switch]: um [Boolean];
  • [RadioButton], [FilterChip]: nada (a entrada É selecionada);
  • [Slider]: um [Float];
  • [DatePickerDialog]: uma data, ao confirmar.

Para a lista suspensa, o [Material 3] não fornece um único componente autônomo: ela é montada de uma vez por todas em [common/DropdownList.kt]:

// =========================================================================
// common/DropdownList.kt - uma lista suspensa, pronta para uso
// -------------------------------------------------------------------------
// O Material 3 para Compose não tem um componente de "lista suspensa" em
// uma só peça: ela é montada a partir de três elementos - ExposedDropdownMenuBox,
// um campo de texto somente leitura e o menu ExposedDropdownMenu.
// Fazemos isso aqui uma vez por todas (exemplos 05 a 08, 24, 25):
//
//     DropdownList("Country", value = country, choices = listOf("fr", "be", "ch"),
//                  text = { countryNames[it] }, onChange = { country = it })
//
// A função é GENÉRICA (<T>): as opções podem ser strings,
// números, médicos... text diz como EXIBIR uma opção. Uma opção
// pode ser null ("— choose —") se T for um tipo "anulável" (Int?).
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.common

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.ExposedDropdownMenuAnchorType
import androidx.compose.material3.ExposedDropdownMenuBox
import androidx.compose.material3.ExposedDropdownMenuDefaults
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
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

@Composable
fun <T> DropdownList(
    label: String,
    value: T,
    choices: List<T>,
    onChange: (T) -> Unit,
    modifier: Modifier = Modifier,
    text: (T) -> String = { it.toString() },
    // uma mensagem de erro sob o campo (cf. exemplos 07 e 25)
    error: String? = null,
) {
    // o menu está aberto? um estado ESPECÍFICO de cada lista suspensa
    var open by remember { mutableStateOf(false) }
    ExposedDropdownMenuBox(expanded = open, onExpandedChange = { open = it }, modifier = modifier) {
        // o campo que exibe a opção atual; menuAnchor o transforma no
        // ponto de ancoragem do menu (tocar nele abre o menu)
        OutlinedTextField(
            value = text(value),
            onValueChange = {},
            readOnly = true,
            singleLine = true,
            label = { Text(label) },
            trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = open) },
            isError = error != null,
            supportingText = if (error == null) null else { { Text(error) } },
            modifier = Modifier.menuAnchor(ExposedDropdownMenuAnchorType.PrimaryNotEditable).fillMaxWidth(),
        )
        // o menu: uma linha por opção
        ExposedDropdownMenu(expanded = open, onDismissRequest = { open = false }) {
            for (c in choices) {
                DropdownMenuItem(
                    text = { Text(text(c)) },
                    onClick = {
                        onChange(c)
                        open = false
                    },
                )
            }
        }
    }
}
  • linhas 36–44: [fun <T> DropdownList]: uma função GENÉRICA: as opções podem ser strings, números, médicos... [text] especifica como exibir uma opção (por padrão, seu [toString()]);
  • linha 47: o estado específico de cada lista: o menu está aberto?
  • linhas 48–49: [ExposedDropdownMenuBox] associa um campo SOMENTE LEITURA ([readOnly = true]), que exibe a opção atual, a um menu; [menuAnchor] faz do campo o ponto de ancoragem do menu;
  • linhas 63–68: uma linha de menu por opção; ao pressioná-la, quem chamou é notificado ([onChange(c)]) e o menu se fecha.

O código do exemplo:

// =========================================================================
// ex05/Ex05Activity.kt - todos os tipos de campos
// -------------------------------------------------------------------------
// No Compose, TODOS os campos são CONTROLADOS: um campo exibe um
// valor do estado (value, checked, selected...) e notifica cada
// alteração por meio de uma função (onValueChange, onCheckedChange, onClick...),
// que atualiza o estado. O estado é a única fonte da verdade: modificar
// o estado (a partir do código) modifica o campo. O que a função repassa
// depende do campo:
//   - OutlinedTextField               -> o novo texto (String);
//   - Checkbox, Switch                -> Boolean;
//   - RadioButton                     -> nada: onClick é a escolha;
//   - DropdownList (common/)          -> o valor do elemento escolhido;
//   - FilterChip                      -> nada: onClick alterna o chip;
//   - Slider                          -> Float;
//   - DatePickerDialog (um diálogo)   -> uma data, na confirmação.
// Tudo acontece no celular, sem servidor.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class, ExperimentalLayoutApi::class)

package fr.stahe.examples.ex05

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.selection.selectable
import androidx.compose.foundation.selection.selectableGroup
import androidx.compose.foundation.selection.toggleable
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material3.Button
import androidx.compose.material3.Checkbox
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerDialog
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.FilterChip
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.RadioButton
import androidx.compose.material3.Slider
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableFloatStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.semantics.Role
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import java.time.Instant
import java.time.LocalDate
import java.time.ZoneOffset

val titles = listOf("Mr", "Mme", "Melle")
val hobbies = listOf("sport", "music", "reading", "cinema")
val countries = mapOf("fr" to "France", "be" to "Belgium", "ch" to "Switzerland")
val languages = mapOf("fr" to "French", "en" to "English", "es" to "Spanish")

// todos os valores, reunidos em um objeto (o que seria enviado a um servidor).
// @Serializable: o plugin kotlinx.serialization pode convertê-lo em JSON
@Serializable
data class Model(
    val title: String,
    val name: String,
    val age: Int?,
    val presentation: String,
    val newsletter: Boolean,
    val hobbies: List<String>,
    val country: String,
    val languages: List<String>,
    val birthDate: String?,
    val satisfaction: Int,
)

// o conversor JSON: prettyPrint, JSON indentado
val indentedJson = Json { prettyPrint = true }

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

@Composable
fun FormPage() {
    // um estado por campo do formulário
    var title by rememberSaveable { mutableStateOf("Mme") }
    var name by rememberSaveable { mutableStateOf("") }
    var age by rememberSaveable { mutableStateOf("30") }
    var presentation by rememberSaveable { mutableStateOf("") } // o valor VALIDADO
    var draft by rememberSaveable { mutableStateOf("") } // o texto sendo digitado
    var newsletter by rememberSaveable { mutableStateOf(false) }
    var myHobbies by rememberSaveable { mutableStateOf(setOf("reading")) } // um SET: sem duplicatas
    var myCountry by rememberSaveable { mutableStateOf("fr") }
    var myLanguages by rememberSaveable { mutableStateOf(setOf<String>()) }
    var birthDate by rememberSaveable { mutableStateOf<LocalDate?>(null) } // null: ainda não escolhido
    var satisfaction by rememberSaveable { mutableFloatStateOf(3f) }
    var sent by rememberSaveable { mutableStateOf<String?>(null) }
    var calendarOpen by rememberSaveable { mutableStateOf(false) }

    // o modelo: um valor CALCULADO a partir do estado
    val model = Model(
        title = title,
        name = name.trim(),
        age = age.toIntOrNull(), // null se o campo estiver vazio
        presentation = presentation,
        newsletter = newsletter,
        hobbies = myHobbies.toList(),
        country = myCountry,
        languages = myLanguages.toList(),
        birthDate = birthDate?.toString(), // "2026-10-05": o formato de data da API RdvMedecins
        satisfaction = satisfaction.toInt(),
    )
    val titleStyle = MaterialTheme.typography.titleSmall

    ExamplePage("Example 05 - controlled fields") {
        Text("Title", style = titleStyle)
        // selectableGroup: um grupo de botões de opção (para acessibilidade)
        Row(Modifier.selectableGroup(), verticalAlignment = Alignment.CenterVertically) {
            for (t in titles) {
                // selectable: a linha INTEIRA (botão + texto) reage ao toque
                Row(
                    verticalAlignment = Alignment.CenterVertically,
                    modifier = Modifier.selectable(selected = title == t, onClick = { title = t }, role = Role.RadioButton),
                ) {
                    RadioButton(selected = title == t, onClick = null)
                    Text(t)
                    Spacer(Modifier.width(12.dp))
                }
            }
        }
        Row {
            OutlinedTextField(value = name, onValueChange = { name = it }, label = { Text("Name") }, modifier = Modifier.weight(2f))
            Spacer(Modifier.width(12.dp))
            OutlinedTextField(
                value = age,
                onValueChange = { age = it },
                label = { Text("Age") },
                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
                modifier = Modifier.weight(1f),
            )
        }
        // onFocusChanged: notifica quando o campo GANHA ou PERDE o foco. A
        // apresentação só é copiada para o estado ao sair do campo
        OutlinedTextField(
            value = draft,
            onValueChange = { draft = it },
            label = { Text("Presentation (updated when leaving the field)") },
            minLines = 2,
            modifier = Modifier.fillMaxWidth().onFocusChanged { state ->
                if (!state.isFocused) presentation = draft
            },
        )
        // uma única caixa: true / false. toggleable: a linha inteira reage
        ListItem(
            modifier = Modifier.toggleable(value = newsletter, onValueChange = { newsletter = it }, role = Role.Checkbox),
            leadingContent = { Checkbox(checked = newsletter, onCheckedChange = null) },
            headlineContent = { Text("Receive the newsletter") },
        )
        Text("Hobbies", style = titleStyle)
        // vários chips para UM conjunto: o valor é adicionado ou removido
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            for (h in hobbies) {
                FilterChip(
                    selected = h in myHobbies,
                    onClick = { myHobbies = if (h in myHobbies) myHobbies - h else myHobbies + h },
                    label = { Text(h) },
                )
            }
        }
        // uma lista suspensa: value indica qual elemento está escolhido
        DropdownList(
            label = "Country",
            value = myCountry,
            choices = countries.keys.toList(),
            text = { code -> countries.getValue(code) },
            onChange = { myCountry = it },
            modifier = Modifier.width(220.dp),
        )
        Text("Spoken languages", style = titleStyle)
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            for ((code, label) in languages) {
                FilterChip(
                    selected = code in myLanguages,
                    onClick = { myLanguages = if (code in myLanguages) myLanguages - code else myLanguages + code },
                    label = { Text(label) },
                )
            }
        }
        Row(verticalAlignment = Alignment.CenterVertically) {
            Text("Satisfaction: ${satisfaction.toInt()} / 5", style = titleStyle)
            // um slider de 1 a 5: 3 passos intermediários (2, 3, 4)
            Slider(
                value = satisfaction,
                onValueChange = { satisfaction = it },
                valueRange = 1f..5f,
                steps = 3,
                modifier = Modifier.weight(1f).padding(start = 8.dp),
            )
        }
        ListItem(
            leadingContent = { Icon(Icons.Default.DateRange, contentDescription = null) },
            headlineContent = { Text("Date of birth") },
            supportingContent = { Text(birthDate?.toString() ?: "not chosen") },
            trailingContent = { OutlinedButton(onClick = { calendarOpen = true }) { Text("Choose") } },
        )
        // FlowRow: os botões quebram para a linha seguinte em uma tela estreita
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            Button(onClick = { sent = Json.encodeToString(Model.serializer(), model) }) { Text("Send") }
            // o estado modificado PELO CÓDIGO: os campos acompanham
            OutlinedButton(onClick = {
                title = "Mr"
                name = "MARTIN"
                age = "42"
                myHobbies = setOf("sport", "cinema")
                myCountry = "be"
            }) { Text("Fill in by code") }
        }
        Spacer(Modifier.height(8.dp))
        Text("The model, live", style = titleStyle)
        Text(
            indentedJson.encodeToString(Model.serializer(), model),
            fontFamily = FontFamily.Monospace,
            fontSize = 12.sp,
            modifier = Modifier.fillMaxWidth().background(Color(0xFFF5F5F5)).padding(8.dp),
        )
        // um bloco que só existe após um envio; ?.let: somente se sent não for null
        sent?.let { json ->
            Text("Last submission", style = titleStyle)
            Text(
                json,
                fontFamily = FontFamily.Monospace,
                fontSize = 12.sp,
                modifier = Modifier.fillMaxWidth().background(Color(0xFFE8F5E9)).padding(8.dp),
            )
        }
    }

    // o diálogo do calendário: só existe se calendarOpen for true
    if (calendarOpen) {
        // o estado do calendário: a data selecionada, em milissegundos (UTC)
        val calendarState = rememberDatePickerState(
            initialSelectedDateMillis = (birthDate ?: LocalDate.of(2000, 1, 1)).atStartOfDay(ZoneOffset.UTC).toInstant().toEpochMilli(),
        )
        DatePickerDialog(
            onDismissRequest = { calendarOpen = false },
            confirmButton = {
                TextButton(onClick = {
                    calendarState.selectedDateMillis?.let { ms ->
                        birthDate = Instant.ofEpochMilli(ms).atZone(ZoneOffset.UTC).toLocalDate()
                    }
                    calendarOpen = false
                }) { Text("OK") }
            },
            dismissButton = { TextButton(onClick = { calendarOpen = false }) { Text("Cancel") } },
        ) {
            DatePicker(state = calendarState)
        }
    }
}
  • linhas 89–101: todos os valores do formulário, agrupados em uma classe [@Serializable]: o plugin [kotlinx.serialization] gera, em tempo de compilação, o código que a converte em JSON ([Json.encodeToString(Model.serializer(), model)]);
  • Linhas 118–130: um estado por campo. [myHobbies] é um CONJUNTO ([Set]) não modificável: [myHobbies + h] e [myHobbies - h] geram novos conjuntos; [birthDate] é uma data “anulável” ([LocalDate?]): [null] até que um valor seja selecionado;
  • linhas 133–143: o modelo, um valor CALCULADO a cada execução; [toIntOrNull()]: o número, ou [null] se o texto não for um número;
  • linhas 150–157: botões de opção. [Modifier.selectable] torna a linha INTEIRA (o botão e o texto) clicável; o botão em si, portanto, não tem ação ([onClick = null]); [selectableGroup] agrupa os botões para as ferramentas de acessibilidade;
  • Linhas 177–182: a apresentação é copiada para o estado somente ao SAIR do campo; [onFocusChanged] dispara uma notificação quando o campo ganha ou perde o foco;
  • linhas 187–189: uma caixa de seleção, que funciona da mesma forma que os botões de opção ([Modifier.toggleable] na linha inteira);
  • linhas 193–198: caixas de seleção ([FilterChip]) para selecionar vários valores; [FlowRow] as quebra para a linha seguinte se não houver espaço suficiente;
  • linhas 203–208: a lista suspensa de [common/];
  • linhas 224–228: um controle deslizante de 1 a 5: [steps = 3] com etapas intermediárias;
  • linhas 236–248: “Preencher por código”: o estado é modificado, e os campos o acompanham;
  • linhas 251–259: o modelo exibido em JSON, indentado ([Json [ prettyPrint = true ]]); [sent?.let [ ... ]]: o bloco só existe se [sent] não for [null];
  • Linhas 271–288: a janela do calendário só existe se [calendarOpen] for verdadeiro. [DatePicker] opera em milissegundos desde 1º de janeiro de 1970 (hora UTC): a conversão funciona nos dois sentidos com [java.time] ([LocalDate], [Instant], [ZoneOffset.UTC]).

Image

Image

Image

O calendário ([DatePickerDialog]) está em inglês: o [Material 3] segue o idioma do aplicativo (veja o Exemplo 21).

3.6. Exemplo 06: um formulário, um objeto, um reducer

O Exemplo 05 tinha uma variável de estado por campo. Para um formulário real, preferimos UM objeto que contenha todos os valores e descrevemos suas alterações em uma única função PURA, o REDUCER: [reducer(currentState, action) -> newState]. A tela deixa de modificar o estado: ela informa o que aconteceu (“o campo LASTNAME agora tem o valor ‘Dupont’”, “o campo LASTNAME foi abandonado”), e o reducer deduz daí o novo estado.

// =========================================================================
// ex06/Ex06Activity.kt - um formulário, um objeto, um reducer
// -------------------------------------------------------------------------
// O exemplo 05 tinha uma variável de estado por campo do formulário. Para um
// formulário real, preferimos UM objeto que contém todos os valores, o
// MODELO (aqui um objeto Profile, não modificável), e descrevemos suas
// alterações em uma única função, o REDUCER:
//
//     reducer(currentState, action) -> newState
//
// A tela não modifica mais o estado: ela DESCREVE o que aconteceu, com um
// objeto ProfileAction (Update(Field.LASTNAME, "Dupont"), Leave(Field.LASTNAME)...),
// e o reducer deduz dele o novo estado. Toda a lógica fica em um só
// lugar, em uma função PURA (mesma entrada, mesma saída, sem efeito
// colateral), fácil de testar.
// O Kotlin se presta bem a isso: uma interface "sealed" lista todas as ações
// possíveis, e um when sobre uma ação é verificado pelo compilador (um
// caso esquecido é um erro).
//
// O estado também guarda, para cada campo, se ele foi "tocado" (deixado pelo
// menos uma vez); disso deduzimos se ele foi "modificado" (seu valor difere do
// valor inicial) e se está desabilitado.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class, ExperimentalLayoutApi::class)

package fr.stahe.examples.ex06

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.selection.selectable
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.RadioButton
import androidx.compose.material3.Slider
import androidx.compose.material3.Switch
import androidx.compose.material3.Text
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.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.JsonObject

// o nome de cada campo do formulário
enum class Field { TITLE, FIRSTNAME, LASTNAME, AGE, NEWSLETTER, EMAIL, COUNTRY, PRESENTATION }

// os dados do formulário: um objeto NÃO MODIFICÁVEL (tudo é val). Para
// "modificá-lo", fazemos uma cópia dele: profile.copy(lastName = "DUPONT"). A
// função copy é escrita pelo Kotlin para qualquer classe "data"
data class Profile(
    val title: String,
    val firstName: String,
    val lastName: String,
    val age: Int,
    val newsletter: Boolean,
    val email: String,
    val country: String,
    val presentation: String,
) {
    // o valor de um campo, designado por seu nome
    fun value(f: Field): Any = when (f) {
        Field.TITLE -> title
        Field.FIRSTNAME -> firstName
        Field.LASTNAME -> lastName
        Field.AGE -> age
        Field.NEWSLETTER -> newsletter
        Field.EMAIL -> email
        Field.COUNTRY -> country
        Field.PRESENTATION -> presentation
    }

    // uma cópia na qual UM campo, designado por seu nome, tem um novo valor
    fun withValue(f: Field, v: Any): Profile = when (f) {
        Field.TITLE -> copy(title = v as String)
        Field.FIRSTNAME -> copy(firstName = v as String)
        Field.LASTNAME -> copy(lastName = v as String)
        Field.AGE -> copy(age = v as Int)
        Field.NEWSLETTER -> copy(newsletter = v as Boolean)
        Field.EMAIL -> copy(email = v as String)
        Field.COUNTRY -> copy(country = v as String)
        Field.PRESENTATION -> copy(presentation = v as String)
    }

    // o objeto JSON do perfil: um campo JSON por campo do formulário
    fun toJson(): JsonObject = JsonObject(
        Field.entries.associate { f ->
            val v = value(f)
            f.name.lowercase() to when (v) {
                is Int -> JsonPrimitive(v) // "is": um teste de tipo; v é então um Int
                is Boolean -> JsonPrimitive(v)
                else -> JsonPrimitive(v.toString())
            }
        },
    )
}

val initial = Profile(
    title = "Mme",
    firstName = "Marie",
    lastName = "PELISSIER",
    age = 30,
    newsletter = false,
    email = "",
    country = "fr",
    presentation = "",
)

// o estado completo: os valores e os campos já deixados
data class State(val values: Profile, val touched: Set<Field>)

// as ações possíveis. "sealed": não há outras além das
// declaradas aqui, o compilador sabe disso
sealed interface ProfileAction {
    data class Update(val field: Field, val value: Any) : ProfileAction
    data class Leave(val field: Field) : ProfileAction
    data object Uppercase : ProfileAction // um objeto único: a ação não tem dados
    data object Reset : ProfileAction
}

// o reducer: ele NUNCA modifica o estado recebido, retorna um novo.
// Em cada ramo do when, action tem o tipo do ramo ("smart cast"):
// action.field é acessível para um Update
fun reducer(state: State, action: ProfileAction): State = when (action) {
    is ProfileAction.Update -> state.copy(values = state.values.withValue(action.field, action.value))
    is ProfileAction.Leave -> state.copy(touched = state.touched + action.field)
    ProfileAction.Uppercase -> state.copy(
        values = state.values.copy(firstName = state.values.firstName.uppercase(), lastName = state.values.lastName.uppercase()),
    )
    ProfileAction.Reset -> State(initial, emptySet())
}

val titles = listOf("Mr", "Mme", "Melle")
val trackedFields = listOf(Field.FIRSTNAME, Field.LASTNAME, Field.AGE, Field.EMAIL)
val countryNames = mapOf("fr" to "France", "be" to "Belgium", "ch" to "Switzerland")
val indentedJson = Json { prettyPrint = true }

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

@Composable
fun ProfilePage() {
    var state by remember { mutableStateOf(State(initial, emptySet())) }

    // A ÚNICA forma de mudar o estado: descrever o que aconteceu
    fun dispatch(action: ProfileAction) {
        state = reducer(state, action)
    }

    val v = state.values
    // valores DEDUZIDOS do estado
    fun modified(f: Field) = v.value(f) != initial.value(f)
    fun disabled(f: Field) = f == Field.EMAIL && !v.newsletter // o e-mail exige a newsletter
    val formModified = Field.entries.any { modified(it) }
    val titleStyle = MaterialTheme.typography.titleSmall

    // um campo de texto ligado ao modelo: uma função @Composable LOCAL
    @Composable
    fun TextField(field: Field, label: String, modifier: Modifier = Modifier, lines: Int = 1) {
        // o campo já teve o foco? (um estado específico de CADA campo)
        var hadFocus by remember { mutableStateOf(false) }
        OutlinedTextField(
            value = v.value(field) as String,
            onValueChange = { text -> dispatch(ProfileAction.Update(field, text)) },
            label = { Text(label) },
            enabled = !disabled(field),
            minLines = lines,
            // o campo é DEIXADO quando perde o foco... depois de tê-lo tido
            modifier = modifier.onFocusChanged { f ->
                if (f.isFocused) {
                    hadFocus = true
                } else if (hadFocus) {
                    dispatch(ProfileAction.Leave(field))
                }
            },
        )
    }

    ExamplePage("Example 06 - a reducer") {
        Row(verticalAlignment = Alignment.CenterVertically) {
            for (t in titles) {
                Row(
                    verticalAlignment = Alignment.CenterVertically,
                    modifier = Modifier.selectable(selected = v.title == t, onClick = { dispatch(ProfileAction.Update(Field.TITLE, t)) }),
                ) {
                    RadioButton(selected = v.title == t, onClick = null)
                    Text(t)
                    Spacer(Modifier.width(12.dp))
                }
            }
        }
        Row {
            TextField(Field.FIRSTNAME, "First name", Modifier.weight(1f))
            Spacer(Modifier.width(12.dp))
            TextField(Field.LASTNAME, "Last name", Modifier.weight(1f))
        }
        Row(verticalAlignment = Alignment.CenterVertically) {
            Text("Age: ${v.age}", style = titleStyle)
            Slider(
                value = v.age.toFloat(),
                onValueChange = { a -> dispatch(ProfileAction.Update(Field.AGE, a.toInt())) },
                valueRange = 0f..120f,
                steps = 119,
                // o slider é solto: o campo foi "deixado"
                onValueChangeFinished = { dispatch(ProfileAction.Leave(Field.AGE)) },
                modifier = Modifier.weight(1f).padding(start = 8.dp),
            )
        }
        ListItem(
            headlineContent = { Text("Receive the newsletter") },
            trailingContent = {
                Switch(checked = v.newsletter, onCheckedChange = { yes -> dispatch(ProfileAction.Update(Field.NEWSLETTER, yes)) })
            },
        )
        TextField(Field.EMAIL, "E-mail (if newsletter)", Modifier.fillMaxWidth())
        DropdownList(
            label = "Country",
            value = v.country,
            choices = countryNames.keys.toList(),
            text = { countryNames.getValue(it) },
            onChange = { c -> dispatch(ProfileAction.Update(Field.COUNTRY, c)) },
            modifier = Modifier.width(220.dp),
        )
        TextField(Field.PRESENTATION, "About you", Modifier.fillMaxWidth(), lines = 2)
        Spacer(Modifier.height(8.dp))
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            OutlinedButton(onClick = { dispatch(ProfileAction.Uppercase) }) { Text("Name in uppercase") }
            OutlinedButton(onClick = { dispatch(ProfileAction.Reset) }) { Text("Reset") }
        }
        Spacer(Modifier.height(8.dp))
        Text("The model, live", style = titleStyle)
        Text(
            indentedJson.encodeToString(JsonObject.serializer(), v.toJson()),
            fontFamily = FontFamily.Monospace,
            fontSize = 12.sp,
            modifier = Modifier.fillMaxWidth().background(Color(0xFFF5F5F5)).padding(8.dp),
        )
        Spacer(Modifier.height(8.dp))
        Text("The state of the fields", style = titleStyle)
        // uma pequena tabela: uma Row por linha, colunas de mesma largura (weight)
        val headers = listOf("field", "touched", "modified", "disabled")
        Row { for (h in headers) Text(h, Modifier.weight(1f), fontWeight = FontWeight.Bold) }
        HorizontalDivider()
        for (f in trackedFields) {
            Row {
                Text(f.name.lowercase(), Modifier.weight(1f))
                Text("${f in state.touched}", Modifier.weight(1f))
                Text("${modified(f)}", Modifier.weight(1f))
                Text("${disabled(f)}", Modifier.weight(1f))
            }
        }
        Spacer(Modifier.height(8.dp))
        // um texto com vários estilos: buildAnnotatedString
        Text(
            buildAnnotatedString {
                append("form modified: ")
                withStyle(SpanStyle(fontWeight = FontWeight.Bold)) { append("$formModified") }
            },
        )
    }
}
  • linha 77: o nome de cada campo, uma lista;
  • linhas 82–113: o perfil, que não pode ser modificado, com duas funções para ler ou substituir o campo designado por seu nome ([v as String]: uma conversão de tipo, verificada em tempo de execução);
  • linhas 117–123: o perfil em JSON: [Field.entries], a lista de valores da enumeração; [associate] gera um [Map]; [is Int]: uma verificação de tipo, após a qual [v] é reconhecido como um [Int] (o “smart cast”);
  • linha 141: o estado completo: os valores e todos os campos já abandonados (“touched”);
  • linhas 145–149: as ações possíveis. [sealed]: não há outras além das declaradas aqui, e o compilador sabe disso. [data object]: uma ação sem dados, um objeto único;
  • linhas 155–161: o reducer: um [when] sobre a ação, sem [else]: o compilador verifica se TODAS as ações são tratadas. Em cada ramo, [action] tem o tipo do ramo: [action.field] é acessível para um [Update];
  • linhas 179–183: o estado e a ÚNICA maneira de alterá-lo, [dispatch(action)];
  • linhas 188–190: valores DEDUZIDOS do estado: um campo é “modificado” se seu valor difere do valor inicial; o e-mail fica desativado sem a newsletter;
  • linhas 195–209: uma função [@Composable] LOCAL (definida dentro de outra): um campo de texto ligado ao modelo. Cada campo tem seu próprio estado ([hadFocus]): ele é “abandonado” quando perde o foco depois de tê-lo tido;
  • linhas 236–241: o controle deslizante de idade: [onValueChangeFinished] é chamada quando ele é solto;
  • linhas 277–285: uma tabela simples, uma [Row] por linha, com colunas de largura igual ([weight(1f)]);
  • linhas 291–293: texto com vários estilos: [buildAnnotatedString].

Image

Image

O reducer é uma função comum: ele pode ser testado sem tela, com um simples teste unitário ([assertEquals(expected, reducer(state, action))]).

3.7. Exemplo 07: validando um formulário manualmente

O formulário “Criar uma conta” do aplicativo RdvMedecins, com as mesmas regras do servidor. Uma função pura, [validate(account)], retorna os erros; eles só são exibidos para os campos já abandonados ou após uma tentativa de envio do formulário.

// =========================================================================
// ex07/Ex07Activity.kt - validando um formulário, à mão
// -------------------------------------------------------------------------
// Uma função PURA, validate(account), retorna os erros dos campos; nós a
// chamamos a cada execução da função @Composable: os erros
// estão portanto sempre atualizados.
// Não os mostramos de imediato (um formulário vazio coberto de vermelho é
// desagradável): somente para um campo já deixado ("touched"). Enviar
// marca todos os campos como tocados, e só age se o formulário
// for válido. Um OutlinedTextField exibe um erro sob o campo quando
// recebe isError = true e um supportingText.
//
// As mesmas regras do servidor RdvMedecins (formulário "Create an account").
// ATENÇÃO: esta validação é apenas uma COMODIDADE para o usuário (uma
// resposta imediata, sem ida e volta ao servidor). Ela não protege
// nada: qualquer pessoa pode enviar ao servidor uma requisição feita à
// mão (curl...). O servidor, portanto, SEMPRE revalida tudo (cf. exemplo 25).
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex07

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.CheckCircle
import androidx.compose.material3.Button
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
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.focus.onFocusChanged
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.input.VisualTransformation
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme

enum class Field { TITLE, FIRSTNAME, LASTNAME, LOGIN, PASSWORD, CONFIRMATION }

// a conta, como digitada
data class Account(
    val title: String,
    val firstName: String,
    val lastName: String,
    val login: String,
    val password: String,
    val confirmation: String,
)

val titles = listOf("Mr", "Mme", "Melle")
val loginFormat = Regex("^[a-z0-9._-]{1,30}$")
const val PASSWORD_MIN = 6

// as regras: uma função pura, que depende apenas de seu argumento. Ela
// retorna, para cada campo com erro, sua mensagem. buildMap: preenchemos
// um Map modificável, a função retorna um Map NÃO MODIFICÁVEL
fun validate(a: Account): Map<Field, String> = buildMap {
    if (a.title !in titles) put(Field.TITLE, "Choose a title from the list.")
    when {
        a.firstName.isBlank() -> put(Field.FIRSTNAME, "The first name is required.")
        a.firstName.length > 20 -> put(Field.FIRSTNAME, "The first name must not exceed 20 characters.")
    }
    when {
        a.lastName.isBlank() -> put(Field.LASTNAME, "The last name is required.")
        a.lastName.length > 20 -> put(Field.LASTNAME, "The last name must not exceed 20 characters.")
    }
    when {
        a.login.isEmpty() -> put(Field.LOGIN, "The login is required.")
        !loginFormat.matches(a.login) -> put(Field.LOGIN, "Unaccented lower-case letters, digits, dot, hyphen, underscore.")
    }
    when {
        a.password.isEmpty() -> put(Field.PASSWORD, "The password is required.")
        a.password.length < PASSWORD_MIN -> put(Field.PASSWORD, "At least $PASSWORD_MIN characters.")
    }
    // uma regra que compara DOIS campos
    if (a.confirmation != a.password) put(Field.CONFIRMATION, "The confirmation does not match the password.")
}

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

@Composable
fun AccountPage() {
    var account by remember { mutableStateOf(Account("Mr", "", "", "", "", "")) }
    var touched by remember { mutableStateOf(setOf<Field>()) }
    var submitAttempted by remember { mutableStateOf(false) }
    var success by remember { mutableStateOf(false) }

    // os erros: recalculados a cada execução, nunca armazenados no estado
    val errors = validate(account)

    // o erro a EXIBIR para um campo: somente se ele foi tocado
    fun error(f: Field): String? = if (f in touched) errors[f] else null

    fun send() {
        submitAttempted = true
        touched = Field.entries.toSet() // todos os erros aparecem
        // aqui, a conta seria enviada ao servidor (cf. exemplo 25)
        success = errors.isEmpty()
    }

    // um campo de texto: rótulo, erro e um sinal de visto verde se ele estiver
    // tocado e válido. value: o valor do campo; update: a função que
    // constrói a conta modificada
    @Composable
    fun AccountField(f: Field, label: String, value: String, update: (String) -> Account, secret: Boolean = false) {
        var hadFocus by remember { mutableStateOf(false) }
        val message = error(f)
        OutlinedTextField(
            value = value,
            onValueChange = { text ->
                account = update(text)
                success = false
            },
            label = { Text(label) },
            singleLine = true,
            isError = message != null,
            supportingText = message?.let { m -> { Text(m) } },
            // os caracteres de uma senha ficam ocultos
            visualTransformation = if (secret) PasswordVisualTransformation() else VisualTransformation.None,
            trailingIcon = if (f in touched && message == null) {
                { Icon(Icons.Default.CheckCircle, contentDescription = null, tint = Color(0xFF2E7D32)) }
            } else {
                null
            },
            // o campo deixado (depois de ter tido o foco) passa a "tocado"
            modifier = Modifier.fillMaxWidth().onFocusChanged { fs ->
                if (fs.isFocused) hadFocus = true else if (hadFocus) touched = touched + f
            },
        )
    }

    ExamplePage("Example 07 - validation") {
        DropdownList(
            label = "Title",
            value = account.title,
            choices = titles,
            onChange = { t -> account = account.copy(title = t) },
            modifier = Modifier.width(200.dp),
        )
        AccountField(Field.FIRSTNAME, "First name", account.firstName, { account.copy(firstName = it) })
        AccountField(Field.LASTNAME, "Last name", account.lastName, { account.copy(lastName = it) })
        AccountField(Field.LOGIN, "Login", account.login, { account.copy(login = it) })
        AccountField(Field.PASSWORD, "Password", account.password, { account.copy(password = it) }, secret = true)
        AccountField(Field.CONFIRMATION, "Confirmation", account.confirmation, { account.copy(confirmation = it) }, secret = true)
        Spacer(Modifier.height(16.dp))
        Button(onClick = { send() }) { Text("Create the account") }
        Spacer(Modifier.height(12.dp))
        if (submitAttempted && errors.isNotEmpty()) {
            Message("The form contains ${errors.size} error(s).", Color(0xFFFFEBEE))
        }
        if (success) {
            Message("Valid form: it could be sent to the server.", Color(0xFFE8F5E9))
        }
    }
}

// um pequeno componente privado deste arquivo: uma mensagem sobre um fundo colorido
@Composable
private fun Message(text: String, color: Color) {
    Text(text, Modifier.fillMaxWidth().background(color, RoundedCornerShape(8.dp)).padding(12.dp))
}
  • linhas 69–70: uma expressão regular ([Regex]) e uma constante;
  • linhas 75–94: as regras. [buildMap [ ... ]]: um [Map] modificável (por meio de [put]) é preenchido; a função retorna um [Map] NÃO modificável. A última regra compara DOIS campos;
  • linha 113: os erros são RECALCULADOS a cada execução, nunca apagados do estado: estão sempre atualizados;
  • linha 116: o erro A EXIBIR para um campo: somente se ele tiver sido modificado;
  • Linhas 118–122: o envio marca todos os campos como tocados (todos os erros são exibidos) e só é bem-sucedido se não houver erros;
  • linhas 129–151: um campo da conta. [update] é uma função que gera a conta modificada ([[ account.copy(firstName = it) ]]); [isError] e [supportingText] exibem o erro abaixo do campo; [PasswordVisualTransformation] mascara os caracteres; um visto verde ([trailingIcon]) para um campo que foi atualizado e é válido;
  • linha 183: [private]: um componente visível apenas neste arquivo.

Image

Image

ATENÇÃO: esta validação é apenas uma COMODIDADE para o usuário (uma resposta imediata, sem ida e volta ao servidor). Ela não protege nada: qualquer pessoa pode enviar ao servidor uma requisição montada manualmente (com o [curl]; veja o capítulo sobre o servidor). O servidor, portanto, SEMPRE revalida tudo (veja o Exemplo 25).

3.8. Exemplo 08: campos que podem se validar sozinhos

O [Flutter] tem seus próprios formulários ([Form], [FormField]); o [Compose] não. Então escrevemos nós mesmos a ferramenta, em apenas algumas linhas, usando classes comuns que MANTÊM um estado observado pelo [Compose] (“state holders”): essa é a abordagem padrão com o [Compose].

// =========================================================================
// ex08/Form.kt - campos que podem se validar sozinhos
// -------------------------------------------------------------------------
// O Compose não fornece nenhuma ferramenta de formulário (nada equivalente ao Form
// do Flutter ou aos formulários do Angular): nós mesmos a escrevemos, em
// poucas linhas, com classes comuns que MANTÊM um estado
// observado pelo Compose ("state holders"):
//   - uma REGRA é uma função: (value) -> null se o valor estiver correto,
//     senão a mensagem de erro;
//   - um FormField guarda seu valor e seu erro, e se valida sozinho:
//     primeiro sob demanda (validate()), depois a cada tecla digitada, assim que
//     o usuário o modificou;
//   - um Form agrupa campos: validate() valida TODOS eles,
//     exibe seus erros e retorna true se tudo estiver correto.
// =========================================================================
package fr.stahe.examples.ex08

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue

// typealias: um nome mais expressivo para um tipo de função
typealias Rule = (String) -> String?

// FÁBRICAS de regras: cada uma retorna uma função de validação
fun required(message: String): Rule = { v -> if (v.isBlank()) message else null }

// uma regra que COMPLETA outra: "?:" (o operador Elvis) dá o
// resultado de other, se ele não for null, senão o do restante
fun maximum(max: Int, other: Rule): Rule = { v -> other(v) ?: if (v.length > max) "$max characters at most." else null }

class FormField(initialValue: String = "", private val rule: Rule = { null }) {
    // o estado do campo: observado pelo Compose, modificável somente AQUI (private set)
    var value by mutableStateOf(initialValue)
        private set
    var error by mutableStateOf<String?>(null)
        private set

    // o usuário já modificou o campo?
    private var modified = false

    // uma tecla digitada: o campo se valida assim que o usuário o modificou
    fun change(newValue: String) {
        value = newValue
        modified = true
        error = rule(value)
    }

    fun validate(): Boolean {
        error = rule(value)
        return error == null
    }

    // revalida, somente se o usuário já modificou o campo
    fun revalidate() {
        if (modified) validate()
    }
}

// vararg: qualquer número de campos, Form(firstName, lastName, login...)
class Form(private vararg val fields: FormField) {
    // map primeiro (TODOS os campos são validados e exibem seu erro),
    // all depois (todos estão corretos?)
    fun validate(): Boolean = fields.map { it.validate() }.all { it }
}
  • linha 23: [typealias]: um nome para um tipo de função: uma REGRA recebe o valor e retorna [null] se ele for válido; caso contrário, retorna uma mensagem de erro;
  • linhas 26–30: FÁBRICAS de regras (funções que retornam uma função). [?:], o operador “Elvis”: o valor à esquerda se não for [null]; caso contrário, o valor à direita;
  • linhas 32–56: um campo: seu valor e seu erro são estados do [Compose] ([mutableStateOf]) que só podem ser modificados de dentro da classe ([private set]). Um campo é validado sob demanda ([validate()]) e depois a cada tecla digitada, uma vez que o usuário o tenha modificado;
  • linhas 61–64: um formulário agrupa campos ([vararg]: qualquer número de parâmetros). Primeiro, [map]: TODOS os campos são validados e exibem seus eventuais erros; depois, [all]: todos são válidos?

O Exemplo 07, reescrito com essas classes:

// =========================================================================
// ex08/Ex08Activity.kt - um formulário reutilizável
// -------------------------------------------------------------------------
// O formulário do exemplo 07, escrito com as classes de Form.kt:
// as regras são associadas aos campos, a tela só precisa exibir
// cada campo e chamar form.validate() no envio.
// Os campos são guardados em uma classe, AccountForm, criada UMA ÚNICA VEZ
// (remember): ela sobrevive às recomposições.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex08

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Button
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
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.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.input.VisualTransformation
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive

val titles = listOf("Mr", "Mme", "Melle")

// os campos do formulário e suas regras
class AccountForm {
    var title by mutableStateOf("Mr")
    val firstName = FormField(rule = maximum(20, required("The first name is required.")))
    val lastName = FormField(rule = maximum(20, required("The last name is required.")))

    // uma regra escrita diretamente: uma lambda
    val login = FormField(
        rule = { v ->
            when {
                v.isEmpty() -> "The login is required."
                !Regex("^[a-z0-9._-]{1,30}$").matches(v) -> "Unaccented lower-case letters, digits, dot, hyphen, underscore."
                else -> null
            }
        },
    )
    val password = FormField(
        rule = { v ->
            when {
                v.isEmpty() -> "The password is required."
                v.length < 6 -> "At least 6 characters."
                else -> null
            }
        },
    )

    // uma regra que lê OUTRO campo
    val confirmation = FormField(
        rule = { v -> if (v == password.value) null else "The confirmation does not match the password." },
    )
    val form = Form(firstName, lastName, login, password, confirmation)

    // os valores, em JSON (o que seria enviado ao servidor)
    fun toJson(): String = JsonObject(
        mapOf(
            "title" to JsonPrimitive(title),
            "firstName" to JsonPrimitive(firstName.value.trim()),
            "lastName" to JsonPrimitive(lastName.value.trim()),
            "login" to JsonPrimitive(login.value),
            "password" to JsonPrimitive(password.value),
        ),
    ).toString()
}

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

@Composable
fun AccountPage() {
    val account = remember { AccountForm() }
    // null: nenhum envio ainda; "": envio rejeitado; caso contrário, o JSON enviado
    var sent by remember { mutableStateOf<String?>(null) }

    ExamplePage("Example 08 - a reusable form") {
        DropdownList(
            label = "Title",
            value = account.title,
            choices = titles,
            onChange = { account.title = it },
            modifier = Modifier.width(200.dp),
        )
        TextField(account.firstName, "First name")
        TextField(account.lastName, "Last name")
        TextField(account.login, "Login")
        // a senha muda: a confirmação é revalidada (se já tiver sido digitada)
        TextField(account.password, "Password", secret = true, after = { account.confirmation.revalidate() })
        TextField(account.confirmation, "Confirmation", secret = true)
        Spacer(Modifier.height(16.dp))
        Button(onClick = { sent = if (account.form.validate()) account.toJson() else "" }) {
            Text("Create the account")
        }
        Spacer(Modifier.height(12.dp))
        // ?.let: este bloco só existe se sent não for null
        sent?.let { s ->
            Text(
                if (s.isEmpty()) "Invalid form." else "Valid form: $s",
                Modifier
                    .fillMaxWidth()
                    .background(if (s.isEmpty()) Color(0xFFFFEBEE) else Color(0xFFE8F5E9), RoundedCornerShape(8.dp))
                    .padding(12.dp),
            )
        }
    }
}

// a exibição de um FormField: seu valor, seu erro. after: o que deve
// ser feito após cada tecla digitada (nada, por padrão)
@Composable
fun TextField(field: FormField, label: String, secret: Boolean = false, after: () -> Unit = {}) {
    OutlinedTextField(
        value = field.value,
        onValueChange = {
            field.change(it)
            after()
        },
        label = { Text(label) },
        singleLine = true,
        isError = field.error != null,
        supportingText = field.error?.let { m -> { Text(m) } },
        visualTransformation = if (secret) PasswordVisualTransformation() else VisualTransformation.None,
        modifier = Modifier.fillMaxWidth(),
    )
}
  • Linhas 48–77: os campos do formulário e suas regras, agrupados em uma classe; a confirmação tem uma regra que lê OUTRO campo ([password.value]);
  • linha 101: [remember [ AccountForm() ]]: o objeto é criado UMA ÚNICA VEZ e sobrevive às recomposições;
  • linha 120: envio: [account.form.validate()] valida tudo e determina se o envio é possível;
  • linhas 140–152: exibição de um campo: seu valor, seu erro e [after], que especifica o que fazer após cada tecla digitada: quando a senha muda, a confirmação é revalidada.

Image

Image

3.9. Exemplo 09: formatando valores

Em uma função [@Composable], os valores são formatados com funções padrão. As funções usadas no aplicativo são reunidas em um único arquivo:

// =========================================================================
// ex09/Formatting.kt - funções de formatação "caseiras"
// -------------------------------------------------------------------------
// O Compose não tem mecanismo próprio de formatação (o Angular tem seus
// "pipes"): em uma função @Composable, chamamos
// FUNÇÕES comuns, guardadas em um arquivo e testáveis separadamente:
//     timeRange(slot)                -> "8:00 - 8:20"
//     timeRange(slot, Part.START)    -> "8:00"
// O Kotlin também permite ADICIONAR funções e propriedades a um
// tipo existente, por meio de EXTENSÕES: "marie pelissier".capitalized ->
// "Marie Pelissier".
// Para datas, números, valores monetários, as classes Java
// (java.time, java.text) conhecem as convenções de cada idioma
// (cf. Ex09Activity.kt).
// =========================================================================
package fr.stahe.examples.ex09

// um intervalo de horário, como descrito pela API RdvMedecins
data class Slot(val startHour: Int, val startMinute: Int, val endHour: Int, val endMinute: Int)

enum class Part { ALL, START, END }

// "8:05" em vez de "8:5"; private: invisível fora deste arquivo
private fun time(h: Int, m: Int) = "$h:${m.toString().padStart(2, '0')}"

// um parâmetro OPCIONAL, com seu valor padrão: part = Part.ALL
fun timeRange(s: Slot, part: Part = Part.ALL): String = when (part) {
    Part.START -> time(s.startHour, s.startMinute)
    Part.END -> time(s.endHour, s.endMinute)
    Part.ALL -> "${time(s.startHour, s.startMinute)} - ${time(s.endHour, s.endMinute)}"
}

// EXTENSÕES do tipo String: novas propriedades para TODAS as
// strings. No corpo, this designa a string
// "marie pelissier" -> "Marie Pelissier"; \p{L}: uma letra, acentuada ou não
val String.capitalized: String
    get() = Regex("\\p{L}+").replace(this) { m ->
        m.value.lowercase().replaceFirstChar { it.uppercase() }
    }

// "Marie PELISSIER" -> "MP"
val String.initials: String
    get() = split(Regex("\\s+")).filter { it.isNotEmpty() }.joinToString("") { it.first().uppercase() }
  • linhas 24–30: um parâmetro OPCIONAL, com seu valor padrão ([part = Part.ALL]); [padStart(2, '0')]: “8:05” em vez de “8:5”;
  • Linhas 36–43: EXTENSÕES: o [Kotlin] permite atribuir propriedades (e funções) a um tipo existente, neste caso, a todas as strings. No corpo, [this] se refere à string: ["marie pelissier".capitalized] resulta em “Marie Pelissier”.

Para datas, números e valores monetários, as classes do [Java] ([java.time], [java.text]) seguem as convenções de cada idioma:

// =========================================================================
// ex09/Ex09Activity.kt - formatando valores
// -------------------------------------------------------------------------
// Cada linha da tabela mostra um trecho de código e o que ele exibe.
// Os formatadores (DateTimeFormatter, NumberFormat) são criados uma vez por
// todas, fora das funções @Composable: construí-los custa mais
// do que usá-los.
// O Java conhece desde o início os nomes dos dias e dos meses de cada idioma:
// nada a carregar antes de usá-los.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex09

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.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.HorizontalDivider
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.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.text.font.FontFamily
import androidx.compose.ui.text.font.FontWeight
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 kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import java.text.NumberFormat
import java.time.LocalDate
import java.time.LocalDateTime
import java.time.format.DateTimeFormatter
import java.time.format.FormatStyle
import java.util.Locale

// datas: formatos "prontos" (SHORT, MEDIUM, LONG, FULL), ou um padrão
val shortDate: DateTimeFormatter = DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM).withLocale(Locale.US)
val fullDate: DateTimeFormatter = DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(Locale.US)
val timeOnly: DateTimeFormatter = DateTimeFormatter.ofLocalizedTime(FormatStyle.MEDIUM).withLocale(Locale.US)
val frenchDay: DateTimeFormatter = DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG).withLocale(Locale.FRANCE)
val pattern: DateTimeFormatter = DateTimeFormatter.ofPattern("MM/dd/yyyy HH:mm", Locale.US)

// números e valores monetários
val euros: NumberFormat = NumberFormat.getCurrencyInstance(Locale.US).apply { currency = java.util.Currency.getInstance("EUR") }
val integer: NumberFormat = NumberFormat.getNumberInstance(Locale.US)

// apply: configura o objeto recém-criado e o retorna
val percent: NumberFormat = NumberFormat.getPercentInstance(Locale.US).apply { minimumFractionDigits = 1 }

const val DAY = "2026-10-05" // uma data no formato da API RdvMedecins
const val PRICE = 1234.5
const val RATE = 0.055
const val NAME = "marie pelissier"
val doctor = mapOf("title" to "Mme", "firstName" to "Marie", "lastName" to "PELISSIER")
val languages = listOf("Kotlin", "Compose", "Dart", "Swift", "SQL")
val slots = listOf(Slot(8, 0, 8, 20), Slot(8, 20, 8, 40), Slot(14, 5, 14, 25))

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

@Composable
fun FormattingPage() {
    var now by remember { mutableStateOf(LocalDateTime.now()) }

    // (código exibido, valor): uma linha da tabela, como um par
    val rows = listOf(
        "shortDate.format(now)" to shortDate.format(now),
        "fullDate.format(now)" to fullDate.format(now),
        "timeOnly.format(now)" to timeOnly.format(now),
        "pattern.format(now)" to pattern.format(now),
        "fullDate.format(LocalDate.parse(DAY))" to fullDate.format(LocalDate.parse(DAY)),
        "frenchDay.format(LocalDate.parse(DAY))" to frenchDay.format(LocalDate.parse(DAY)),
        "now.toString()" to now.toString(),
        "euros.format(PRICE)" to euros.format(PRICE),
        "integer.format(PRICE)" to integer.format(PRICE),
        "\"%.1f\".format(Locale.ROOT, PRICE)" to "%.1f".format(Locale.ROOT, PRICE),
        "percent.format(RATE)" to percent.format(RATE),
        "NAME.uppercase()" to NAME.uppercase(),
        "NAME.capitalized" to NAME.capitalized,
        "\"RDV\".lowercase()" to "RDV".lowercase(),
        "languages.take(3).joinToString(\", \")" to languages.take(3).joinToString(", "),
        "JsonObject(...).toString()" to JsonObject(doctor.mapValues { JsonPrimitive(it.value) }).toString(),
        // duas transformações seguidas: o resultado da primeira vai para a segunda
        "NAME.capitalized.initials" to NAME.capitalized.initials,
    )

    ExamplePage("Example 09 - formatting") {
        // uma tabela: a primeira coluna ocupa 55 % da largura (weight)
        Row(Modifier.padding(4.dp)) {
            Text("In the code", Modifier.weight(0.55f), fontWeight = FontWeight.Bold)
            Text("Displayed", Modifier.weight(0.45f), fontWeight = FontWeight.Bold)
        }
        // um par pode ser "desestruturado": (code, value)
        for ((code, value) in rows) {
            HorizontalDivider()
            Row(Modifier.padding(4.dp)) {
                Text(code, Modifier.weight(0.55f), fontFamily = FontFamily.Monospace, fontSize = 11.sp, color = Color(0xFFC7254E))
                Text(value, Modifier.weight(0.45f))
            }
        }
        Spacer(Modifier.height(16.dp))
        Text("Going through the entries of a Map", style = MaterialTheme.typography.titleSmall)
        for ((key, value) in doctor) {
            Text("$key = $value")
        }
        Spacer(Modifier.height(16.dp))
        Text("A home-made function: timeRange", style = MaterialTheme.typography.titleSmall)
        for (s in slots) {
            Text("${timeRange(s)} (start: ${timeRange(s, Part.START)})")
        }
        Spacer(Modifier.height(16.dp))
        OutlinedButton(onClick = { now = LocalDateTime.now() }) { Text("Refresh the time") }
    }
}
  • linhas 51–62: os formatadores, criados de uma vez por todas fora das funções [@Composable] (criá-los custa mais do que usá-los). [FormatStyle.MEDIUM], [FULL]...: formatos “prontos”; [ofPattern]: um padrão; [apply [ ... ]] configura o objeto recém-criado e o retorna;
  • linhas 85–103: cada linha da tabela é um par (código exibido, valor), gerado por [to];
  • linha 113: um par, como uma entrada de [Map], é “desempacotado”: [for ((code, value) in rows)].

Image

Image

Observe ["%.1f".format(Locale.ROOT, PRICE)]: sem o idioma “neutro” [Locale.ROOT], [format] usaria o idioma do celular e escreveria “1234,5” em francês. É o que se deseja para exibição, não para dados enviados a um servidor.