# Arquivos e "preferências"

> A persistência leve foi removida — o que usar no lugar (SQLite kv ou arquivo em homeFolder).

Source: https://crossfly.dev/pt/docs/data-and-services/files-and-preferences — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Arquivos e "preferências"

Esta página é **honesta sobre uma remoção**. Se você procura `SharedPreferences`/`UserDefaults`, pare:
no CrossFly esse mecanismo **não existe**.

## ⚠️ A persistência leve foi removida
`Settings.appSettings`, `appSecretKey`, `refresh()` e o antigo "preferências" **não existem mais** — e
**não há gravação automática ao sair**. Você grava **explicitamente**, no momento certo.

## O que usar no lugar
| Precisa guardar… | Use |
|---|---|
| flags, tema, último login (chave→valor) | **tabela chave/valor em SQLite** ([guia](/docs/data-and-services/storage-sqlite)) |
| blobs / arquivos | um **arquivo** em `Device.homeFolder` |

### Chave/valor em SQLite (recomendado para configurações)
```java
try (SqliteDb db = SqliteDb.open("app.db")) {
   db.exec("CREATE TABLE IF NOT EXISTS kv(k TEXT PRIMARY KEY, v TEXT)");
   db.execute("INSERT OR REPLACE INTO kv(k, v) VALUES(?, ?)", "tema", "escuro");
   String tema = db.queryString("SELECT v FROM kv WHERE k=?", "tema");   // null se ausente
}
```

### Arquivo simples em `Device.homeFolder`
`Device.homeFolder` é o diretório base da app (varia por plataforma):
| Plataforma | `homeFolder` |
|---|---|
| Desktop | diretório de trabalho (cwd) |
| Android | armazenamento privado da app |
| iOS | pasta *documents* |

```java
String path = Device.homeFolder + "config.json";

byte[] bytes = Utils.readBytes(path);   // ⚠️ null se o arquivo não existe
if (bytes != null) {
   String json = new String(bytes);
   // … parse …
}
// FileHandle (libGDX) para casos que precisam de mais controle:
FileHandle fh = Utils.loadFile(path);   // null se não encontrado
```

## Boas práticas
- **Grave explicitamente** nos pontos certos (ao salvar config, ao sair de uma tela) — nada é
  persistido sozinho.
- Prefira **SQLite kv** a arquivo solto para configurações (transacional, consultável).
- **Sempre cheque `null`** de `Utils.readBytes`/`loadFile` (arquivo pode não existir).

## Erros comuns
- Procurar `Settings.appSettings`/`SharedPreferences` — foi removido; não volta.
- Assumir gravação automática ao fechar — não há; grave você mesmo.
- Não tratar `null` ao ler um arquivo inexistente.

## Veja também
- [Persistência com SQLite](/docs/data-and-services/storage-sqlite)