aylis_core/providers.rs
1//! Provedores (item 25): o que depende de projeto de terceiros vira um par. O componente que o
2//! app usa diz **o que** faz (o `Barcode`, o `Export`, o `Report`, o `MapView`, com as
3//! propriedades e os eventos de sempre); um componente provedor diz **quem** faz (com a
4//! biblioteca). O componente aponta o provedor pela propriedade `provider`, como o
5//! `data_source` aponta o dataset; sem provedor ligado, vale o provedor padrão do Aylis (não é
6//! erro). Trocar de biblioteca é trocar o provedor; um formato novo é um provedor novo; o app
7//! só leva o código dos provedores que os forms usam (o `aylis-build` registra por classe).
8//!
9//! Um contrato (trait) por assunto, aqui no núcleo (sem nada de sistema nem de biblioteca):
10//! [`BarcodeProvider`], [`ExportProvider`], [`PdfProvider`] e [`MapTileProvider`]. O
11//! componente provedor devolve o seu em [`Component::provided`](crate::Component::provided).
12
13use crate::pages::{Page, PageSet};
14use crate::ui::Ui;
15use crate::component::ComponentId;
16
17/// O que um componente provedor oferece (um assunto por vez).
18#[derive(Clone, Copy)]
19pub enum Provided<'a> {
20 Barcode(&'a dyn BarcodeProvider),
21 Export(&'a dyn ExportProvider),
22 Pdf(&'a dyn PdfProvider),
23 MapTiles(&'a dyn MapTileProvider),
24 MediaTags(&'a dyn MediaTagsProvider),
25}
26
27// ---------------------------------------------------------------------------
28// Códigos de barras
29
30/// Um código pronto para desenhar.
31#[derive(Clone, Debug, PartialEq, Eq)]
32pub enum BarcodeImage {
33 /// De barras (1D): os módulos da esquerda para a direita (`true` = barra escura), e o
34 /// texto legível que vai embaixo.
35 Linear { modules: Vec<bool>, text: String },
36 /// Em matriz (2D, como o QR Code): `width` módulos por linha, linha a linha.
37 Matrix { width: usize, modules: Vec<bool> },
38}
39
40/// O nível de correção de erro de um código em matriz (o QR Code): quanto do código pode
41/// estar estragado (sujo, rasgado, com um logo por cima) e ainda ser lido. Mais correção é
42/// um código maior para o mesmo dado.
43#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
44pub enum ErrorCorrection {
45 /// L: cerca de 7%.
46 Low,
47 /// M: cerca de 15% (o padrão).
48 #[default]
49 Medium,
50 /// Q: cerca de 25%.
51 Quartile,
52 /// H: cerca de 30%.
53 High,
54}
55
56impl crate::prop::PropEnum for ErrorCorrection {
57 const NAMES: &'static [&'static str] = &["low", "medium", "quartile", "high"];
58
59 fn from_index(index: usize) -> Option<Self> {
60 [ErrorCorrection::Low, ErrorCorrection::Medium, ErrorCorrection::Quartile, ErrorCorrection::High].get(index).copied()
61 }
62
63 fn index(self) -> usize {
64 self as usize
65 }
66}
67
68/// O que o componente pede além do formato e do dado (o provedor usa o que o formato tem).
69#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
70pub struct BarcodeOptions {
71 /// A correção de erro dos códigos em matriz (o QR Code); os de barras não têm.
72 pub error_correction: ErrorCorrection,
73}
74
75/// Quem gera os códigos de barras.
76pub trait BarcodeProvider {
77 /// Os formatos que sabe gerar (`code128`, `ean13`, `qr`...), em minúsculas.
78 fn formats(&self) -> Vec<&'static str>;
79 /// O código de `data` no formato `format`, com as opções do componente. Dado que não cabe
80 /// no formato: `Err` com o motivo (o controle mostra o motivo no lugar do código).
81 fn encode(&self, format: &str, data: &str, options: &BarcodeOptions) -> Result<BarcodeImage, String>;
82}
83
84// ---------------------------------------------------------------------------
85// Exportação de tabelas (planilha, CSV...)
86
87/// O tipo de uma coluna exportada.
88#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
89pub enum ColumnKind {
90 #[default]
91 Text,
92 Integer,
93 /// Número com casas (dinheiro, quantidade).
94 Number,
95 Date,
96 DateTime,
97 Bool,
98}
99
100/// Um valor de uma célula exportada.
101#[derive(Clone, Debug, PartialEq)]
102pub enum CellValue {
103 Empty,
104 Text(String),
105 Number(f64),
106 Bool(bool),
107 /// Data (ano, mês, dia).
108 Date(i32, u32, u32),
109 /// Data e hora (ano, mês, dia, hora, minuto, segundo).
110 DateTime(i32, u32, u32, u32, u32, u32),
111}
112
113/// Uma coluna: o título, o tipo e o formato de exibição (`#,##0.00`; vazio: o padrão).
114#[derive(Clone, Debug, Default, PartialEq)]
115pub struct ExportColumn {
116 pub title: String,
117 pub kind: ColumnKind,
118 pub format: String,
119}
120
121/// Uma tabela para exportar (uma aba da planilha).
122#[derive(Clone, Debug, Default, PartialEq)]
123pub struct ExportTable {
124 pub name: String,
125 pub columns: Vec<ExportColumn>,
126 pub rows: Vec<Vec<CellValue>>,
127}
128
129/// Quem grava tabelas num formato de arquivo.
130pub trait ExportProvider {
131 /// A extensão do arquivo, sem o ponto (`xlsx`, `csv`).
132 fn extension(&self) -> &'static str;
133 /// O tipo do conteúdo (`text/csv`...).
134 fn mime(&self) -> &'static str;
135 /// O arquivo com as tabelas (uma aba por tabela, onde o formato tem abas).
136 fn write(&self, tables: &[ExportTable]) -> Result<Vec<u8>, String>;
137}
138
139// ---------------------------------------------------------------------------
140// PDF
141
142/// Quem transforma as páginas gravadas (um relatório) em PDF. O documento é montado página
143/// por página ([`PdfProvider::begin`]): um relatório enorme não precisa de todas as páginas na
144/// memória ao mesmo tempo. O padrão (sem provedor ligado no `Report`) é o de
145/// [`Services::pdf`](crate::Services::pdf), que o `aylis-providers` põe (o `KrillaPdfProvider`);
146/// o núcleo não escreve PDF (decidido pelo autor em 15/11).
147pub trait PdfProvider {
148 /// Começa um documento com páginas de `width` × `height` pontos.
149 fn begin(&self, width: f32, height: f32) -> Result<Box<dyn PdfDocument>, String>;
150
151 /// O PDF de todas as páginas de uma vez.
152 fn write(&self, pages: &PageSet) -> Result<Vec<u8>, String> {
153 let mut doc = self.begin(pages.width, pages.height)?;
154 for page in &pages.pages {
155 doc.add_page(page)?;
156 }
157 doc.finish()
158 }
159}
160
161/// Um PDF sendo montado ([`PdfProvider::begin`]).
162pub trait PdfDocument {
163 fn add_page(&mut self, page: &Page) -> Result<(), String>;
164 /// Os bytes do arquivo.
165 fn finish(self: Box<Self>) -> Result<Vec<u8>, String>;
166}
167
168// ---------------------------------------------------------------------------
169// Mapas
170
171/// Quem fornece as imagens (tiles) do mapa.
172pub trait MapTileProvider {
173 /// O endereço da imagem do quadro `x`, `y` no nível de zoom `z`.
174 fn tile_url(&self, z: u32, x: u32, y: u32) -> String;
175 /// O crédito que o mapa mostra no canto (exigido pela maioria dos servidores).
176 fn attribution(&self) -> String;
177}
178
179/// Um servidor de blocos pelo endereço: `url` com `{z}`, `{x}` e `{y}` (e `{s}`, trocado por
180/// `a`, `b` ou `c` para dividir os pedidos), e o crédito que a licença dele pede. O padrão é
181/// o OpenStreetMap, o que o `MapView` usa sem provedor ligado; o `TileServerProvider` é este
182/// como componente (outro servidor é só outro endereço nele).
183#[derive(Clone, Debug, PartialEq, Eq)]
184pub struct TileServer {
185 pub url: String,
186 pub attribution: String,
187}
188
189impl Default for TileServer {
190 fn default() -> Self {
191 Self { url: "https://tile.openstreetmap.org/{z}/{x}/{y}.png".into(), attribution: "© OpenStreetMap".into() }
192 }
193}
194
195impl TileServer {
196 /// O endereço do bloco a partir do modelo (`{z}`, `{x}`, `{y}` e `{s}`).
197 pub fn expand(template: &str, z: u32, x: u32, y: u32) -> String {
198 let shard = ["a", "b", "c"][((x + y) % 3) as usize];
199 template.replace("{z}", &z.to_string()).replace("{x}", &x.to_string()).replace("{y}", &y.to_string()).replace("{s}", shard)
200 }
201}
202
203impl MapTileProvider for TileServer {
204 fn tile_url(&self, z: u32, x: u32, y: u32) -> String {
205 Self::expand(&self.url, z, x, y)
206 }
207
208 fn attribution(&self) -> String {
209 self.attribution.clone()
210 }
211}
212
213// ---------------------------------------------------------------------------
214
215impl Ui {
216 /// O que o componente `id` provê (um componente provedor), se for um.
217 pub fn provided(&self, id: ComponentId) -> Option<Provided<'_>> {
218 self.component(id)?.provided()
219 }
220}
221
222// ---------------------------------------------------------------------------
223// Tags de mídia
224
225/// O que se lê de um arquivo de áudio ou vídeo: as tags, a duração e a capa embutida (o
226/// `MediaInfo`; decidido em 21/11: um componente com provedor, não propriedades do player).
227#[derive(Clone, Debug, Default, PartialEq)]
228pub struct MediaTags {
229 pub title: String,
230 pub artist: String,
231 pub album: String,
232 /// O número da faixa no álbum (0: sem).
233 pub track: u32,
234 /// O ano (0: sem).
235 pub year: u32,
236 /// Em segundos (0: não se sabe).
237 pub duration: f64,
238 /// A imagem embutida (a capa do álbum), como está no arquivo (PNG, JPEG).
239 pub cover: Option<Vec<u8>>,
240}
241
242/// De onde ler: um caminho do disco ou os bytes (um arquivo do projeto), com a extensão.
243#[derive(Clone, Debug)]
244pub enum MediaInput {
245 Path(String),
246 Bytes(Vec<u8>, String),
247}
248
249/// Quem lê as tags: roda em outra thread (uma playlist inteira em segundo plano).
250pub type TagReader = std::sync::Arc<dyn Fn(&MediaInput) -> Result<MediaTags, String> + Send + Sync>;
251
252/// O provedor de tags de mídia: devolve o leitor (que vai para outra thread).
253pub trait MediaTagsProvider {
254 fn tag_reader(&self) -> TagReader;
255}